OSGi は Adobe Experience Manager(AEM)のテクノロジースタックの基本要素です。AEM とその設定の複合バンドルを制御するために使用されます。
OSGiは、小規模で再利用可能なコラボレーションコンポーネントからアプリケーションを構築できるようにする、標準化されたプリミティブを提供します。これらのコンポーネントは、アプリケーションに組み込んでデプロイすることができます。 これにより、OSGi バンドルの管理が容易になり、バンドルを個別に停止、インストール、開始できます。相互依存関係は自動的に処理されます。各 OSGi コンポーネントは、様々なバンドルの 1 つに含まれています。詳しくは、OSGi の仕様を参照してください。
AEM コードプロジェクトに含まれる設定ファイルを使用して、OSGi コンポーネントの設定を管理できます。
設定の変更は、 AEM プロジェクトのコードパッケージ(ui.apps
)で、実行モード固有の config フォルダーの下に設定ファイル(.cfg.json
)として定義されます。
/apps/example/config.<runmode>
OSGi設定ファイルの形式は、Apache Slingプロジェクトで定義されている.cfg.json
形式を使用したJSONベースです。
OSGi設定ターゲットOSGiコンポーネントは、そのPersistent Identity(PID)を介してコンポーネントを設定します。デフォルトでは、OSGiコンポーネントのJava™クラス名が使用されます。 例えば、OSGi サービス用の OSGi 設定を提供するには、次のように実装します。
com.example.workflow.impl.ApprovalWorkflow.java
OSGi 設定ファイルは次の場所で定義されます。
/apps/example/config/com.example.workflow.impl.ApprovalWorkflow.cfg.json
cfg.json OSGi 設定形式に従います。
以前のバージョンの AEM は、.cfg、.config、XML sling:OsgiConfig リソース定義など、様々なファイル形式の OSGi 設定ファイルをサポートしていました。これらの形式は、cfg.json OSGi 設定形式に置き換えられます。
実行モードを使用すると、特定の OSGi 設定を特定の AEM インスタンスにターゲット設定できます。実行モードを使用するには、次の形式で、/apps/example
(「example」はプロジェクト名)の下に config フォルダーを作成します。
/apps/example/config.<author|publish>.<dev|stage|prod>/
configフォルダー名で定義されたrunmodeがAEMで使用されるrunmodeと一致する場合、このようなフォルダー内のOSGi設定が使用されます。
例えば、AEMがrunmodes authorとdevを使用している場合、/apps/example/config.author/
と/apps/example/config.author.dev/
の設定ノードは適用され、/apps/example/config.publish/
と/apps/example/config.author.stage/
の設定ノードは適用されません。
同じ PID に複数の設定が該当する場合は、一致する実行モードの数が最も大きい設定が適用されます。
このルールの精度は PID レベルです。つまり、/apps/example/config.author/
で同じ PID の一部のプロパティと、/apps/example/config.author.dev/
で同じ PID のより具体的なプロパティを定義することはできません。一致するランモードの数が最も多い設定は、PID全体に対して有効です。
ローカルで開発する場合、runmode起動パラメータを渡して、OSGIのどのrunmode設定が使用されるかを指定できます。
OSGiの設定値には3種類あり、Adobe Experience ManagerをCloud Serviceとして使用できます。
インライン値:OSGi 設定にハードコーディングされ、Git に保存される値です。次に例を示します。
{
"connection.timeout": 1000
}
シークレット値(セキュリティ上の理由からGitに保存しない値)。次に例を示します。
{
"api-key": "$[secret:server-api-key]"
}
環境固有の値。開発環境間で変化する値であり、したがって実行モードでは正確にターゲット化できません(Adobe Experience ManagerにはCloud Serviceとして1つの dev
runmodeが存在するため)。次に例を示します。
{
"url": "$[env:server-url]"
}
1 つの OSGi 設定ファイルで、これらの設定値タイプの任意の組み合わせを併用できます。次に例を示します。
{
"connection.timeout": 1000,
"api-key": "$[secret:server-api-key]",
"url": "$[env:server-url]"
}
OSGi では、インライン OSGi 設定値を使用する場合が多くあります。環境固有の設定は、開発環境間で値が異なる特定の使用例に対してのみ使用します。
環境固有の設定は、インライン値を含む、従来の静的に定義されたOSGi設定を拡張し、Cloud Manager APIを介してOSGi設定値を外部で管理できるようにします。 インライン値を定義して Git に保存する一般的で従来の方法を使用する必要がある場合と、値を環境固有の設定に抽象化する必要がある場合を理解することが重要です。
次のガイダンスは、非シークレットの場合とシークレットの場合の環境固有の設定を使用する手順を示しています。
インライン設定の値は標準的なアプローチと見なされるので、可能であればこの設定を使用してください。インライン設定には次のような利点があります。
OSGi設定値を定義する場合は常に、インライン値を持つ開始を指定し、必要に応じて、シークレット設定または環境固有の設定を選択する必要があります。
非シークレットの設定値に対しては、開発環境間で値が異なる場合にのみ、環境固有の設定($[env:ENV_VAR_NAME]
)を使用してください。これには、地域開発事例や、Cloud Service開発環境としてのAdobe Experience Managerが含まれます。 Cloud Serviceステージまたは実稼動環境として、Adobe Experience Managerに対して秘密でない環境固有の設定を使用しないでください。
Cloud ServiceとしてAdobe Experience Managerを使用するには、セキュリティ上の理由から、パスワード、プライベートAPIキー、またはGitに保存できない他の値など、秘密のOSGi設定値に環境固有の設定($[secret:SECRET_VAR_NAME]
)を使用する必要があります。
シークレット環境固有の設定を使用して、StageやProductionなどのCloud Service環境としてすべてのAdobe Experience Managerにシークレットの値を保存します。
OSGi設定を作成するには、次の2つの方法があります。 前者の方法は、通常、開発者によってよく知られている OSGi のプロパティと値を持つカスタム OSGi コンポーネントの設定に使用され、後者は AEM が提供する OSGi コンポーネントの設定に使用されます。
JSON 形式の OSGi 設定ファイルは、AEM プロジェクト内から直接手動で書き込むことができます。これは、多くの場合、よく知られているOSGiコンポーネント、特に、設定を定義する同じ開発者が設計および開発したカスタムOSGiコンポーネント用のOSGi設定を最もすばやく作成する方法です。 この方法は、同じOSGiコンポーネントの設定を様々なrunmodeフォルダーにコピー/貼り付け、更新する場合にも使用できます。
ui.apps
プロジェクトを開き、新しいOSGi構成を有効にするために実行モードをターゲットする設定フォルダ(/apps/.../config.<runmode>
)を探すか、作成します<PID>.cfg.json
ファイルを作成します。PIDはOSGiコンポーネントの永続的なIDです。通常、OSGiコンポーネント実装の完全なクラス名です。 次に例を示します。/apps/.../config/com.example.workflow.impl.ApprovalWorkflow.cfg.json
<PID>-<factory-name>.cfg.json
命名規則が使用されます.cfg.json
ファイルを開き、JSON OSGi 設定形式に従って、OSGi プロパティと値のペアのキー/値の組み合わせを定義します。.cfg.json
ファイルに保存します。AEM SDK Quickstart Jar の AEM Web コンソールは、OSGi コンポーネントの設定、および JSON として OSGi 設定を書き出すために使用できます。これは、OSGi プロパティとその値の形式が AEM プロジェクトで OSGi 設定を定義する開発者には理解されない可能性のある、AEM が提供する OSGi コンポーネントを設定する場合に役立ちます。
AEM Webコンソールの設定UIは、.cfg.json
ファイルをリポジトリに書き込みます。 したがって、AEMプロジェクト定義のOSGi設定が生成された設定と異なる場合に、ローカル開発時に予期しない動作が発生する可能性を回避するために、この点に注意してください。
ui.apps
プロジェクトを開き、新しいOSGi構成を有効にする必要があるrunmodesのターゲットを指定するか、configフォルダ(/apps/.../config.<runmode>
)を作成します。<PID>.cfg.json
ファイルを作成します。PID は、手順 5 と同じ値です。.cfg.json
ファイルに貼り付けます。.cfg.json
ファイルに保存します。インライン値は、標準のJSON構文に従って、標準の名前と値のペアとして形式設定されます。 次に例を示します。
{
"my_var1": "val",
"my_var2": [ "abc", "def" ],
"my_var3": 500
}
OSGi 設定では、環境ごとに定義する変数にプレースホルダーを割り当てる必要があります。
use $[env:ENV_VAR_NAME]
お客様は、カスタムコードに関連するOSGI設定プロパティに対してのみ、この手法を使用する必要があります。Adobe定義のOSGI設定を上書きする場合は使用しないでください。
repoint文ではプレースホルダーを使用できません。
OSGi 設定では、環境ごとに定義するシークレットにプレースホルダーを割り当てる必要があります。
use $[secret:SECRET_VAR_NAME]
環境固有の設定値とシークレットの設定値の両方に次のことが適用されます。
変数名は、次の規則に従う必要があります。
[a-zA-Z_][a-zA-Z_0-9]*
変数の値は2048文字以下にする必要があります。
環境固有の設定値とシークレットの設定値の両方に次のことが適用されます。
環境単位の値を設定しない場合、プレースホルダーは実行時に置き換えられず、補間が行われないので、配置されたままになります。 これを回避するには、プレースホルダーの一部として次の構文でデフォルト値を指定します。
$[env:ENV_VAR_NAME;default=<value>]
デフォルト値が指定されている場合、プレースホルダーは、環境ごとの値(指定されている場合)またはデフォルト値に置き換えられます。
環境固有の設定値とシークレットの設定値の両方に次のことが適用されます。
変数は、実行時にローカル AEM によって取得されるように、ローカル環境で定義できます。例えば、Linux®では次のようになります。
export ENV_VAR_NAME=my_value
設定で使用される環境変数を設定し、AEM を起動する前に実行する、単純な bash スクリプトを記述することをお勧めします。https://direnv.net/ などのツールを使うと、このアプローチを簡略化できます。すべてのユーザー間で共有できる場合は、値のタイプに応じて、値をソースコード管理にチェックインできることがあります。
シークレットの値はファイルから読み取られます。したがって、シークレットを使用するプレースホルダごとに、シークレット値を含むテキストファイルを作成する必要があります。
例えば、$[secret:server_password]
を使用する場合は、server_passwordという名前のテキストファイルを作成する必要があります。 これらのシークレットファイルはすべて同じディレクトリに保存する必要があり、フレームワークプロパティorg.apache.felix.configadmin.plugin.interpolation.secretsdir
はそのローカルディレクトリで構成する必要があります。
OSGi プロパティで、作成者とパブリッシュで異なる値が必要な場合:
config.author
とconfig.publish
のOSGiフォルダーは別々に使用する必要があります。詳しくは、Runmode Resolutionセクションを参照してください。author_<variablename>
および publish_<variablename>
などのプレフィックスを使用することをお勧めします。以下の例では、ステージ環境とprod環境に加えて、3つの開発があると仮定します。
例 1
目的は、OSGIプロパティmy_var1
の値をステージとprodで同じにすることですが、3つの開発環境ごとに異なります。
Folder | myfile.cfg.json の内容 |
config |
{ "my_var1": "val", "my_var2": "abc", "my_var3": 500 } |
config.dev |
{ "my_var1" : "$[env:my_var1]" "my_var2": "abc", "my_var3": 500 } |
例 2
目的は、OSGIプロパティmy_var1
の値がステージ、prod、および3つの開発環境のそれぞれで異なることです。 したがって、各開発環境に対してmy_var1
の値を設定するには、Cloud Manager APIを呼び出す必要があります。
フォルダ | myfile.cfg.json の内容 |
config.stage |
{ "my_var1": "val1", "my_var2": "abc", "my_var3": 500 } |
config.prod |
{ "my_var1": "val2", "my_var2": "abc", "my_var3": 500 } |
config.dev |
{ "my_var1":"$[env:my_var1]" "my_var2":"abc", "my_var3":500 } |
例 3
OSGi プロパティ my_var1
の値をステージング、実稼働、1 つの開発環境で同じ値、他の 2 つの開発環境では異なる値にします。この場合、Cloud Manager APIを呼び出して各開発環境の値my_var1
を設定する必要があります。この値は、開発環境用(ステージと実稼働と同じ値を持つ必要がある開発環境用を含む)に対して設定します。 フォルダー config に設定された値は継承されません。
フォルダ | myfile.cfg.json の内容 |
config |
{ "my_var1":"val1", "my_var2":"abc", "my_var3":500 } |
config.dev |
{ "my_var1":"$[env:my_var1]" "my_var2":"abc", "my_var3":500 } |
これをおこなう別の方法は、config.dev フォルダーの置き換えトークンのデフォルト値を、config フォルダーと同じ値に設定することです。
フォルダ | myfile.cfg.json の内容 |
config |
{ "my_var1":"val1", "my_var2":"abc", "my_var3":500 } |
config.dev |
{ "my_var1": "$[env:my_var1;default=val1]" "my_var2": "abc", "my_var3": 500 } |
API の設定方法については、こちらのページを参照してください。
使用している Cloud Manager API に「デプロイメントマネージャー - Cloud Service」という役割が割り当てられていることを確認します。その他の役割では、必ずしも以下のすべてのコマンドを実行できるわけではありません。
APIを呼び出すと、一般的なカスタマーコードの導入パイプラインと同様、新しい変数と値がクラウド環境にデプロイされます。 オーサーとパブリッシュサービスは再起動され、新しい値が参照されます(通常、数分かかります)。
PATCH /program/{programId}/environment/{environmentId}/variables
]
{
"name" : "MY_VAR1",
"value" : "plaintext value",
"type" : "string" <---default
},
{
"name" : "MY_VAR2",
"value" : "<secret value>",
"type" : "secretString"
}
]
デフォルトの変数は、APIを介してではなく、OSGiプロパティ自体に設定されます。
詳しくは、こちらのページを参照してください。
GET /program/{programId}/environment/{environmentId}/variables
詳しくは、こちらのページを参照してください。
PATCH /program/{programId}/environment/{environmentId}/variables
変数を削除するには、空の値を含めます。
詳しくは、こちらのページを参照してください。
$ aio cloudmanager:list-environment-variables ENVIRONMENT_ID
Name Type Value
MY_VAR1 string plaintext value
MY_VAR2 secretString ****
$ aio cloudmanager:set-environment-variables ENVIRONMENT_ID --variable MY_VAR1 "plaintext value" --secret MY_VAR2 "some secret value"
$ aio cloudmanager:set-environment-variables ENVIRONMENT_ID --delete MY_VAR1 MY_VAR2
Adobe I/O CLI 用の Cloud Manager プラグインを使用した値の設定方法の詳細については、こちらのページを参照してください。
1 つの環境につき最大 200 個の変数を宣言できます。
秘密と環境固有の設定値はGitの外部に存在し、したがって、Cloud Service展開メカニズムとしての正式なAdobe Experience Managerには含まれないので、Cloud Service展開プロセスとしての管理、管理、Adobe Experience Managerへの統合を行う必要があります。
前述したように、APIを呼び出すと、一般的なカスタマーコードの導入パイプラインと同様に、新しい変数と値がクラウド環境にデプロイされます。 オーサーとパブリッシュサービスは再起動され、新しい値が参照されます(通常、数分かかります)。通常のコードのデプロイメント中に Cloud Manager によって実行される品質ゲートおよびテストは、このプロセス中は実行されません。
通常、Cloud Manager で API を使用するコードをデプロイする前に、API を呼び出して環境変数を設定します。場合によっては、コードが既にデプロイされた後で既存の変数を変更する必要があります。
パイプラインが使用中の場合、その時点でエンドツーエンドパイプラインのどの部分が実行されているかに応じて、AEMのアップデートまたはお客様のデプロイメントが成功しない場合があります。 エラーの応答は、リクエストが成功しなかったことを示しますが、理由は示しません。
予定されている顧客コードのデプロイメントが、新しい値を持つ既存の変数に依存している場合があります。これは、現在のコードには適していません。これが問題となる場合は、変数の変更を加える方法をお勧めします。 そのためには、古いコードが新しい値を参照しないように、古い変数の値を変更する代わりに、新しい変数名を作成します。後日、新しいカスタマーリリースが安定したら、古い値を削除できます。
同様に、変数の値はバージョン管理されないので、コードのロールバックによって、新しい値を参照することで問題を引き起こす場合があります。前述の加法変数戦略もこの場で役立ちます。
この変数の加算方式戦略は、数日前のコードを再デプロイする必要がある災害復旧シナリオにも役立ちます。コードが参照する変数名と値は変わりません。これは、顧客が古い変数を削除する前に数日間待機するという手法に依存しています。この手法を使用していない場合、古いコードには参照できる適切な変数はありません。