[SaaSのみ]{class="badge positive" title="Adobe Commerce as a Cloud ServiceおよびAdobe Commerce Optimizer プロジェクト（Adobeが管理するSaaS インフラストラクチャ）にのみ適用されます。"}

一括データ移行の実行

このガイドは、一括データ移行ツールを使用して、Adobe Commerce PaaSまたはオンプレミスのインストールからAdobe Commerce as a Cloud Serviceへのデータ移行を実行するための手順ごとの運用上のリファレンスです。 実際の設定値と環境固有の詳細は、設定によって異なります。

開始する前に、顧客準備チェックリスト ​のすべての項目を完了し、移行サービスアクセスガイド ​でAPI アクセスを確認したことを確認してください。

前提条件

ツールパッケージの設定

一括データ移行用の環境を設定します。

設定ファイルの例

リポジトリ ルート内の.example.envおよび.my.cnf.example ファイルは、設定の開始点です。 各ファイルを作業名にコピーし、必要な値を入力します。

環境ファイルの設定

プロジェクト ルートの.env ファイルは、移行と抽出の設定です。 ソースおよびターゲット URL、OAuth、リモート CDMS接続、SaaSおよびIMS認証、その他のスイッチを含むCLI パイプラインを駆動します。

.env ファイルを編集し、少なくとも次の値を正しく設定してください。 サポートされている変数の完全なリストについては、.example.envのインライン注釈を参照してください。

SOURCE_INSTANCE_URL=https://<source-host>
SOURCE_INSTANCE_GRAPHQL_URL=https://<source-host>/graphql
SOURCE_INSTANCE_REST_URL=https://<source-host>/rest
SOURCE_INSTANCE_CONSUMER_KEY=<consumer_key>
SOURCE_INSTANCE_CONSUMER_SECRET=<consumer_secret>
SOURCE_INSTANCE_ACCESS_TOKEN=<access_token>
SOURCE_INSTANCE_ACCESS_TOKEN_SECRET=<access_token_secret>

ソース OAuth資格情報の設定

これらの4つの値は、移行ツールからソースストア APIにリクエストを署名します。 それらを取得するには、ソース Adminを開き、システム > 拡張機能 > 統合​に移動します。 統合を作成するか開いて、値を.envにコピーします。

SOURCE_INSTANCE_CONSUMER_KEY=<consumer_key>
SOURCE_INSTANCE_CONSUMER_SECRET=<consumer_secret>
SOURCE_INSTANCE_ACCESS_TOKEN=<access_token>
SOURCE_INSTANCE_ACCESS_TOKEN_SECRET=<access_token_secret>

Cloud CLI トークンの設定

Commerce管理者設定の調整

移行前に、次の設定がソースとターゲットの間で一貫していることを確認してください。

ターゲット SaaSおよびIMS資格情報の設定

ターゲットのAdobe Commerce as a Cloud Service IMSおよびAPI設定です。 テナント ID、組織ID、IMS OAuth サーバー間の資格情報、および環境に適したIMS ホストが必要です。 Adobeチームと連携して、整理、テナント、プロファイルアクセスを行います。 機密値を推測または推定しようとしない。

IMS資格情報の生成

Adobe Developer Consoleを使用します。 プロジェクトを作成するには、Adobe組織でDeveloperまたはAdminのアクセス権が必要です。 基本的なユーザーログインだけでは、APIを追加することはできません。

IMS トークン エンドポイント （ADOBE_IMS_URL）は、資格情報の環境と一致する必要があります。

ADOBE_IMS_META_SCOPESは、その資格情報でプロビジョニングされたスコープと一致する必要があります。 .example.env ファイルには、完全なコンマ区切りスコープ文字列が参照として含まれています。 Adobeが指示した場合にのみ変更します。

Adobe I/O資格情報を環境ファイルにマッピング

Developer Consoleでは、OAuth サーバー間の値は、次のJSON構造に対応するクライアント IDおよびクライアントシークレットとして表示されます。

{
  "client_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "client_secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

それらを.envにマッピングします（プレースホルダーの例）。

TARGET_ORG_ID=<org_id>@AdobeOrg
ADOBE_IMS_URL=https://ims-na1.adobelogin.com
ADOBE_IMS_CLIENT_ID=xxxxxxxxxxxxxxxxxxxxxxxxxxx
ADOBE_IMS_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxx
ADOBE_IMS_META_SCOPES=AdobeID,openid,additional_info.projectedProductContext

SaaS API ホストは、プリプロダクションとプロダクションで異なります。 TARGET_INSTANCE_REST_URLとTARGET_INSTANCE_GRAPHQL_URLは、実稼動前または実稼動中のいずれの場合も、移行と同じCommerce API環境を使用する必要があります。 一方の階層を他の階層のCDMSまたはテナントと混在させないでください。

TARGET_TENANT_ID=<tenant_id>
TARGET_ORG_ID=<org_id>@AdobeOrg
ADOBE_IMS_URL=https://ims-na1.adobelogin.com
ADOBE_IMS_CLIENT_ID=<client_id>
ADOBE_IMS_CLIENT_SECRET=<client_secret>
ADOBE_IMS_META_SCOPES=AdobeID,openid,additional_info.projectedProductContext
TARGET_INSTANCE_REST_URL=https://na1-sandbox.api.commerce.adobe.com/{tenantId}
TARGET_INSTANCE_GRAPHQL_URL=https://na1-sandbox.api.commerce.adobe.com/{tenantId}/graphql

実稼動SaaS ホストの場合、na1-sandboxをTARGET_INSTANCE_*個のURLでna1に置き換えます。 前の表に示すように、その層に一致するADOBE_IMS_URLを使用します。

CDMS エンドポイントの設定

移行先の環境に一致するCDMS API ホストに移行ツールを指定します。 .envにCDMS_HOST （通常はCDMS_PORT=443）を設定します。 プリプロダクションまたはプロダクションのどちらか1つのホストを使用します。両方を使用しないでください。

実行に一致するブロックを設定またはコメント解除します。

# Pre-production CDMS
CDMS_HOST=https://commerce-data-migration-service-preprod-external.adobe.io
CDMS_PORT=443

# Production CDMS (use for prod cutover only)
# CDMS_HOST=https://na1.api.commerce.adobe.com
# CDMS_PORT=443

ストアコードの設定

STORE_CODEは、移行ツールでソースインスタンス REST API呼び出し、合成テスト顧客の作成、およびデータクリーンアップに使用されるストアビューコードです。 読み込み段階では、x-store-code ヘッダーとしても送信されます。

STORE_CODEのデフォルトは.example.envのdefaultです。 これがソースインスタンスのデフォルトのストアビューコードと一致することを確認します。 確認するには、ソース Adminで​Stores > すべてのStores​に移動し、使用するストアビューの​ Code ​列を確認します。 表示されているコードがdefaultでない場合は、.envのSTORE_CODEを更新して一致させます。

データベース接続ファイルの設定

.my.cnf ファイルには、移行ツールの抽出側のMySQL接続設定が用意されています。 プロジェクト ルートの.my.cnf.exampleを.my.cnfにコピーして作成します。 セクション名は.envのSOURCE_CONNECTION_NAMEと一致する必要があります。

オンプレミスまたはセルフホストのソースの場合：

[<connection-name>]
user=<db_user>
password='<db_password>'
host=<db_host>
port=3306
database=<db_name>

Adobe Commerce on Cloud ソースの場合：

[<connection-name>]
id=<project_id>:<environment>

id= フィールドは、ソースがMAGENTO_CLOUD_CLI_TOKENを使用したPaaSおよびトリガートンネル設定であることをツールに伝えます。 project_idとenvironmentの値は、Cloud Consoleまたはmagento-cloud project:listとmagento-cloud environment:listのコマンドを通じて使用できます。

ネットワークとインスタンスの準備

ストアの前のHTTP Basic Authは、APIとツールのトラフィックをブロックできます。 移行で使用されるソース URLに対して無効にするか、ツールのパスが許可されていることを確認して、RESTおよびGraphQL リクエストがストアに到達できるようにします。

抽出中にソースデータベースの安定性を維持する

ツールはソースデータベースからデータを抽出しますが、他のプロセスはそのデータベースに書き込む必要はありません。 同時に書き込むと、スナップショットに一貫性がなくなることがあります。

Target

移行前にターゲットカタログをクリアする必要がある場合は、カタログの重複や一括削除のタイムアウトを避けるために、一度に200など、Adminの製品を小さなバッチで削除します。

移行のビルドと実行

書き込みアクセス権を持つ抽出されたプロジェクトディレクトリから作業します。

SSH経由でセッションを維持する

SSH経由で接続する場合、ドロップされたネットワークはシェルを殺し、長い移行を中断する可能性があります。 GNU screen コマンドは、サーバー上でセッションを維持します。

screen -S migration          # new session named "migration"
# run ./bin/console commands here; when you want to disconnect without stopping work:
# press Ctrl+A, release, then press d   # detach
screen -ls                   # list sessions
screen -x migration          # reattach to "migration"

サーバーで使用可能な場合は、tmuxを使用することもできます。

Docker イメージのビルド

PHP、CLI、および依存関係を含むbin/consoleで使用されるDocker イメージをビルドします。 これは最初の実行前、またはDockerfileまたはベースイメージの変更後に実行します。

./bin/console build

バッキングサービスの開始

ローカル テスト データベースなどのツールのDocker Compose バッキング サービスを開始し、.envで有効にした場合は、オプションのローカル サービスを開始します。 正確なサービスは、設定によって異なります。 ビルドが成功した後、シェル、移行、または段階的なコマンドの前に、これを実行します。

./bin/console start

CLI コンテナの初期化

インストール済みのプロジェクトに対して、必要に応じてComposerのインストールなどのセットアップを完了できるように、CLI コンテナを1回起動します。 これを1回実行してから、最初の移行を新しい環境で実行します。

./bin/console shell
exit

移行の実行

このツールは、2つの移行アプローチをサポートしています。 ユースケースに合ったものを選びましょう。

単相移行

ソースインスタンスではメンテナンスモードは必要ありません。 単一のコマンドで完全な移行パイプラインを実行します。

./bin/console migration

このコマンドは、次の順序で、すべてのパイプラインステップをエンドツーエンドで自動的に実行します。

このオプションは、エンドツーエンドのドライ実行、開発またはサンドボックス環境、または抽出中にソースがライブのままになる移行に典型的なメンテナンスウィンドウが必要ない場合に使用します。

メンテナンスモードを使用した多相移行

抽出時にデータの一貫性を確保するために、ソースインスタンスではメンテナンスモードが必要です。 移行は、順番に実行する必要がある個別のフェーズに分割されます。

フェーズ 1 — メンテナンス前（ソースが公開されています）

ソースインスタンスがライブでトラフィックを受け入れている間に実行します。 ソースへのRESTおよびGraphQL アクセスは、完全に使用可能である必要があります。 このフェーズが完了する前に、メンテナンスモードを有効にしないでください。

サーバーのルートに戻り、以下を実行します。

./bin/console migration:before-maintenance

フェーズ 2 — メンテナンスモードを有効にする（手動）

ソースでメンテナンスモードを有効にし、スケジュールされたジョブ、サードパーティ統合、注文処理、メディアアセットの同期など、データベースに書き込むか影響を与えるすべてのアクティビティを一時停止します。

ソース Commerce サーバー（インストール ルート）で、次を実行します。

bin/magento maintenance:enable

フェーズ 3 — メンテナンス中（ソースがフリーズしている）

ソースインスタンスでメンテナンスモードで実行します。 ソースは、このフェーズの全期間にわたってフリーズしたままにする必要があります。 フェーズ 3​が正常に完了するまで、メンテナンスモードを無効にしないでください。

./bin/console migration:during-maintenance

フェーズ 4 — メンテナンスモードを無効にする（手動、条件付き）

このフェーズでは、メンテナンスモードが無効になり、ソースインスタンスへのトラフィックが再度有効になります。 クリーンアップはRESTを介してソースと通信し、メンテナンスモードがアクティブな場合はHTTP 503で失敗するため、クリーンアップフェーズを実行する前にこの手順が必要です。

ソース Commerce サーバーで、次を実行します。

bin/magento maintenance:disable

フェーズ 5 — クリーンアップ （オプション、ソースがライブである必要があります）

フェーズ 1​で作成された合成テストの顧客と注文を、RESTを介してソースインスタンスから削除します。 このフェーズは、メンテナンスモードが無効になっている場合にのみ実行できます。

サーバーのルートに戻り、以下を実行します。

./bin/console migration:cleanup

移行の再開または再実行

移行ツールは、プロジェクトルートの.migration_id ファイルを使用して進行状況を追跡します。 このファイルは、新しい移行が開始され、現在の移行識別子が記録されるときに自動的に作成されます。

失敗後に再開

移行の実行が失敗したり、中断されたりした場合は、同じコマンドを再実行して、最初から再開するのではなく、最後に成功したステップ（抽出、読み込み、検証）から再開します。 既に完了した手順は自動的にスキップされます。

新しい移行を開始

前回の実行を破棄して完全に新しい移行を開始するには、次の移行を開始する前に.migration_id ファイルを削除します。

rm .migration_id

.migration_idが存在し、以前の移行が既に完了している場合、移行が既に完了したことを示すメッセージが表示され、ファイルを削除するようにアドバイスされます。

ログの確認とデバッグ

すべての移行ログは、プロジェクトルートのlogs/ ディレクトリに書き込まれ、タイムスタンプ付きのサブディレクトリに整理されます。

logs/
  2026-03-23_14-30-00/     ← one directory per run
    index.log              ← main pipeline log (start here)
    ...