文件AEM使用手冊

使用AEM Cloud移轉技能 using-cloud-migration-skill

最後更新： 2026年5月27日
  • 適用對象：
  • Experience Manager as a Cloud Service

建立對象：

  • Developer

此參考資料涵蓋各種支援的移轉模式、如何提供BPA發現，以及如何管理大型專案中的工作階段。 如需簡介和設定說明，請參閱概觀。

工作階段的運作方式 workflow-overview

每個移轉工作階段會依照此順序進行：

  1. 命名模式：指定一個模式（例如，scheduler）
  2. 提供發現：從BPA CSV檔案、透過MCP的CAM或特定檔案路徑
  3. 代理程式會讀取轉換規則：此技能會先讀取相關的最佳實務模組，然後再進行任何程式碼變更
  4. 第一批五個：代理程式最多可轉換五個發現專案並報告變更的內容
  5. 您檢閱並繼續：檢閱每個批次後，回覆continue以繼續下一批次

代理程式一次會處理一個模式和一個批次。 不會自動繼續；每個批次都需要您的確認。

移轉模式 patterns

排程器 scheduler

目標鎖定使用與AEMaaCS的無狀態、容器化執行階段不相容sling.commons.scheduler或Scheduler插入的Java類別。

BPA模式識別碼： scheduler

代理程式會使用@Designate將Scheduler插入的工作轉換為Runnable的@Component實作，將建構函式式排程器註冊取代為@Activate / @Deactivate生命週期方法。

ResourceChangeListener resource-change-listener

鎖定需要AEMaaCS更新的ResourceChangeListener或ResourceChange接聽程式實作。

BPA模式識別碼： resourceChangeListener

複製 replication

目標類別匯入com.day.cq.replication.Replicator或AEMaaCS不支援的相關復寫API。 代理程式會以ContentDistribution型對等項取代它們，並更新對應的OSGi服務參照。

BPA模式識別碼： replication

事件監聽器 event-listener

鎖定必須針對AEMaaCS事件處理語意更新的OSGi EventListener或EventHandler實作。

BPA模式識別碼： eventListener

事件處理常式 event-handler

鎖定需要針對AEMaaCS調整的同步OSGi EventHandler服務。

BPA模式識別碼： eventHandler

資產API asset-api

使用已棄用AssetManager、DAMEvent或不支援的DAM API的目標類別。 代理程式會將其取代為支援的AEM Assets API對等函式。

BPA模式識別碼： assetApi

HTL Lint (data-sly-test) htl-lint

鎖定在ui.apps下產生data-sly-test: redundant constant value comparison個Lint警告的HTL範本。 代理程式會透過直接掃描內容套件來探索受影響的範本；此模式不需要BPA CSV或CAM連線。

BPA模式識別碼： htlLint

NOTE
htlLint個發現未出現在BPA CSV匯出中。 當您啟動此模式的工作階段時，代理程式會透過直接檔案掃描來探索這些模式。

Cloud Manager的OSGi設定 osgi-cloud-manager

將ui.config中的OSGi設定轉換為與Cloud Manager相容的.cfg.json格式，並具有完整的環境特定處理。 這涵蓋兩項相關工作：

設定格式轉換

AEMaaCS需要將OSGi設定儲存為.cfg.json個檔案，並在runmode範圍的資料夾（config.author/、config.publish/、config.dev/等）中使用環境特定的設定。 代理程式：

  • 將現有.config、.cfg和XML格式的OSGi設定轉換為.cfg.json
  • 將包含作者和發佈特定值的設定分割為個別執行模式範圍的檔案
  • 根據OSGi中繼型別規格驗證屬性型別（字串、整數、布林值、陣列）
  • 標示Adobe擁有的PID以供手動檢閱，而非自動轉換

密碼和環境變數

將純文字密碼和環境特定值移出已提交的設定檔案，並以Cloud Manager預留位置取代它們：

  • $[secret:NAME]：用於密碼、權杖和其他敏感值
  • $[env:NAME]：針對每個環境不同的非敏感值（例如，服務URL）

對應的變數和秘密會在Cloud Manager中套用，並在執行階段插入；原始檔控制中不會儲存任何值。

IMPORTANT
代理程式絕對不會在交談中輸出秘密值。 所有敏感資料都會寫入授權移交檔案，供您透過Cloud Manager API或UI套用。

此模式不使用BPA CSV或CAM。 開始工作階段於：

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

BPA Source選項 bpa-source

來源
使用時機
BPA CSV檔案
您已從AEM執行個體或Cloud Acceleration Manager匯出CSV。 啟動工作階段時提供檔案路徑。
透過MCP的攝影機
您已設定AEM雲端移轉MCP。 代理程式會列出您的CAM專案、確認要使用的專案，並會直接擷取發現。 請參閱使用雲端移轉MCP。
手動檔案路徑
您要移轉不含BPA報告的特定檔案。 直接在您的提示中提供路徑。

MCP錯誤處理 mcp-errors

如果MCP連線傳回錯誤（包括找不到專案或驗證失敗），代理程式會停止並顯示錯誤。 它不會自動切換到另一個來源。 從已停止狀態，您可以：

  • 從顯示代理程式的清單中確認正確的專案
  • 提供BPA CSV路徑作為替代方法
  • 為手動移轉提供特定的Java檔案路徑

管理大型報表中的工作階段 large-reports

針對具有許多發現專案的BPA報表，逐批次方式可讓您逐步驗證：

  1. 複查每個批次的差異
  2. 使用模式範圍的認可訊息認可批次
  3. 回覆continue以開始下一個批次
  4. 重複此步驟，直到代理程式報告模式的所有發現專案都完成為止

每個認可一個模式​可讓您的Git歷程記錄保持可讀，並視需要輕鬆還原個別模式轉換。

NOTE
如果您在處理所有發現專案之前結束工作階段，請在新的工作階段中使用相同的模式和BPA來源重新啟動。 代理程式會從中斷的地方繼續。

Workspace範圍 workspace-scope

代理程式只會搜尋和編輯開啟的IDE Workspace資料夾中的檔案。 它不會掃描磁碟上的父目錄、同層級資料夾或其他位置。

如果BPA發現所參照的檔案路徑在工作區內不存在，代理程式會停止並告訴您哪些路徑遺失。 開啟正確的專案資料夾或明確提供路徑以繼續。

recommendation-more-help
experience-manager-cloud-service-help-main-toc