%InstallerでInterSystems Cachéにアプリケーションをデプロイする
InterSystemsのテクノロジースタックを使用して独自のアプリを開発し、顧客側で複数のデプロイを実行したいとします。 開発プロセスでは、クラスをインポートするだけでなく、必要に応じて環境を微調整する必要があるため、アプリケーションの詳細なインストールガイドを作成しました。この特定のタスクに対処するために、インターシステムズは、%Installer(Caché/Ensemble)という特別なツールを作成しました 。 続きを読んでその使用方法を学んでください。
%Installer
このツールを使用すると、インストール手順ではなく、目的のCaché構成を記述するインストールマニフェストを定義できます。作成したい Caché 構成を記述します。必要な内容を記述するだけで、環境を変更するために必要なコードが自動的に生成されます。
したがって、マニフェストのみを配布する必要がありますが、インストール・コードはすべてコンパイル時に特定の Caché サーバ用に生成されます。
マニフェストを定義するには、ターゲット構成の詳細な説明を含む新しいXDataブロックを作成してから、このXDataブロックのCaché ObjectScriptコードを生成するメソッドを実装します(このコードは常に同じです)。 マニフェストの準備ができたら、ターミナルまたはCaché ObjectScriptコードから、またはCachéのインストール中に自動的にアクセスできます。 マニフェストは %SYSネームスペースで実行する必要があります。 マニフェストは、システムパラメータ(スーパーサーバポート、OS、mgrディレクトリなど)とユーザーが提供した任意のパラメータの両方を処理できます。 一般に、各インストールクラスは次の要件を満たしている必要があります。
- %occInclude.incへのリンクを含むこと
- Cachéサーバー構成のXDataブロックを含むこと
- ブロックには任意の有効な名前を付けること
- スタジオでブロックの名前の後に[XMLNamespace = INSTALLER]を追加すること
- ルートアイテム(1つのみである必要があります)は<Manifest>と呼ばれ、他のすべてのアイテムを含むように記述すること
- また、XDataブロックに必要なプログラムコードを生成するsetup()メソッドを実装すること
インストーラーの基本
複数の方法でインストールマニフェストを実行できます。
- ターミナルを使用して%SYSネームスペースで、またはCachéObjectScriptコードから以下実行します。
do ##class(MyPackage.MyInstaller).setup()
- Cachéのインストール中に自動的に実行されます。 これを行うには、インストーラーのクラスを、Cachéインストールパッケージ(すなわち、 setup_cache.exeまたはcinstallが格納されている場所)のフォルダー内に格納されているDefaultInstallerClass.xmlにエクスポートする必要があります。 このクラスは、Cachéのインストール中に%SYSネームスペースにインポートされ、 setup() メソッドを介して実行されます。
例:
簡単な例を考えてみましょう。
ユーザー定義の名前で新しいネームスペースを作成し、デフォルトのWebアプリを作成し、作成したネームスペースにコードをインポートするインストーラーを含む App.Installerというクラスを作成します。
XData Install [ XMLNamespace = INSTALLER ]
{
<Manifest>
<If Condition='(##class(Config.Namespaces).Exists("${Namespace}")=0)'>
<Log Text="Creating namespace ${Namespace}" Level="0"/>
<Namespace Name="${Namespace}" Create="yes" Code="${Namespace}" Ensemble="0" Data="${Namespace}">
<Configuration>
<Database Name="${Namespace}" Dir="${MGRDIR}${Namespace}" Create="yes"/>
</Configuration>
</Namespace>
<Log Text="End Creating namespace ${Namespace}" Level="0"/>
</If>
<Role Name="AppRole" Description="Role to access and use the App" Resources="%DB_CACHESYS:RW,%Admin_Secure:U" />
<Namespace Name="${Namespace}" Create="no">
<CSPApplication Url="/csp/${Namespace}" Directory="${CSPDIR}${Namespace}" AuthenticationMethods="64" IsNamespaceDefault="true" Grant="AppRole" />
<IfDef Var="SourceDir">
<Log Text="SourceDir defined - offline install from ${SourceDir}" Level="0"/>
<Import File="${SourceDir}"/>
</IfDef>
</Namespace>
</Manifest>
}
///Entry point method, you need to call
/// At class compile time it generate Caché ObjectScript code from the manifest
/// After that you can run this installer from a terminal:
/// Set pVars("Namespace")="NewNamespace"
/// Set pVars("SourceDir")="C:\temp\distr\"
/// Do ##class(App.Installer).setup(.pVars)
ClassMethod setup(ByRef pVars, pLogLevel As %Integer = 0, pInstaller As %Installer.Installer) As %Status [ CodeMode = objectgenerator, Internal ]
{
Quit ##class(%Installer.Manifest).%Generate(%compiledclass, %code, "Install")
}
}
この例では、インストーラーは次のアクションを実行します。
- Namespace変数の値と同じ名前のネームスペースが存在するかどうかを確認します(明確にするために、Namespace変数がNewNamespaceに設定されていることを指定しましょう)
- そうでなければ、NewNamespaceという新しいネームスペースが作成されることをログに記録します。
- 新しいネームスペースを定義します。
- 名前はNewNamespaceです
- 新しいネームスペースを作成します
- ルーチンデータベースはNewNamespaceです
- Ensembleを有効にしないでください
- ルーチンデータベースはNewNamespaceです
- 新しいデータベースを作成します
- 名前はNewNamespaceです;
- それを mgr/NewNamespaceフォルダーに作成します(MGRDIR変数はデフォルトで使用可能であることに注意してください)
- ネームスペースの作成が完了し、ログに記録されます。
- 新しいロールを次のように作成します。 AppRole(リソース %DB_CACHESYS:RW および %Admin_Secure:U を設定)
- デフォルトのWebアプリケーション /csp/NewNamespace が作成されます(Grant 属性により、AppRole が設定されます)
- SourceDir変数が定義されている場合、そこからすべてのファイルをNewNamespaceにインポートします。
このインストーラーをターミナルで実行するには、次のコマンドを実行します。
Set pVars("Namespace")="NewNamespace" Set pVars("SourceDir")="C:\temp\distr\" Do ##class(App.Installer).setup(.pVars)
実行中、ターミナルは次の関連情報を表示します。
2016-02-17 19:26:17 0 : Creating namespace NewNamespace
2016-02-17 19:26:17 0 : End Creating namespace NewNamespace
2016-02-17 19:26:17 0 : SourceDir defined - offline install from C:\temp\distr\
2016-02-17 19:26:18 0 App.Installer: Installation succeeded at 2016-02-17 19:26:18
2016-02-17 19:26:18 0 %Installer: Elapsed time .545148s
発生していることについて多くの情報を取得するためには、LogLevelを指定します(0(デフォルト)から3(未加工)、数値が大きければ大きいほどより詳細な情報が得られます)。
Do ##class(App.Installer).setup(.pVars, 3)
次に、インストーラマニフェストで実行できることについて説明します。
利用可能なノード
マニフェストは次のアイテムで構成されています。
ノード |
親ノード |
属性(デフォルト値) |
説明 |
Arg |
Invoke、Error |
Value – 引数の値 |
InvokeまたはError経由で呼び出されるたメソッドに引数を渡します |
ClassMapping |
Configuration |
Package –マッピングされるパッケージ |
データベースからこの構成項目を含むネームスペースへのクラスマッピングを作成します。 |
Compile |
Namespace |
Class –コンパイルするクラスの名 |
コンパイラクラス。 $System.OBJ.Compile(Class, Flags)を呼び出す |
Configuration |
Namespace |
|
ネームスペースとデータベースの作成に使用されます。 タグを閉じるとマッピングがアクティブになり、CPFファイルを更新します。 |
CopyClass |
Namespace |
Src — ソースクラス |
ソースクラス定義をターゲット定義にコピーまたは移動します。 |
CopyDir |
Manifest |
Src —ソースディレクトリ |
ディレクトリをコピーします。 |
CopyFile |
Manifest |
Src —ソースファイル |
ファイルをコピーします。 |
Credential |
Production |
Name–アクセス認証情報の名前 |
アクセス資格情報を作成または上書きします。 |
CSPApplication |
Namespace |
AuthenticationMethods –有効な認証方法 |
Webアプリケーションを作成または変更します。 詳細については、ドキュメントおよび Security.Applications クラスを参照してください |
Database |
Configuration |
BlockSize – データベースのバイト単位のブロックサイズ |
データベースを作成または変更します。 詳細については、ドキュメント 、 Config.Databases および SYS.Database クラスを参照してください |
Default |
Manifest |
Name –変数名 |
変数値を設定します(未設定の場合) |
Else |
Manifest, Namespace |
If文がfalseのときに実行されます。 |
|
Error |
Manifest |
Status – エラーコード |
例外をスローします。 ${}および#{}構文は使用できないことに注意してください。 |
ForEach |
Manifest |
Index – 変数名Values – 変数の値のリスト |
|
GlobalMapping |
Configuration |
Global – グローバル名 Collation – 並べ替えの順序 (Caché 標準) |
グローバルをマッピングします。 |
If |
Manifest, Namespace |
Condition – 条件付きステートメント |
条件付きif文 |
IfDef |
Manifest, Namespace |
Var – 変数名 |
変数がすでに設定されている場合に使用される条件付きif文 |
IfNotDef |
Manifest, Namespace |
Var – 変数名 |
変数がすでに設定されていない場合に使用される条件付きif文 |
Import |
Namespace |
File – インポート用のファイル/フォルダー |
ファイルをインポートします。 次を呼び出します。[文字列の折り返しの区切り]$System.OBJ.ImportDir(File,,Flags,,Recurse) and $System.OBJ.Load(File, Flags) |
Invoke |
Namespace |
Class – クラス名 |
さまざまな引数を指定してクラスのメソッドの呼び出し、実行結果を返します |
LoadPage |
Namespace |
Name – CSPページへのパス |
$System.CSP.LoadPage(Name, Flags)と$System.CSP.LoadPageDir(Dir, Flags)を使ってCSP fileを読み込みます。 |
Log |
Manifest |
Level – 0(最小)から3(詳細)までのロギングレベル |
ロギングレベルが「level」属性以上の場合、ログにメッセージを追加します |
Manifest |
|
|
ルートアイテム。 マニフェストで唯一のルートアイテム。他のすべてのアイテムを含みます。 |
Namespace |
Manifest |
Name – ネームスペースの名前 |
インストーラーのスコープを定義します。 |
Production |
Namespace |
Name – プロダクション名[ |
Ensembleプロダクションを構成します。 |
Resource |
Manifest |
Name – リソース名 |
リソースを作成または変更します。 |
Role |
Manifest |
Name – 役割の名前 RolesGranted – 対応するロールを付与するかどうか |
新しいロールを作成します。 |
RoutineMapping |
Configuration |
Routines – ルーチン名 |
ルーチンの新しいマッピングを作成します。 |
Setting |
Production |
Item – 構成可能な項目[文字列の折り返しの区切り]Target – パラメータタイプ:項目、ホスト、アダプタ[文字列の折り返しの区切り]Setting – パラメータ名[文字列の折り返しの区切り]Value – パラメータ値 |
Ensembleプロダクションの項目を構成します Ens.Production:ApplySettings メソッドを呼び出します |
SystemSetting |
Manifest |
Name – 構成パッケージのclass.property |
Configパッケージの属性値を設定します(Modifyメソッドを使用)。 |
User |
Manifest |
Username – ユーザー名 |
ユーザーを作成または変更します。 |
Var |
Manifest |
Name – 変数名 |
変数に値を割り当てます。 |
変数
ユーザー提供の変数
属性によっては、マニフェストの実行時に展開される式(文字列)を含めることができます。 次のように、展開できる式には3つのタイプがあります。
- ${<Variable_name>} – マニフェストの実行時に計算される変数(ユーザ定義または環境変数; 下記参照)の値。
- ${#<Parameter_name>} –コンパイル時にインストーラーのクラスから指定されたパラメーターの値に置き換えられます。
- #{<Cache_ObjectScript_code>} —指定されたCaché ObjectScript文の値は、マニフェストの実行中に処理されます。 必要に応じて引用符を付けてください。
パラメータ値はコンパイル時に定義されるため、変数またはCaché ObjectScript文の一部にすることができます。 変数はCaché ObjectScriptコードの前に解釈されるため、Caché ObjectScript文で使用できます。
例:#{$ZCVT("${NAMESPACE}","L")}
システム変数
次の変数は常に使用可能です。
変数 |
説明 |
サンプル値 |
SourceDir |
(インストーラーの実行時にのみ使用可能)インストール(setup_cache.exeまたはcinstall)が実行されるディレクトリ。 |
/InterSystems/distr/ |
ISCUpgrade |
(インストーラーの実行時にのみ使用可能)新規インストールなのか、アップグレードなのかを示します。 この変数は、0(新規インストール)または1(アップグレード)のいずれかです。 |
0 (インストール) |
CFGDIR |
INSTALLDIRを参照。 |
/InterSystems/Cache/ |
CFGFILE |
CPFファイルへのパス |
/InterSystems/Cache/cache.cpf |
CFGNAME |
インスタンスの名前 |
CACHE |
CPUCOUNT |
CPUコアの数 |
4 |
CSPDIR |
CSPディレクトリ |
/InterSystems/Cache/csp/ |
HOSTNAME |
Webサーバーの名前 |
SCHOOL15 |
HTTPPORT |
Webサーバーのポート |
80 |
INSTALLDIR |
Cachéのインストールディレクトリ |
/InterSystems/Cache/ |
MGRDIR |
マネージャディレクトリ(mgr) |
/InterSystems/Cache/mgr/ |
PLATFORM |
オペレーティングシステム |
UNIX |
PORT |
Cachéスーパーサーバポート |
1972 |
PROCESSOR |
プラットフォームの名前 |
x86-64 |
VERSION |
Cachéのバージョン |
2015.1.1 |
デバッグ
ノード属性の値としてどのような値が割り当てることができるのか理解に苦しむことがあります。これを把握するには、setupメソッドの生成されたintコードを確認してください。
ほとんどの場合、メインコールは %Installer.Installer クラスのオブジェクトである tInstaller<ElementName>に対して行われ、次に、システムメソッドを直接呼び出します。 または、ノード属性がクラスプロパティである %Installer.<ElementName>クラスのコードを確認することもできます。 プログラムコードは、 %OnBeforeGenerateCode、 %OnGenerateCode、 %OnAfterGenerateCode メソッドで生成されます。デバッグのため、インストーラーへの呼び出しをトランザクションにラップすることをお勧めします。 たとえば、 Caché内で行われたすべての変更を簡単に元に戻すためにTSTART/TROLLBACKコマンドを使うこともできます(ただし、新しいデータベースファイルの作成など、外部の変更は元に戻りません)。
最後に、LogLevel を 3 に設定することを忘れないでください。
例:
MDX2JSONプロジェクトはインストーラーを提供します 。 プロジェクトをインストールするには、MDX2JSON.Installer クラスを含むinstaller.xmlファイルを任意のネームスペースにインポートします。管理ポータルから、またはファイルをスタジオにドラッグ&ドロップすることによってインポートを実行できます。
次に、ターミナルで次のコマンドを実行します。
do ##class(MDX2JSON.Installer).setup()
その結果、CachéはGitHubリポジトリからアプリケーションファイルをロードし、デフォルトの MDX2JSON ネームスペース /MDX2JSON データベースにインストールを実行し、MDX2SJONパッケージを %AllとSAMPLESにマップし、MDX2SJONグローバルを %Allにマップし、SAMPLESネームスペースは /MDX2JSON で定義されるRESTアプリケーションを作成します。 これらの手順はすべてターミナルで確認できます。
MDX2JSONインストーラーの詳細については、プロジェクトのreadmeを参照してください 。
追加の例
ドキュメントからの例 Samplesネームスペースの Sample.Installerクラス
CacheGitHubCIプロジェクトは、インストーラーを提供します 。
SYSMONダッシュボードプロジェクトは、インストーラーを提供します 。
DeepSee監査プロジェクトは、インストーラーを提供します 。
概要
%Installerは、InterSystems Caché および Ensemble に基づいてアプリケーションを配布およびデプロイするための便利なツールです。
参考: ドキュメント