AEM as a Cloud Service の開発ガイドライン

このドキュメントでは、AEM as a Cloud Service での開発に関するガイドラインと、オンプレミスおよび AMS の AEM とは異なる重要な方法について説明します。

コードはクラスター対応である必要があります

AEM as a Cloud Service で実行するコードは、常にクラスター内で実行されていることを認識している必要があります。つまり、常に複数のインスタンスが実行されています。インスタンスはいつ停止するかわからないので、コードには特に回復力が必要です。

AEM as a Cloud Service を更新する間、古いコードと新しいコードが並行して実行されるインスタンスが存在します。したがって、新しいコードで作成されたコンテンツが古いコードによって中断されず、新しいコードが古いコンテンツを処理できる必要があります。

クラスター内のプライマリを識別する必要がある場合は、Apache Sling Discovery API を使用して検出できます。

メモリ内の状態

状態はメモリ内ではなく、リポジトリー内に保持する必要があります。そうしないと、インスタンスが停止した場合に、状態が失われる可能性があります。

ファイルシステムの状態

インスタンスのファイルシステムは、AEM as a Cloud Service で使用しないでください。ディスクは揮発性で、インスタンスが再利用されると破棄されます。単一の要求の処理に関する一時的なストレージのために、ファイルシステムの使用を制限することは可能ですが、大量のファイルに対して濫用しないでください。リソースの使用割り当てに悪影響を与え、ディスクの制限が生じる可能性があるためです。

ファイルシステムの使用がサポートされていない例として、パブリッシュ層では、永続化する必要のあるデータが、長期ストレージのために外部サービスに送り出されることを確認する必要があります。

監視

同様に、観察イベントに作用するように非同期的に起こっているものすべてに対して、ローカルで実行することを保証できないことから、注意深く使用する必要があります。これは、JCR リソースと Sling イベントの両方に当てはまります。変更が発生した時点で、インスタンスが停止し、別のインスタンスに置き換えられる場合があります。その時点でアクティブなトポロジ内の他のインスタンスは、このイベントに反応できます。しかし、この場合、ローカルのイベントではなく、イベントの発行時にアクティブなリーダーがいない可能性もあります。

バックグラウンドタスクと長時間実行ジョブ

バックグラウンドタスクとして実行するコードでは、コードを実行しているインスタンスが突然機能しなくなる可能性があることを前提にする必要があります。そのため、コードは回復力がある必要があり、最も重要なのは再開可能であることです。つまり、コードが再実行された場合は、再び最初から始めるのではなく、実行が中断された箇所に近い位置から始める必要があります。これはこの種のコードにとって新しい要件ではありませんが、AEM as a Cloud Service では、インスタンスの停止が起こる可能性が高くなります。

トラブルを最小限に抑えるために、長時間実行ジョブは可能な限り避け、少なくとも再開可能な状態になっている必要があります。このようなジョブを実行するには、少なくとも 1 回は実行されることが保証されている Sling ジョブを使用します。したがって、ジョブが中断された場合、ジョブはできるだけ早く再実行されます。ただし、最初からやり直すべきではないでしょう。このようなジョブをスケジュールする場合は、 Sling ジョブ スケジューラーを使用することをお勧めします。やはり、少なくとも 1 回は実行されることが保証されているからです。

Sling Commons Scheduler は実行を保証できないので、スケジュール設定には使用しないでください（スケジュール設定される可能性のほうが高いというだけで、保証されるものではありません）。

同様に、監視イベント（例：JCR イベントや Sling リソースイベント）に対する動作など、非同期的に発生するあらゆる動作は、必ずしも実行が保証されないので、慎重に使用する必要があります。これは、現在の AEM デプロイメントに既に当てはまります。

送信 HTTP 接続

送信 HTTP 接続では、接続および読み取りの妥当なタイムアウトを設定することを強くお勧めします。推奨値は、接続タイムアウトの場合は 1 秒、読み取りタイムアウトの場合は 5 秒です。正確な数値は、これらのリクエストを処理するバックエンドシステムのパフォーマンスに基づいて決定する必要があります。

これらのタイムアウトを適用しないコードの場合、AEM as a Cloud Service 上で動作している AEM インスタンスは、グローバルタイムアウトを強制的に適用します。接続の場合、これらのタイムアウト値は、接続呼び出しについては 10 秒、読み取り呼び出しについては 60 秒です。

HTTP 接続を行う場合は、提供されている Apache HttpComponents Client 4.x ライブラリを使用することをお勧めします。

次の代替手段は、動作することはわかっていますが、依存関係を自分で指定しなければならない可能性があります。

• java.net.URL と java.net.URLConnection（AEM で提供）のいずれか一方または両方
• Apache Commons HttpClient 3.x（古くなり、バージョン 4.x に代わっているので、お勧めしません）
• OK Http（AEM では提供されません）

タイムアウトの指定の次に、そのようなタイムアウトと予期しない HTTP ステータスコードの適切な処理も実装する必要があります。

クラシック UI のカスタマイズがない

AEM as a Cloud Service は、サードパーティの顧客コードのタッチ UI のみをサポートします。クラシック UI はカスタマイズには使用できません。

ネイティブバイナリの回避

コードは、実行時にバイナリをダウンロードしたり、変更したりすることはできません。例えば、jar や tar ファイルは解凍できません。

AEM as a Cloud Service を使用したストリーミングバイナリがない

バイナリは CDN を通じてアクセスし、コア AEM サービスの外部でバイナリを提供します。

例えば、AEM サービスの揮発性ディスクへのバイナリのダウンロードをトリガーする asset.getOriginal().getStream() を使用しないでください。

リバースレプリケーションエージェントがない

パブリッシュからオーサーへのリバースレプリケーションは、AEM as a Cloud Service ではサポートされていません。このような方法が必要な場合は、パブリッシュインスタンスのファームと、場合によってはオーサークラスターで共有される外部の永続化ストアを使用できます。

転送レプリケーションエージェントの移植が必要

コンテンツは、pub-sub メカニズムを使用してオーサーからパブリッシュにレプリケートされます。カスタムレプリケーションエージェントはサポートされていません。

監視とデバッグ

ログ

ローカル開発の場合、ログエントリは /crx-quickstart/logs フォルダーのローカルファイルに書き込まれます。

クラウド環境では、開発者は Cloud Manager を使用してログをダウンロードするか、コマンドラインツールを使用してログを追跡することができます。

ログレベルの設定

クラウド環境のログレベルを変更するには、Sling Logging OSGi 設定を変更した後、完全に再デプロイする必要があります。これは即座には行われないので、大量のトラフィックを受け取る実稼動環境で詳細なログを有効にする場合は注意が必要です。今後、ログレベルをより迅速に変更するメカニズムが提供される可能性があります。

デバッグログレベルのアクティベート

デフォルトのログレベルは情報（INFO）なので、デバッグ（DEBUG）メッセージはログに記録されません。DEBUG ログレベルをアクティブにするには、次のプロパティをデバッグモードに更新します。

/libs/sling/config/org.apache.sling.commons.log.LogManager/org.apache.sling.commons.log.level

例えば、/apps/<example>/config/org.apache.sling.commons.log.LogManager.factory.config~<example>.cfg.json に次の値を設定します。

{
   "org.apache.sling.commons.log.names": [
      "com.example"
   ],
   "org.apache.sling.commons.log.level": "DEBUG",
   "org.apache.sling.commons.log.file": "logs/error.log",
   "org.apache.sling.commons.log.additiv": "false"
}

この結果、多くのエントリが生成されるので、ログを不必要に長くデバッグログレベルのままにしないでください。

開発時に常に DEBUG レベルでログを記録するのが望ましい場合は、実行モードベースの OSGi 設定ターゲティングを使用して、AEM 環境ごとに個別にログレベルを設定できます。次に例を示します。

デバッグファイルの行は、通常は DEBUG で始まり、ログレベル、インストーラーのアクション、ログメッセージを示します。 次に例を示します。

DEBUG 3 WebApp Panel: WebApp successfully deployed

ログレベルは次のとおりです。

スレッドダンプ

クラウド環境のスレッドダンプは継続的に収集されますが、現時点ではセルフサービス方式でダウンロードすることはできません。しばらくの間は、問題のデバッグ用にスレッドダンプが必要な場合は、AEM サポートに連絡して、正確な時間枠を指定してください。

CRXDE Lite とデベロッパーコンソール

ローカル開発

ローカル開発の場合、開発者は CRXDE Lite（/crx/de）と AEM Web コンソール（/system/console）に完全にアクセスできます。

（SDK を使用する）ローカル開発では、/apps と /libs に直接書き込むことができます。この点が、最上位フォルダーが不変なクラウド環境とは異なります。

AEM as a Cloud Service の開発ツール

ユーザーはオーサー層の開発環境では CRXDE Lite にアクセスできますが、ステージ環境や実稼動環境ではアクセスできません。不変リポジトリー（/libs、/apps）に実行時に書き込むことはできないので、書き込もうとするとエラーが発生します。

代わりに、開発者コンソールからリポジトリーブラウザーを起動して、オーサー層、パブリッシュ層およびプレビュー層にあるすべての環境のリポジトリーに対して読み取り専用ビューを提供できます。リポジトリーブラウザーについて詳しくは、こちらを参照してください。

AEM as a Cloud Service 開発者環境をデバッグするための一連のツールは、RDE 環境、開発環境、ステージ環境、実稼動環境の開発者コンソールで利用できます。URL は、次のようにオーサーサービス URL またはパブリッシュサービス URL を調整して決定できます。

https://dev-console/-<namespace>.<cluster>.dev.adobeaemcloud.com

ショートカットとして、次の Cloud Manager CLI コマンドを使用して、下記の環境パラメーターに基づいて開発者コンソールを起動できます。

aio cloudmanager:open-developer-console <ENVIRONMENTID> --programId <PROGRAMID>

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

開発者は、ステータス情報を生成し、様々なリソースを解決できます。

下図に示すように、使用可能なステータス情報には、バンドルの状態、コンポーネント、OSGi 設定、Oak インデックス、OSGi サービス、Sling ジョブなどがあります。

下図に示すように、開発者はパッケージの依存関係とサーブレットを解決できます。

また、デバッグにも便利です。開発者コンソールには、次のように「クエリの説明を実行」ツールへのリンクがあります。

実稼動プログラムの場合、開発者コンソールへのアクセスは Admin Console の「Cloud Manager - デベロッパーロール」で定義されます。一方、サンドボックスプログラムの場合、開発者コンソールは、AEM as a Cloud Service へのアクセスを可能にする製品プロファイルを持つすべてのユーザーが使用できます。すべてのプログラムで、ステータスダンプとリポジトリーブラウザーには「Cloud Manager - デベロッパーロール」が必要です。また、オーサーサービスとパブリッシュサービスの両方のデータを表示するには、ユーザーがそれら両方のサービスで「AEM ユーザー」または「AEM 管理者」製品プロファイルにも定義されている必要があります。ユーザー権限の設定について詳しくは、 Cloud Manager のドキュメント を参照してください。

パフォーマンスの監視

アドビはアプリケーションのパフォーマンスを監視し、劣化が観察された場合に対処します。現時点では、アプリケーションの指標を確認できません。

メールの送信

以下の節では、メールのリクエスト、設定、送信の方法について説明します。

送信メールの有効化

メールの送信に使用されるポートは、デフォルトでは無効になっています。ポートをアクティブにするには、高度なネットワークを設定して、対象となるポート（465 や 587 など）をプロキシポートにマッピングするエンドポイントのポート転送ルールを、必要な環境ごとに設定するようにします（PUT /program/<program_id>/environment/<environment_id>/advancedNetworking）。

kind パラメータを flexiblePortEgress に設定して高度なネットワーク機能を設定することをお勧めします。アドビがフレキシブルポートエグレストラフィックのパフォーマンスを最適化できるからです。一意のエグレス IP アドレスが必要な場合は、kind パラメーターを dedicatedEgressIp に設定します。他の理由で既に VPN を設定してある場合は、その高度なネットワークバリエーションから提供される一意の IP アドレスも使用できます。

メールクライアントに直接送信するのではなく、メールサーバーを通じてメールを送信する必要があります。そうしないと、メールがブロックされる可能性があります。

メールの送信

Day CQ Mail Service OSGi サービスを使用してください。また、受信者に直接送信するのではなく、サポートリクエストに明示されたメールサーバーにメールを送信する必要があります。

設定

AEM 内のメールは、Day CQ Mail Service OSGi サービスを使用して送信する必要があります。

メールの設定について詳しくは、 AEM 6.5 ドキュメント を参照してください。AEM as a Cloud Service の場合は、com.day.cq.mailer.DefaultMailService OSGI サービスへの次のような調整が必要になります。

• SMTP サーバーのホスト名を $[env:AEM_PROXY_HOST;default=proxy.tunnel] に設定する必要があります
• SMTP サーバーポートは、高度なネットワーク機能を設定する際に、API 呼び出しで使用される portForwards パラメーターに設定された元のプロキシポートの値に設定してください。例えば、（465 ではなく）30465 などとします。

SMTP サーバーポートには、高度なネットワーク設定時に API 呼び出しで使用される portForwards パラメーターに設定された portDest 値を設定する必要があります。portOrig 値は、30000 ～ 30999 の必須範囲内の意味のある値である必要があります。例えば、SMTP サーバーポートが 465 の場合、ポート 30465 を portOrig の値として使用します。

この例で、SSL を有効にする必要がある場合、Day CQ Mail Service OSGI サービスの設定は次のとおりです。

• smtp.port を 30465 に設定
• smtp.ssl を true に設定

または、宛先ポートが 587 の場合、portOrig 値の 30587 を使用する必要があります。また、SSL を無効にする必要がある場合、Day CQ Mail Service OSGi サービスの設定は次のとおりです。

• smtp.port を 30587 に設定
• smtp.ssl を false に設定

smtp.starttls プロパティは、実行時に AEM as a Cloud Service によって適切な値に自動的に設定されます。したがって、smtp.ssl が true に設定されている場合、smtp.startls は無視されます。smtp.ssl が false に設定されている場合、smtp.starttls は true に設定されます。これは、OSGI 構成で設定されている smtp.starttls 値には関係ありません。

オプションで、メールサービスに OAuth2 サポートを設定できます。詳しくは、メールサービスの OAuth2 サポートを参照してください。

従来のメール設定

2021.9.0 リリースより前は、カスタマーサポートへの依頼を通じてメールが設定されていました。com.day.cq.mailer.DefaultMailService OSGI サービスへの次のような調整が必要になります。

AEM as a Cloud Service では、ポート 465 を通じてメールを送信する必要があります。TLS オプションが有効になっている限り、メールサーバーがポート 465 をサポートしていない場合は、ポート 587 を使用できます。

ポート 465 がリクエストされた場合：

• smtp.port を 465 に設定
• smtp.ssl を true に設定

さらに、ポート 587 がリクエストされた場合は、

• smtp.port を 587 に設定
• smtp.ssl を false に設定

smtp.starttls プロパティは、実行時に AEM as a Cloud Service によって適切な値に自動的に設定されます。したがって、smtp.ssl が true に設定されている場合、smtp.startls は無視されます。smtp.ssl が false に設定されている場合、smtp.starttls は true に設定されます。これは、OSGI 構成で設定されている smtp.starttls 値には関係ありません。

SMTP サーバーホストは、メールサーバーのホストに設定してください。

複数値の大きなプロパティの回避

AEM as a Cloud Service の基盤となる Oak コンテンツリポジトリは、複数値プロパティ（MVP）の数が非常に多い状況での使用を意図していません。経験則として、MVP を 1000 未満に保ってください。ただし、実際のパフォーマンスは多くの要因に左右されます。

警告は、1000 件を超えるとデフォルトでログに記録されます。 次のようになります。

org.apache.jackrabbit.oak.jcr.session.NodeImpl Large multi valued property [/path/to/property] detected (1029 values).

大規模な MVP では、16 MB を超える MongoDB ドキュメントが原因で、次のようなエラーが発生する可能性があります。

Caused by: com.mongodb.MongoWriteException: Resulting document after update is larger than 16777216

詳しくは、Apache Oak のドキュメントを参照してください。

Assets 開発のガイドラインとユースケース

Assets as a Cloud Service の開発のユースケース、推奨事項、参考資料については、Assets の開発者向けリファレンスを参照してください。

Business.Adobe.com リソース