[Nur SaaS]{class="badge positive" title="Gilt nur für Adobe Commerce as a Cloud Service- und Adobe Commerce Optimizer-Projekte (von Adobe verwaltete SaaS-Infrastruktur)."}

Ausführen einer Massendatenmigration

Dieses Handbuch ist eine schrittweise Anleitung zum Ausführen einer Datenmigration von einer Adobe Commerce PaaS- oder On-Premise-Installation zum Adobe Commerce as a Cloud Service mithilfe des Tools für die Massendatenmigration. Die tatsächlichen Konfigurationswerte und umgebungsspezifischen Details variieren je nach Einrichtung.

Bevor Sie beginnen, vergewissern Sie sich, dass Sie alle Elemente in der Checkliste zur Kundenbereitschaft“ abgeschlossen ​ den API-Zugriff mit dem Migrationsservice-Zugriffshandbuch“ ​ haben.

Voraussetzungen

Einrichten des Tool-Pakets

Einrichten der Umgebung für die Massendatenmigration:

Beispielkonfigurationsdateien

Die .example.env- und .my.cnf.example-Dateien im Repository-Stamm sind der Ausgangspunkt für Ihre Konfiguration. Kopieren Sie jede Datei in ihren Arbeitsnamen und geben Sie die erforderlichen Werte ein.

Konfigurieren der Umgebungsdatei

Die .env Datei im Projektstamm ist die Migrations- und Extraktionskonfiguration. Sie steuert die CLI-Pipeline, einschließlich Quell- und Ziel-URLs, OAuth, der Remote-CDMS-Verbindung, SaaS- und IMS-Authentifizierung und anderer Switches.

Bearbeiten Sie die .env und legen Sie mindestens die folgenden Werte korrekt fest. Eine vollständige Liste der unterstützten Variablen finden Sie in den Inline-Anmerkungen in .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>

Konfigurieren der OAuth-Quellberechtigungen

Diese vier Werte signieren Anfragen vom Migrations-Tool an die Quell-Store-APIs. Um sie zu erhalten, öffnen Sie die Admin und navigieren Sie zu System > Erweiterungen > Integrationen. Erstellen oder öffnen Sie eine Integration und kopieren Sie dann die Werte in .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>

Festlegen des Cloud-CLI-Tokens

Commerce-Admin-Einstellungen ausrichten

Stellen Sie vor der Migration sicher, dass die folgenden Einstellungen zwischen Quelle und Ziel konsistent sind.

Target SaaS- und IMS-Anmeldedaten konfigurieren

Dies sind die Adobe Commerce as a Cloud Service IMS- und API-Einstellungen für das Ziel. Sie benötigen die Mandanten-ID, die Organisations-ID, die IMS-OAuth-Server-zu-Server-Anmeldeinformationen und den richtigen IMS-Host für Ihre Umgebung. Abstimmung mit Ihrem Adobe-Team für Organisations-, Mandanten- und Profilzugriff. Versuchen Sie nicht, vertrauliche Werte abzuleiten oder zu schätzen.

IMS-Anmeldeinformationen generieren

Verwenden Sie die Adobe Developer Console. Sie benötigen Developer oder Admin Zugriff auf die Adobe-Organisation, um Projekte zu erstellen. Eine einfache Benutzeranmeldung reicht nicht aus, um APIs hinzuzufügen.

Der IMS-Token-Endpunkt (ADOBE_IMS_URL) muss mit der Umgebung der Berechtigung übereinstimmen.

ADOBE_IMS_META_SCOPES muss mit den für diese Berechtigung bereitgestellten Bereichen übereinstimmen. Die .example.env-Datei enthält die vollständige, durch Kommas getrennte Bereichszeichenfolge als Referenz. Ändern Sie sie nur, wenn Adobe Sie dazu anweist.

Zuordnen Adobe I/O Anmeldeinformationen zur Umgebungsdatei

In Developer Console werden die OAuth-Server-zu-Server-Werte als Client-ID und Client-Geheimnis dargestellt, die der folgenden JSON-Struktur entsprechen:

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

Ordnen Sie sie .env zu (Beispiel-Platzhalter):

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

Die SaaS-API-Hosts unterscheiden sich zwischen der Vorproduktion und der Produktion. TARGET_INSTANCE_REST_URL und TARGET_INSTANCE_GRAPHQL_URL müssen dieselbe Commerce-API-Umgebung wie Ihre Migration verwenden, entweder vor der Produktion oder in der Produktion. Mischen Sie keine Ebene mit dem CDMS oder Mandanten der anderen Ebene.

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

Ersetzen Sie bei SaaS-Produktions-Hosts in beiden TARGET_INSTANCE_*-URLs na1-sandbox durch na1. Verwenden Sie den entsprechenden ADOBE_IMS_URL für diese Ebene, wie in der vorherigen Tabelle dargestellt.

Festlegen des CDMS-Endpunkts

Zeigen Sie mit dem Migrations-Tool auf den CDMS-API-Host, der der Umgebung entspricht, zu der Sie migrieren. CDMS_HOST (und normalerweise CDMS_PORT=443) in .env festlegen. Verwenden Sie einen Host, entweder vor der Produktion oder in der Produktion, aber nicht beides.

Legen Sie den Block fest, der Ihrer Ausführung entspricht, oder heben Sie den Kommentar auf:

# 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

Festlegen des Store-Codes

STORE_CODE ist der Code der Speicheransicht, der vom Migrations-Tool für REST-API-Aufrufe der Quellinstanz, die Erstellung synthetischer Tests und die Datenbereinigung verwendet wird. Sie wird auch während der Ladephase als x-store-code-Header gesendet.

STORE_CODE Standardwert ist default in .example.env. Stellen Sie sicher, dass dies mit dem Standard-Code der Store-Ansicht Ihrer Quellinstanz übereinstimmt. Um dies zu überprüfen, gehen Sie in der Admin zu Stores > Alle Stores und suchen Sie in der Spalte Code nach der Store-Ansicht, die verwendet werden sollte. Wenn der dort angezeigte Code nicht default wird, aktualisieren Sie STORE_CODE in .env entsprechend.

Datenbankverbindungsdatei konfigurieren

Die .my.cnf-Datei enthält MySQL Verbindungseinstellungen für die Extraktionsseite des Migrations-Tools. Erstellen Sie sie durch Kopieren von .my.cnf.example nach .my.cnf im Projektstamm. Der Abschnittsname muss mit SOURCE_CONNECTION_NAME in .env übereinstimmen.

Für eine lokale oder selbst gehostete Quelle:

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

Für eine Adobe Commerce on Cloud:

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

Das id= Feld teilt dem Tool mit, dass die Quelle PaaS ist und dass der Trigger-Tunnel mithilfe von MAGENTO_CLOUD_CLI_TOKEN eingerichtet wird. Die project_id- und environment sind in der Cloud Console oder über die magento-cloud project:list- und magento-cloud environment:list verfügbar.

Vorbereiten des Netzwerks und der Instanzen

Die einfache HTTP-Authentifizierung vor dem Store kann API- und Tool-Traffic blockieren. Stellen Sie sicher, dass sie für die von der Migration verwendete Quell-URL deaktiviert ist oder dass die Pfade des Tools zulässig sind, sodass REST- und GraphQL-Anfragen den Store erreichen können.

Wahrung der Stabilität der Quelldatenbank während der Extraktion

Während das Tool Daten aus der Quelldatenbank extrahiert, sollten keine anderen Prozesse in sie schreiben. Gleichzeitige Schreibvorgänge können zu einem inkonsistenten Snapshot führen.

Target

Wenn der Zielkatalog vor der Migration gelöscht werden muss, löschen Sie Produkte in Admin in kleinen Batches, z. B. jeweils 200, um doppelte Katalogkonflikte und Zeitüberschreitungen bei der Massenlöschung zu vermeiden.

Erstellen und Ausführen der Migration

Arbeiten aus dem extrahierten Projektverzeichnis mit Schreibzugriff.

Halten Sie die Sitzung über SSH am Leben

Wenn Sie eine Verbindung über SSH herstellen, kann ein ausgelassenes Netzwerk Ihre Shell zerstören und eine lange Migration unterbrechen. Der GNU-screen-Befehl hält die Sitzung auf dem Server am Leben:

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"

Sie können auch tmux verwenden, wenn es auf dem Server verfügbar ist.

Docker-Image erstellen

Erstellen Sie das von bin/console verwendete Docker-Image, das PHP, die CLI und Abhängigkeiten enthält. Führen Sie dies vor der ersten Ausführung oder nach Docker-Datei- oder Basisbildänderungen aus.

./bin/console build

Starten der unterstützenden Services

Starten Sie die Docker Compose für das Tool, z. B. die lokale Testdatenbank und, wenn in .env aktiviert, optionale lokale Services. Die genauen Dienste hängen von Ihrer Konfiguration ab. Führen Sie dies nach einem erfolgreichen Build und vor den Befehlen Shell, Migration oder Schrittweise aus.

./bin/console start

Initialisieren des CLI-Containers

Starten Sie den CLI-Container einmal, damit der Einstiegspunkt die Einrichtung für Ihr bereitgestelltes Projekt abschließen kann, z. B. eine Composer Installation. Führen Sie dies einmal vor der ersten Migrationsausführung in einer neuen Umgebung aus.

./bin/console shell
exit

Ausführen der Migration

Das Tool unterstützt zwei Migrationsansätze. Wählen Sie den für Ihren Anwendungsfall passenden aus.

Einphasige Migration

Auf der Quellinstanz ist kein Wartungsmodus erforderlich. Führen Sie die vollständige Migrations-Pipeline mit einem einzigen Befehl aus:

./bin/console migration

Der Befehl führt alle Pipeline-Schritte automatisch von Ende zu Ende in der folgenden Reihenfolge aus.

Verwenden Sie diese Option, wenn kein Wartungsfenster erforderlich ist, was typisch für End-to-End-Trockenläufe, Entwicklungs- oder Sandbox-Umgebungen oder für eine Migration ist, bei der die Quelle während der Extraktion live bleiben kann.

Mehrphasige Migration mit Wartungsmodus

Der Wartungsmodus ist auf der Quellinstanz erforderlich, um die Datenkonsistenz während der Extraktion sicherzustellen. Die Migration ist in verschiedene Phasen unterteilt, die Sie in der richtigen Reihenfolge ausführen müssen.

Phase 1 — Vor der Wartung (Quelle ist aktiv)

Führen Sie aus, während die Quellinstanz live ist und Traffic akzeptiert. Der Zugriff von REST und GraphQL auf die -Quelle muss vollständig verfügbar sein. Aktivieren Sie den Wartungsmodus nicht, bevor diese Phase abgeschlossen ist.

Kehren Sie zum Serverstamm zurück und führen Sie Folgendes aus:

./bin/console migration:before-maintenance

Phase 2 — Wartungsmodus aktivieren (manuell)

Aktivieren Sie den Wartungsmodus an der Quelle und pausieren Sie alle Aktivitäten, die in die Datenbank schreiben oder sich auf sie auswirken, einschließlich geplanter Aufträge, Drittanbieterintegrationen, Bestellverarbeitung und Synchronisierung von Medien-Assets.

Führen Sie auf dem Commerce-Quellserver (Installationsstamm) Folgendes aus:

bin/magento maintenance:enable

Phase 3 — Während der Wartung (Quelle eingefroren)

Mit der Quellinstanz im Wartungsmodus ausführen. Die Quelle muss für die gesamte Dauer dieser Phase eingefroren bleiben. Deaktivieren Sie den Wartungsmodus erst, wenn Phase 3 erfolgreich abgeschlossen wurde.

./bin/console migration:during-maintenance

Phase 4 — Wartungsmodus deaktivieren (manuell, bedingt)

In dieser Phase wird der Wartungsmodus deaktiviert, sodass der Traffic zur Quellinstanz wieder aktiviert wird. Dieser Schritt ist erforderlich, bevor die Bereinigungsphase ausgeführt wird, da die Bereinigung über REST mit der Quelle kommuniziert und mit HTTP 503 fehlschlägt, wenn der Wartungsmodus noch aktiv ist.

Führen Sie auf dem Commerce-Quellserver Folgendes aus:

bin/magento maintenance:disable

Phase 5 - Bereinigung (optional, Quelle muss live sein)

Entfernen Sie die in Phase 1 erstellten Kundinnen und Kunden sowie Bestellungen synthetischen Tests REST aus der Quellinstanz. Diese Phase kann nur ausgeführt werden, nachdem der Wartungsmodus deaktiviert wurde.

Kehren Sie zum Serverstamm zurück und führen Sie Folgendes aus:

./bin/console migration:cleanup

Fortsetzen oder erneutes Ausführen einer Migration

Das Migrations-Tool verfolgt den Fortschritt mithilfe einer .migration_id Datei im Projektstamm. Diese Datei wird beim Start einer neuen Migration automatisch erstellt und zeichnet die aktuelle Migrationskennung auf.

Nach einem Fehler fortsetzen

Wenn ein Migrationsdurchgang fehlschlägt oder unterbrochen wird, führen Sie denselben Befehl erneut aus, um ihn vom letzten erfolgreichen Schritt (Extraktion, Laden oder Verifizierung) aus fortzusetzen, anstatt von Grund auf neu zu starten. Bereits abgeschlossene Schritte werden automatisch übersprungen.

Starten einer neuen Migration

Um einen vorherigen Durchlauf zu verwerfen und eine völlig neue Migration zu starten, löschen Sie die .migration_id-Datei, bevor Sie die nächste Migration beginnen:

rm .migration_id

Wenn .migration_id vorhanden und die vorherige Migration bereits abgeschlossen ist, druckt das Tool eine Meldung, die besagt, dass die Migration bereits abgeschlossen ist, und empfiehlt, die Datei zu löschen.

Überprüfen von Protokollen und Debugging

Alle Migrationsprotokolle werden in das logs/ im Projektstammverzeichnis geschrieben und in Unterverzeichnisse mit Zeitstempel unterteilt:

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