Cloud ServiceとしてのAdobe Experience Manager用のOSGiの設定

OSGi は Adobe Experience Manager（AEM）のテクノロジースタックの基本要素です。AEM とその設定の複合バンドルを制御するために使用されます。

OSGiは、小規模で再利用可能なコラボレーションコンポーネントからアプリケーションを構築できるようにする、標準化されたプリミティブを提供します。これらのコンポーネントは、アプリケーションに組み込んでデプロイすることができます。 これにより、OSGi バンドルの管理が容易になり、バンドルを個別に停止、インストール、開始できます。相互依存関係は自動的に処理されます。各 OSGi コンポーネントは、様々なバンドルの 1 つに含まれています。詳しくは、OSGi の仕様を参照してください。

AEM コードプロジェクトに含まれる設定ファイルを使用して、OSGi コンポーネントの設定を管理できます。

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 設定値のタイプ

OSGiの設定値には3種類あり、Adobe Experience ManagerをCloud Serviceとして使用できます。

  1. インライン値：OSGi 設定にハードコーディングされ、Git に保存される値です。次に例を示します。

    {
   "connection.timeout": 1000
}

  2. シークレット値（セキュリティ上の理由からGitに保存しない値）。次に例を示します。

    {
"api-key": "$[secret:server-api-key]"
}

  3. 環境固有の値。開発環境間で変化する値であり、したがって実行モードでは正確にターゲット化できません(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 設定値を使用する場合が多くあります。環境固有の設定は、開発環境間で値が異なる特定の使用例に対してのみ使用します。

環境固有の設定は、インライン値を含む、従来の静的に定義されたOSGi設定を拡張し、Cloud Manager APIを介してOSGi設定値を外部で管理できるようにします。 インライン値を定義して Git に保存する一般的で従来の方法を使用する必要がある場合と、値を環境固有の設定に抽象化する必要がある場合を理解することが重要です。

次のガイダンスは、非シークレットの場合とシークレットの場合の環境固有の設定を使用する手順を示しています。

インライン設定値を使用する場合

インライン設定の値は標準的なアプローチと見なされるので、可能であればこの設定を使用してください。インライン設定には次のような利点があります。

  • Git でガバナンスとバージョン履歴に基づいて管理される
  • 値はコードデプロイメントに暗黙的に結び付けられる
  • デプロイメントに関する検討事項や調整を追加する必要がない

OSGi設定値を定義する場合は常に、インライン値を持つ開始を指定し、必要に応じて、シークレット設定または環境固有の設定を選択する必要があります。

非シークレットの環境固有の設定値を使用する場合

非シークレットの設定値に対しては、開発環境間で値が異なる場合にのみ、環境固有の設定（$[env:ENV_VAR_NAME]）を使用してください。これには、地域開発事例や、Cloud Service開発環境としてのAdobe Experience Managerが含まれます。 Cloud Serviceステージまたは実稼動環境として、Adobe Experience Managerに対して秘密でない環境固有の設定を使用しないでください。

  • ローカル開発インスタンスなど、開発環境間で異なる設定値に対しては、非シークレットの環境固有の設定のみを使用します。
  • 代わりに、ステージングと実稼働の非シークレット値の OSGi 設定では、標準のインライン値を使用します。関連して、実行時にStageおよびProduction環境に対して設定を簡単に変更するために、環境固有の設定を使用することはお勧めしません。これらの変更は、ソースコード管理を通じて導入する必要があります。

シークレットの環境固有の設定値を使用する場合

Cloud ServiceとしてAdobe Experience Managerを使用するには、セキュリティ上の理由から、パスワード、プライベートAPIキー、またはGitに保存できない他の値など、秘密のOSGi設定値に環境固有の設定($[secret:SECRET_VAR_NAME])を使用する必要があります。

シークレット環境固有の設定を使用して、StageやProductionなどのCloud Service環境としてすべてのAdobe Experience Managerにシークレットの値を保存します。

OSGi 設定の作成

OSGi設定を作成するには、次の2つの方法があります。 前者の方法は、通常、開発者によってよく知られている OSGi のプロパティと値を持つカスタム OSGi コンポーネントの設定に使用され、後者は AEM が提供する OSGi コンポーネントの設定に使用されます。

OSGi 設定の書き込み

JSON 形式の OSGi 設定ファイルは、AEM プロジェクト内から直接手動で書き込むことができます。これは、多くの場合、よく知られているOSGiコンポーネント、特に、設定を定義する同じ開発者が設計および開発したカスタムOSGiコンポーネント用のOSGi設定を最もすばやく作成する方法です。 この方法は、同じOSGiコンポーネントの設定を様々なrunmodeフォルダーにコピー/貼り付け、更新する場合にも使用できます。

  1. IDEでui.appsプロジェクトを開き、新しいOSGi構成を有効にするために実行モードをターゲットする設定フォルダ(/apps/.../config.<runmode>)を探すか、作成します
  2. この config フォルダーに、新しい <PID>.cfg.json ファイルを作成します。PIDはOSGiコンポーネントの永続的なIDです。通常、OSGiコンポーネント実装の完全なクラス名です。 次に例を示します。
    /apps/.../config/com.example.workflow.impl.ApprovalWorkflow.cfg.json
    OSGi設定ファクトリのファイル名には、 <PID>-<factory-name>.cfg.json 命名規則が使用されます
  3. 新しい .cfg.json ファイルを開き、JSON OSGi 設定形式に従って、OSGi プロパティと値のペアのキー／値の組み合わせを定義します。
  4. 変更を新しい .cfg.json ファイルに保存します。
  5. 新しい追加 OSGi 構成ファイルを Git にコミットします。

AEM SDK Quickstart を使用した OSGi 設定の生成

AEM SDK Quickstart Jar の AEM Web コンソールは、OSGi コンポーネントの設定、および JSON として OSGi 設定を書き出すために使用できます。これは、OSGi プロパティとその値の形式が AEM プロジェクトで OSGi 設定を定義する開発者には理解されない可能性のある、AEM が提供する OSGi コンポーネントを設定する場合に役立ちます。

メモ

AEM Webコンソールの設定UIは、.cfg.jsonファイルをリポジトリに書き込みます。 したがって、AEMプロジェクト定義のOSGi設定が生成された設定と異なる場合に、ローカル開発時に予期しない動作が発生する可能性を回避するために、この点に注意してください。

  1. AEM SDK Quickstart Jar の AEM Web コンソールに管理者ユーザーとしてログインします。
  2. OSGi／設定に移動します。
  3. 設定するには、OSGiコンポーネントを見つけ、タイトルをタップして編集します
    OSGi 設定
  4. 必要に応じて Web UI を使用して OSGi 設定プロパティの値を編集します。
  5. 安全な場所に永続ID(PID)を記録します。 これは後でOSGi設定JSONの生成に使用されます
  6. 「保存」をタップします。
  7. OSGi／OSGi インストーラー設定プリンターに移動します。
  8. 手順 5 でコピーした PID に貼り付け、シリアル化形式が「OSGi Configurator JSON」に設定されていることを確認します。
  9. 「印刷」をタップします
  10. JSON 形式の OSGi 設定は、「シリアライズされた設定プロパティ」セクションに表示されます。
    OSGi インストーラー設定プリンター
  11. IDEでui.appsプロジェクトを開き、新しいOSGi構成を有効にする必要があるrunmodesのターゲットを指定するか、configフォルダ(/apps/.../config.<runmode>)を作成します。
  12. この config フォルダーに、新しい <PID>.cfg.json ファイルを作成します。PID は、手順 5 と同じ値です。
  13. 手順 10 のシリアライズされた設定プロパティを .cfg.json ファイルに貼り付けます。
  14. 変更を新しい .cfg.json ファイルに保存します。
  15. 新しい追加 OSGi 構成ファイルを Git にコミットします。

OSGi 構成プロパティの形式

インライン値

インライン値は、標準の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]

変数の命名

環境固有の設定値とシークレットの設定値の両方に次のことが適用されます。

変数名は、次の規則に従う必要があります。

  • 最小長：2
  • 最大長：100
  • Must match regex:[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
}

プロパティ設定用の Cloud Manager API 形式

API の設定方法については、こちらのページを参照してください。

メモ

使用している Cloud Manager API に「デプロイメントマネージャー - Cloud Service」という役割が割り当てられていることを確認します。その他の役割では、必ずしも以下のすべてのコマンドを実行できるわけではありません。

API を使用した値の設定

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プロパティ自体に設定されます。

詳しくは、こちらのページを参照してください。

API を使用した値の取得

GET /program/{programId}/environment/{environmentId}/variables

詳しくは、こちらのページを参照してください。

API を使用した値の削除

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のアップデートまたはお客様のデプロイメントが成功しない場合があります。 エラーの応答は、リクエストが成功しなかったことを示しますが、理由は示しません。

予定されている顧客コードのデプロイメントが、新しい値を持つ既存の変数に依存している場合があります。これは、現在のコードには適していません。これが問題となる場合は、変数の変更を加える方法をお勧めします。 そのためには、古いコードが新しい値を参照しないように、古い変数の値を変更する代わりに、新しい変数名を作成します。後日、新しいカスタマーリリースが安定したら、古い値を削除できます。

同様に、変数の値はバージョン管理されないので、コードのロールバックによって、新しい値を参照することで問題を引き起こす場合があります。前述の加法変数戦略もこの場で役立ちます。

この変数の加算方式戦略は、数日前のコードを再デプロイする必要がある災害復旧シナリオにも役立ちます。コードが参照する変数名と値は変わりません。これは、顧客が古い変数を削除する前に数日間待機するという手法に依存しています。この手法を使用していない場合、古いコードには参照できる適切な変数はありません。

このページ

Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now
Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now