[SaaS uniquement]{class="badge positive" title="S’applique uniquement aux projets Adobe Commerce as a Cloud Service et Adobe Commerce Optimizer (infrastructure SaaS gérée par Adobe)."}

Exécuter une migration de données en bloc

Ce guide est une référence opérationnelle détaillée pour l’exécution d’une migration des données à partir d’une installation PaaS Adobe Commerce ou locale vers Adobe Commerce as a Cloud Service à l’aide de l’outil de migration de données en bloc. Les valeurs de configuration réelles et les détails spécifiques à l’environnement varient en fonction de votre configuration.

Avant de commencer, confirmez que vous avez terminé chaque élément de la liste de contrôle de préparation du client et vérifié l’accès à l’API avec le guide d’accès au service de migration.

Conditions préalables

Configurer le package d’outils

Configurez l’environnement pour la migration de données en bloc :

Exemples de fichiers de configuration

Les fichiers .example.env et .my.cnf.example de la racine du référentiel constituent le point de départ de votre configuration. Copiez chaque fichier dans son nom de travail et renseignez les valeurs requises.

Configuration du fichier d’environnement

Le fichier .env dans la racine du projet est la configuration de migration et d’extraction. Il pilote le pipeline de l’interface de ligne de commande, y compris les URL source et cible, OAuth, la connexion CDMS distante, l’authentification SaaS et IMS et d’autres commutateurs.

Modifiez le fichier .env et définissez correctement au moins les valeurs suivantes. Pour obtenir la liste complète des variables prises en charge, reportez-vous aux annotations intégrées dans .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>

Configuration des informations d’identification OAuth source

Ces quatre valeurs signent les requêtes de l’outil de migration vers les API du magasin source. Pour les obtenir, ouvrez le Admin source et accédez à Système > Extensions > Intégrations. Créez ou ouvrez une intégration, puis copiez les valeurs dans .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>

Définition du jeton d’interface de ligne de commande Cloud

Aligner les paramètres d’administration Commerce

Avant la migration, assurez-vous que les paramètres suivants sont cohérents entre la source et la cible.

Configuration des identifiants SaaS et IMS cibles

Il s’agit des paramètres IMS et API Adobe Commerce as a Cloud Service pour la cible. Vous avez besoin de l’identifiant du client, de l’identifiant de l’organisation, des informations d’identification de serveur à serveur OAuth IMS et de l’hôte IMS approprié pour votre environnement. Assurez la coordination avec votre équipe Adobe pour l’accès à l’organisation, au client et au profil. N’essayez pas de déduire ou d’estimer des valeurs sensibles.

Générer les informations d’identification IMS

Utiliser le 🔗. Vous avez besoin d’un accès Developer ou Admin à l’organisation Adobe pour créer des projets. Une connexion utilisateur de base ne suffit pas pour ajouter des API.

Le point d’entrée du jeton IMS (ADOBE_IMS_URL) doit correspondre à l’environnement des informations d’identification.

ADOBE_IMS_META_SCOPES doit correspondre aux étendues configurées sur ces informations d’identification. Le fichier .example.env inclut la chaîne de portée complète séparée par des virgules comme référence. Modifiez-la uniquement si Adobe vous le demande.

Mapper les informations d’identification Adobe I/O au fichier d’environnement

Dans Developer Console, les valeurs de serveur à serveur OAuth sont présentées sous la forme d’un identifiant client et d’un secret client, correspondant à la structure JSON suivante :

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

Mappez-les dans des .env (exemples d’espaces réservés) :

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

Les hôtes de l’API SaaS diffèrent entre la pré-production et la production. TARGET_INSTANCE_REST_URL et TARGET_INSTANCE_GRAPHQL_URL doivent utiliser le même environnement d’API Commerce que votre migration, que ce soit en préproduction ou en production. Ne mélangez pas un niveau avec le système de gestion de la relation client (CDMS) ou le client de l’autre niveau.

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

Pour les hôtes SaaS de production, remplacez na1-sandbox par na1 dans les deux URL TARGET_INSTANCE_*. Utilisez les ADOBE_IMS_URL correspondantes pour ce niveau, comme indiqué dans le tableau précédent.

Définir le point d’entrée CDMS

Pointez l’outil de migration sur l’hôte de l’API CDMS correspondant à l’environnement vers lequel vous migrez. Définissez CDMS_HOST (et généralement CDMS_PORT=443) dans .env. Utilisez un hôte, en préproduction ou en production, mais pas les deux.

Définissez ou supprimez les commentaires du bloc correspondant à votre exécution :

# 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

Définir le code du magasin

STORE_CODE est le code d’affichage du magasin utilisé par l’outil de migration pour les appels API REST de l’instance source, la création d’un client de test synthétique et le nettoyage des données. Il est également envoyé en tant qu’en-tête x-store-code pendant la phase de chargement.

STORE_CODE valeur par défaut est default dans .example.env. Vérifiez que cela correspond au code d’affichage du magasin par défaut de votre instance source. Pour vérifier, dans la Admin source, accédez à Magasins > Tous les magasins et regardez la colonne Code pour l’affichage du magasin qui doit être utilisé. Si le code affiché n’est pas default, mettez à jour le STORE_CODE dans .env pour qu’il corresponde.

Configurer le fichier de connexion à la base de données

Le fichier .my.cnf fournit MySQL paramètres de connexion pour le côté extraction de l’outil de migration. Créez-le en copiant les .my.cnf.example dans les .my.cnf de la racine du projet. Le nom de la section doit correspondre à SOURCE_CONNECTION_NAME dans .env.

Pour une source sur site ou auto-hébergée :

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

Pour une source Adobe Commerce on Cloud :

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

Le champ id= indique à l’outil que la source est PaaS et déclenche la configuration du tunnel à l’aide de MAGENTO_CLOUD_CLI_TOKEN. Les valeurs project_id et environment sont disponibles dans le Cloud Console ou par le biais des commandes magento-cloud project:list et magento-cloud environment:list .

Préparation du réseau et des instances

L’authentification de base HTTP devant le magasin peut bloquer le trafic d’API et d’outils. Assurez-vous qu’elle est désactivée pour l’URL source utilisée par la migration ou que les chemins d’accès de l’outil sont autorisés, de sorte que les requêtes REST et GraphQL puissent atteindre le magasin .

Maintenir la stabilité de la base de données source pendant l’extraction

Tandis que l’outil extrait les données de la base de données source, aucun autre processus ne doit y écrire. Les écritures simultanées peuvent entraîner un instantané incohérent.

Target

Si le catalogue cible doit être effacé avant la migration, supprimez les produits en Admin par petits lots, par exemple 200 à la fois, afin d’éviter les conflits de catalogues en double et les délais de suppression en masse.

Créer et exécuter la migration

Travaillez à partir du répertoire du projet extrait avec un accès en écriture.

Maintenir la session active via SSH

Si vous vous connectez via SSH, un réseau abandonné peut tuer votre shell et interrompre une longue migration. La commande GNU screen maintient la session active sur le serveur :

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"

Vous pouvez également utiliser tmux s’il est disponible sur le serveur.

Créer l’image Docker

Créez l’image Docker utilisée par bin/console, qui contient PHP, l’interface de ligne de commande et les dépendances. Exécutez cette opération avant la première exécution ou après les modifications du fichier Docker ou de l’image de base.

./bin/console build

Démarrer les services de support

Démarrez les services de sauvegarde Docker Compose de l’outil, tels que la base de données de test locale, puis, lorsqu’ils sont activés dans .env, les services locaux facultatifs. Les services exacts dépendent de votre configuration. Exécutez cette opération après une génération réussie et avant le shell, la migration ou les commandes par phases.

./bin/console start

Initialiser le conteneur d’interface de ligne de commande

Démarrez une seule fois le conteneur de l’interface de ligne de commande afin que le point d’entrée puisse terminer la configuration (une installation Composer, par exemple) pour votre projet monté. Exécutez cette opération une fois avant la première exécution de migration dans un nouvel environnement.

./bin/console shell
exit

Exécuter la migration

L’outil prend en charge deux approches de migration. Choisissez celui qui correspond à votre cas d’utilisation.

Migration monophasée

Aucun mode de maintenance n’est requis sur l’instance source. Exécutez le pipeline de migration complet avec une seule commande :

./bin/console migration

La commande exécute automatiquement toutes les étapes du pipeline de bout en bout, dans l’ordre suivant.

Utilisez cette option lorsqu’aucune fenêtre de maintenance n’est requise, ce qui est courant pour les exécutions sèches de bout en bout, les environnements de développement ou de sandbox, ou toute migration où la source peut rester active pendant l’extraction.

Migration multiphase avec mode de maintenance

Le mode de maintenance est requis sur l’instance source pour garantir la cohérence des données lors de l’extraction. La migration est divisée en phases distinctes que vous devez exécuter dans l’ordre.

Phase 1 — Avant la maintenance (la source est active)

S’exécute lorsque l’instance source est active et accepte le trafic. L’accès REST et GraphQL à la source doit être entièrement disponible. N’activez pas le mode de maintenance avant la fin de cette phase.

Revenez à la racine du serveur et exécutez :

./bin/console migration:before-maintenance

Phase 2 — Activer le mode de maintenance (manuel)

Activez le mode de maintenance sur la source et mettez en pause toutes les activités qui écrivent dans la base de données ou qui ont un impact sur celle-ci, y compris les tâches planifiées, les intégrations tierces, le traitement des commandes et la synchronisation des ressources multimédias.

Sur le serveur Commerce source (racine d’installation), exécutez :

bin/magento maintenance:enable

Phase 3 — Pendant la maintenance (la source est gelée)

Exécutez avec l’instance source en mode de maintenance. La source doit rester gelée pendant toute la durée de cette phase. Ne désactivez pas le mode de maintenance tant que la Phase 3 n’est pas terminée.

./bin/console migration:during-maintenance

Phase 4 — Désactiver le mode de maintenance (manuelle, conditionnelle)

Cette phase désactive le mode de maintenance et réactive le trafic vers l’instance source. Cette étape est requise avant d’exécuter la phase de nettoyage, car le nettoyage communique avec la source via REST et échoue avec HTTP 503 si le mode de maintenance est toujours actif.

Sur le serveur Commerce source, exécutez :

bin/magento maintenance:disable

Phase 5 — Nettoyage (facultatif, la source doit être active)

Supprimez les clients et commandes de test synthétique créés dans Phase 1 de l’instance source via REST. Cette phase ne peut s’exécuter qu’une fois le mode de maintenance désactivé.

Revenez à la racine du serveur et exécutez :

./bin/console migration:cleanup

Reprise ou réexécution d’une migration

L’outil de migration suit la progression à l’aide d’un fichier .migration_id dans la racine du projet. Ce fichier est créé automatiquement lorsqu’une nouvelle migration démarre et enregistre l’identifiant de migration actuel.

Reprendre après un échec

Si une exécution de migration échoue ou est interrompue, exécutez à nouveau la même commande pour reprendre à partir de la dernière étape réussie (extraction, chargement ou vérification) plutôt que de redémarrer à partir de zéro. Les étapes déjà terminées sont automatiquement ignorées.

Démarrer une nouvelle migration

Pour annuler une exécution précédente et démarrer une migration entièrement nouvelle, supprimez le fichier .migration_id avant de démarrer la migration suivante :

rm .migration_id

Si .migration_id existe et que la migration précédente est déjà terminée, l’outil imprime un message indiquant que la migration est déjà terminée et vous conseille de supprimer le fichier.

Vérifier les journaux et le débogage

Tous les journaux de migration sont écrits dans le répertoire logs/ dans la racine du projet et sont organisés en sous-répertoires horodatés :

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