AEM Cloud Migration Skillの使用 using-cloud-migration-skill

このリファレンスでは、サポートされている各移行パターン、BPAの調査結果の提供方法、大規模なプロジェクト全体でのセッションの管理方法について説明します。 概要と設定の手順については、概要を参照してください。

移行Runbookの生成 migration-runbook

プロジェクト全体を評価する場合は、単一のパターンに名前を付ける代わりに、Runbookから始めます。 担当者に次のプロンプトを入力します。

Review my code for AEMaaCS migration

スキルは、コードを変更することなく、プロジェクトルートで​ 読み取り専用migration-runbook.md ​を生成します。 Runbookは、移行スキルが対処できる​ 個の ​個のパターンをカバーし、それぞれに対して次のレコードを含みます。

Runbookはマークダウンと共に調査結果キャッシュも書き込むため、後のパターンセッションでは、既に発見された調査結果を再利用します。エージェントは再スキャンしません。 ランブックを使用して、最初に取り組むパターンの優先順位を決め、次に説明するようにパターンセッションを開始します。

セッションの仕組み workflow-overview

すべての移行セッションは、次の順序に従います。

エージェントは一度に1つのパターンと1つのバッチを処理します。 自動的には処理されません。各バッチには確認が必要です。

移行パターン patterns

スケジューラー scheduler

AEMaaCSのステートレスでコンテナ化されたランタイムと互換性のないsling.commons.schedulerまたはScheduler インジェクションを使用するJava クラスをターゲットにします。

BPA パターン ID: scheduler

エージェントは、コンストラクターベースのスケジューラー登録を@Activate / @Deactivateのライフサイクルメソッドに置き換えて、@Designateを使用してScheduler注入されたジョブをRunnable実装の@Componentに変換します。

ResourceChangeListener resource-change-listener

AEMaaCSの更新が必要なResourceChangeListenerまたはResourceChange個のリスナー実装をターゲットにします。

BPA パターン ID: resourceChangeListener

レプリケーション replication

AEMaaCSではサポートされていないcom.day.cq.replication.Replicatorまたは関連するレプリケーション APIを読み込むクラスをターゲットにします。 エージェントは、それらをContentDistribution ベースの同等のものに置き換え、対応するOSGi サービス参照を更新します。

BPA パターン ID: replication

イベントリスナー event-listener

AEMaaCS イベント処理セマンティクスのために更新する必要があるOSGi EventListenerまたはEventHandler実装をターゲットにします。

BPA パターン ID: eventListener

イベントハンドラー event-handler

AEMaaCSに適応させる必要がある同期OSGi EventHandler サービスをターゲットにします。

BPA パターン ID: eventHandler

Asset API asset-api

非推奨のAssetManager、DAMEvent、またはサポートされていないDAM APIを使用してクラスをターゲットにします。 Agentは、サポートされているAEM Assets API同等の機能に置き換えます。

BPA パターン ID: assetApi

カフェインへのGuava キャッシュ guava-cache

Guavaのキャッシュ （com.google.common.cache.*、Cache、CacheBuilder、LoadingCacheなど）を使用するバンドルをターゲットにします。 AEM as a Cloud Serviceでは、サポートされているインプロセスキャッシュライブラリはCaffeineであるため、エージェントはMavenの依存関係を入れ替え、インポートを更新し、影響を受けるコールサイトを調整します。 カフェインは同じ著者によって書かれており、そのAPIは意図的にほぼ同じであるため、変更はほとんどが機械的です。

BPA パターン ID: guavaCache

BPAはこのパターンを​ バンドル ​の精度（サブタイプ custom.guava.cache）で報告するので、エージェントはバンドルをGuava キャッシュを実際に読み込むJava ファイルに解決し、それらを編集します。 Guava キャッシュの使用は、従来のCloud Serviceから引き継いだコードでのみ行われ、ネイティブのAEM コードでは行われないので、このパターンはcode-assessmentではなく、移行スキルでのみ提供されます。

InputStream使用状況 input-stream

BPAがjava.io.InputStream使用にフラグを付けるJava コードをターゲットにします（サブタイプ java.io.inputstream）。 AEM as a Cloud Serviceでは、JVMを介して大きなバイナリをストリーミングするとコンテナメモリを使い果たすことができるため、バイナリを直接Cloud Blob StoreおよびCDNからアップロードして配信する必要があります（開発ガイドライン ​および直接バイナリアップロード ​を参照）。

BPA パターン ID: inputStream

エージェントはリスクごとに調査結果を分類し、各グループを異なる方法で処理します。

次の内容でセッションを開始：

Fix inputStream findings using BPA CSV at ./reports/bpa.csv

HTL Lint （data-sly-test） htl-lint

data-sly-test: redundant constant value comparison回のプリント警告を生成するui.apps以下のHTL テンプレートをターゲットにします。 エージェントは、コンテンツパッケージを直接スキャンすることで、影響を受けるテンプレートを検出します。このパターンでは、BPA CSVまたはCAM接続は必要ありません。

BPA パターン ID: htlLint

CLOUD MANAGERへのOSGi設定 osgi-cloud-manager

ui.configのOSGi設定を、完全な環境固有の処理を使用して、Cloud Manager互換の.cfg.json形式に変換します。 いくつかの関連タスクについて説明します。

形式の変換​を構成

AEMaaCSでは、OSGi設定を.cfg.json ファイルとして保存し、環境固有の設定を実行モードでスコープ設定されたフォルダー（config.author/、config.publish/、config.dev/など）に格納する必要があります。 エージェント：

秘密鍵と環境変数

コミットされた設定ファイルからプレーンテキストシークレットと環境固有の値を移動し、Cloud Managerのプレースホルダーに置き換えます。

対応する変数とシークレットはCloud Managerに適用され、実行時に挿入されます。値はソースコントロールに保存されません。

サポートされていない実行モード （URC）

AEM as a Cloud Serviceでは、固定の実行モード ID セットをサポートしています。 サポートされていない実行モードを使用する設定フォルダーは、一度デプロイしても効果がありません。 エージェントは、次のようなサポートされていない実行モード設定（URC）にフラグを立てます。

URCの結果は、最初にベストプラクティスアナライザー（サブタイプ unsupported.runmode、重大度CRITICAL）から得られます。BPA ソースが報告しない場合、エージェントはconfig.*およびinstall.*個のフォルダーをセーフティネットとしてローカルにスキャンします。 検出するたびに、フォルダーパス、問題のある実行モード、および修復が報告されます。設定がまだ必要かどうかを評価し、サポートされている実行モードに変更するか、古い場合は削除します。 注文のみの違反の場合、すべてのトークンが有効ですが、注文されていない場合、エージェントは安全な再注文を自動的に適用できます（例えば、config.dev.authorをconfig.author.devに変更）。不明なトークンやその他のあいまいなケースにはフラグが付けられ、解決できます。

構成形式の変換と秘密鍵の外部化にはBPA CSVまたはCAMは必要ありません。URC検出では、使用可能な場合にBPAの結果が使用されます。 次の内容でセッションを開始：

Scan my config files and create Cloud Manager environment secrets or variables.

ダイアログの移行（レガシーUI） dialog-migration

クラシック UI ダイアログをタッチ UIに変換します。 エージェントは2つのダイアログサブタイプを処理します。ExtJS / Classic UI cq:Dialogの定義はCoral 3 _cq_dialog構造として再構築され、既存のCoral 2 ダイアログはCoral 3にアップグレードされます。 また、リスナー、optionsProvider、namePrefixおよび更新filter.xmlも引き継ぎます。

BPA パターン ID: lui （ダイアログ サブタイプのみ）

同じコンポーネントに対してダイアログとカスタムウィジェットの両方の結果が存在する場合は、最初にカスタムウィジェットの移行を実行して、ダイアログが変換される前にすべてのxtype参照が解決されるようにします。

Convert my Classic UI dialogs to Touch UI Coral 3.

カスタムデザインウィジェット（従来のUI） custom-design-widgets

カスタム ExtJS ウィジェット （cq:Widget定義とカスタム xtype値）を移行します。 エージェントはウィジェットをインベントリし、各xtypeを既知のCoral 3にマッピングするか、直接マッピングが存在しない場合にGranite UI フォームコンポーネントを基礎モードにします。

BPA パターン ID: cdw

Migrate my custom ExtJS widgets (CDW findings) from CAM.

テンプレートの近代化 template-modernization

静的テンプレートを編集可能なテンプレートに変換し、対応するAEM Modernize Tools書き換えルール（構造、コンポーネント、ポリシールール）を生成します。 エージェントは、テンプレートを検出してテンプレートごとのプランを生成し、テンプレートごとにプラン テンプレートを実行し、生成された/conf構造を検証するという3つのフェーズで実行されます。

発見時に、エージェントは、ネストまたはグループ化されたテンプレートフォルダーを含むapps/<appId>/templates/の下のテンプレートを任意の深さで移動し、ページコンポーネントのリソースタイプに基づいて、各静的テンプレートをレガシーまたはカスタムとして分類します。 この分類は、BPA レポートがなくても保持されるため、カスタムテンプレートはレガシーテンプレートとは異なる方法で処理されます。

このパターンでは、BPA パターン IDは使用されません。 次の内容でセッションを開始：

Migrate my static templates to editable templates and generate the Modernize Tools rewrite rules.

Dispatcher コンバージョン dispatcher-conversion

AMSまたはオンプレミスのApache HTTPDおよびDispatcher設定をAEM as a Cloud Service構造に変換します。 この機能は、Adobeが管理するDispatcher Converter ツールをラップし、検出、設定の生成、出力検証、検証を追加します。

エージェントは段階的なフローで動作します。

Runbook パターン id: dispatcherConversion （設定レイアウトからヒューリスティックに検出されました）。 このパターンでは、BPAやCAMは使用されません。 次の内容でセッションを開始：

Convert my AMS / on-prem Dispatcher config to AEM as a Cloud Service.

Oak インデックスの移行 oak-index

ui.apps/.../_oak_index/の従来のOak インデックス定義をAEM as a Cloud Service互換の定義に変換します。 この機能により、Adobeは、コンバージョンルールを再実装するのではなく、Index Converter ツールを維持しています。 カスタム Lucene インデックスと、その場で変更された標準のインデックスについて説明します。

BPA パターン ID: oakIndex （サブタイプ index.rule.violationおよびstandard.index.modification）

エージェントはコンバーターを実行し、データタイプの互換性チェックで差分を表示し、確認した後にのみ変更を適用し、次にui.appsをビルドしてAEM アナライザーを実行します。

AEM as a Cloud Serviceでは、-custom-<n> バージョンのサフィックスを含めるカスタムインデックスが必要です。定義が変更されるたびに<n>は増加します（​ インデックス名を参照）。 エージェントは次の空き<n>を選択するので、繰り返し移行しても既存のインデックスは上書きされません。

パターンは現在、従来の_oak_index形式を生成しています。 ターゲット形式としての簡易インデックス管理は計画されていますが、まだサポートされていません。

次の内容でセッションを開始：

Fix oakIndex findings using BPA CSV at ./reports/bpa.csv

移行の検証 validate-migration

パターンを移行した後、エージェントはローカルのAEM as a Cloud Service SDKで結果を確認できます。 検証はコードに対して読み取り専用です。エージェントはパスを取得するためにソースを編集しません。 チェックが失敗した場合、修正はコードを所有する移行パターンに戻ります。

検証はこれらのパターンをサポートします。

Dispatcherのコンバージョン設定やOSGi設定など、その他のパターンは検証の対象外です。

必要なパターンについては、Cloud SDKを起動し（デフォルトではhttp://localhost:4602）、AEM クイックスタート MCP サーバーをIDEに追加します。 担当者は次の操作を行います。

プロジェクトがCloud Acceleration Manager プロジェクトにリンクされている場合（移行ランブックを介してリンクされている場合など）、エージェントはAEM MCP ServerのCloud Migration機能を使用してCAMの検証結果も記録します。

次の内容でセッションを開始：

Validate my scheduler migration on the local Cloud SDK.

BPA Source オプション bpa-source

MCP エラー処理 mcp-errors

MCP接続がエラー（プロジェクトが見つからないエラーや認証エラーを含む）を返した場合、エージェントは停止し、エラーを表示します。 自動的に別のソースに切り替わることはありません。 停止した状態から、次のことができます。

大規模なレポートをまたいだセッション管理 large-reports

多くの発見があるBPA レポートの場合、バッチによるバッチ処理のアプローチにより、次の段階的な検証が可能になります。

コミットごとに​ 1つのパターン ​を使用すると、Git履歴を読み取り可能な状態に保つことができ、必要に応じて個々のパターン変換を簡単に元に戻すことができます。

Workspace範囲 workspace-scope

エージェントは、開いているIDE ワークスペースフォルダー内でのみファイルを検索および編集します。 親ディレクトリ、兄弟フォルダー、またはディスク上の他の場所はスキャンしません。

BPA検索がワークスペースに存在しないファイルパスを参照する場合、エージェントは停止し、欠落しているパスを通知します。 正しいプロジェクトフォルダーを開くか、パスを明示的に指定して続行します。