[Solo SaaS]{class="badge positive" title="Applicabile solo ai progetti Adobe Commerce as a Cloud Service e Adobe Commerce Optimizer (infrastruttura SaaS gestita da Adobe)."}

Eseguire una migrazione dati in blocco

Questa guida è un riferimento operativo dettagliato per l’esecuzione di una migrazione dati da un’installazione locale o PaaS Adobe Commerce a Adobe Commerce as a Cloud Service tramite lo strumento di migrazione dati in blocco. I valori di configurazione effettivi e i dettagli specifici dell’ambiente variano a seconda della configurazione.

Prima di iniziare, verifica di aver completato ogni elemento nella Lista di controllo preparazione cliente e di aver verificato l’accesso API con la Guida all’accesso al servizio di migrazione.

Prerequisiti

Configurare il pacchetto di strumenti

Configurare l’ambiente per la migrazione in blocco dei dati:

Esempio di file di configurazione

I file .example.env e .my.cnf.example nella directory principale dell’archivio sono il punto di partenza per la configurazione. Copiare ogni file con il relativo nome di lavoro e inserire i valori richiesti.

Configurare il file di ambiente

Il file .env nella directory principale del progetto è la configurazione di migrazione ed estrazione. Gestisce la pipeline CLI, inclusi gli URL di origine e di destinazione, OAuth, la connessione CDMS remota, l’autenticazione SaaS e IMS e altri switch.

Modificare il file .env e impostare correttamente almeno i valori seguenti. Per l’elenco completo delle variabili supportate, fare riferimento alle annotazioni in linea 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>

Configurare le credenziali OAuth di origine

Questi quattro valori firmano le richieste dallo strumento di migrazione alle API dell’archivio di origine. Per ottenerle, apri l’origine Admin e passa a Sistema > Estensioni > Integrazioni. Creare o aprire un’integrazione, quindi copiare i valori 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>

Impostare il token CLI cloud

Allinea impostazioni amministratore Commerce

Prima della migrazione, assicurati che le seguenti impostazioni siano coerenti tra l’origine e la destinazione.

Configurare le credenziali SaaS e IMS di destinazione

Queste sono le impostazioni IMS e API di Adobe Commerce as a Cloud Service per la destinazione. È necessario disporre dell’ID tenant, dell’ID organizzazione, delle credenziali server-to-server di IMS OAuth e dell’host IMS corretto per l’ambiente. Coordina con il tuo team di Adobe per l’accesso a organizzazione, tenant e profilo. Non tentare di dedurre o stimare valori sensibili.

Genera credenziali IMS

Utilizza Adobe Developer Console. Per creare i progetti è necessario l’accesso Developer o Admin nell’organizzazione Adobe. Un accesso utente di base non è sufficiente per aggiungere le API.

L’endpoint del token IMS (ADOBE_IMS_URL) deve corrispondere all’ambiente delle credenziali.

ADOBE_IMS_META_SCOPES deve corrispondere agli ambiti per i quali è stato eseguito il provisioning in tale credenziale. Il file .example.env include come riferimento la stringa completa dell’ambito separato da virgole. Modificala solo se Adobe ti indica di farlo.

Mappare le credenziali Adobe I/O al file di ambiente

In Developer Console, i valori server-to-server OAuth vengono presentati come un ID client e un segreto client, corrispondenti alla seguente struttura JSON:

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

Mappare in .env (segnaposto di esempio):

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

Gli host API SaaS differiscono tra pre-produzione e produzione. TARGET_INSTANCE_REST_URL e TARGET_INSTANCE_GRAPHQL_URL devono utilizzare lo stesso ambiente API Commerce della migrazione, sia di pre-produzione che di produzione. Non combinare un livello con il CDMS o tenant dell’altro livello.

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

Per gli host SaaS di produzione, sostituire na1-sandbox con na1 in entrambi gli URL TARGET_INSTANCE_*. Utilizzare ADOBE_IMS_URL corrispondente per il livello, come illustrato nella tabella precedente.

Impostare l’endpoint CDMS

Puntare lo strumento di migrazione sull’host dell’API CDMS che corrisponde all’ambiente in cui si sta eseguendo la migrazione. Imposta CDMS_HOST (e in genere CDMS_PORT=443) in .env. Utilizzare un host, di pre-produzione o di produzione, non entrambi.

Imposta o rimuovi il commento dal blocco corrispondente all’esecuzione:

# 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

Imposta il codice store

STORE_CODE è il codice della vista archivio utilizzato dallo strumento di migrazione per le chiamate API REST dell’istanza sorgente, per la creazione di clienti di test sintetici e per la pulizia dei dati. Viene inviato anche come intestazione x-store-code durante la fase di caricamento.

STORE_CODE utilizza default come impostazione predefinita in .example.env. Verifica che corrisponda al codice predefinito della vista archivio dell’istanza sorgente. Per verificare, nell’origine Admin vai a Archivi > Tutti gli archivi e controlla la colonna Codice per la visualizzazione archivio da utilizzare. Se il codice mostrato non è default, aggiornare STORE_CODE in .env per farla corrispondere.

Configurare il file di connessione al database

Il file .my.cnf fornisce le impostazioni di connessione MySQL per il lato di estrazione dello strumento di migrazione. Per crearlo, copia .my.cnf.example in .my.cnf nella directory principale del progetto. Il nome della sezione deve corrispondere a SOURCE_CONNECTION_NAME in .env.

Per un’origine locale o self-hosted:

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

Per un’origine Adobe Commerce on Cloud:

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

Il campo id= indica allo strumento che l’origine è PaaS e attiva la configurazione del tunnel utilizzando MAGENTO_CLOUD_CLI_TOKEN. I valori project_id e environment sono disponibili in Cloud Console o tramite i comandi magento-cloud project:list e magento-cloud environment:list.

Preparare la rete e le istanze

L’autenticazione di base HTTP davanti all’archivio può bloccare il traffico di API e strumenti. Assicurati che sia disabilitato per l’URL di origine utilizzato dalla migrazione o che i percorsi dello strumento siano consentiti, in modo che le richieste REST e GraphQL possano raggiungere l’archivio.

Mantenere la stabilità del database di origine durante l’estrazione

Mentre lo strumento estrae i dati dal database di origine, nessun altro processo deve scrivervi. Le scritture simultanee possono causare uno snapshot incoerente.

Target

Se il catalogo di destinazione deve essere cancellato prima della migrazione, eliminare i prodotti in Admin in piccoli batch, ad esempio 200 alla volta, per evitare conflitti di catalogo duplicati e timeout di eliminazione in blocco.

Creare ed eseguire la migrazione

Lavora dalla directory del progetto estratto con accesso in scrittura.

Mantieni la sessione attiva tramite SSH

Se ti connetti tramite SSH, una rete rilasciata può uccidere la shell e interrompere una migrazione lunga. Il comando GNU screen mantiene la sessione attiva sul server:

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"

È inoltre possibile utilizzare tmux se disponibile nel server.

Creare l’immagine Docker

Genera l’immagine Docker utilizzata da bin/console, che contiene PHP, CLI e dipendenze. Eseguire questa operazione prima della prima esecuzione o dopo la modifica di Dockerfile o immagine di base.

./bin/console build

Avvia i servizi di backup

Avviare i servizi di backup Docker Compose per lo strumento, ad esempio il database di test locale e, se abilitati in .env, i servizi locali facoltativi. I servizi esatti dipendono dalla configurazione. Esegui questa operazione dopo una build corretta e prima dei comandi della shell, della migrazione o della fase.

./bin/console start

Inizializzare il contenitore CLI

Avviare una volta il contenitore CLI in modo che il punto di ingresso possa completare l’installazione, ad esempio un’installazione di Composer se necessaria, rispetto al progetto montato. Esegui questa operazione una volta prima della prima migrazione eseguita in un nuovo ambiente.

./bin/console shell
exit

Eseguire la migrazione

Lo strumento supporta due approcci di migrazione. Scegli quello adatto al tuo caso d’uso.

Migrazione monofase

Non è richiesta alcuna modalità di manutenzione nell’istanza sorgente. Esegui la pipeline di migrazione completa con un singolo comando:

./bin/console migration

Il comando esegue automaticamente tutti i passaggi della pipeline, end-to-end, nell’ordine seguente.

Utilizza questa opzione quando non è necessaria alcuna finestra di manutenzione, tipica per esecuzioni di prova end-to-end, ambienti di sviluppo o sandbox o qualsiasi migrazione in cui l’origine può rimanere attiva durante l’estrazione.

Migrazione multifase con modalità di manutenzione

È necessaria una modalità di manutenzione nell’istanza sorgente per garantire la coerenza dei dati durante l’estrazione. La migrazione è suddivisa in fasi distinte che devono essere eseguite in ordine.

Fase 1 — Prima della manutenzione (l’origine è attiva)

Esegui mentre l’istanza sorgente è attiva e accetta il traffico. L’accesso REST e GraphQL all’origine deve essere completamente disponibile. Non attivare la modalità di manutenzione prima del completamento di questa fase.

Torna alla directory principale del server ed esegui:

./bin/console migration:before-maintenance

Fase 2 - Abilitare la modalità di manutenzione (manuale)

Abilita la modalità di manutenzione nell’origine e sospendi tutte le attività che scrivono nel database o che hanno un impatto su di esso, inclusi i processi pianificati, le integrazioni di terze parti, l’elaborazione degli ordini e la sincronizzazione delle risorse multimediali.

Sul server Commerce di origine (directory principale di installazione), eseguire:

bin/magento maintenance:enable

Fase 3 — Durante la manutenzione (l’origine è bloccata)

Esegui con l’istanza sorgente in modalità manutenzione. L’origine deve rimanere bloccata per l’intera durata di questa fase. Non disattivare la modalità di manutenzione fino al completamento della fase 3.

./bin/console migration:during-maintenance

Fase 4 — Disattivazione della modalità di manutenzione (manuale, condizionale)

Questa fase disattiva la modalità di manutenzione, riabilitando il traffico verso l’istanza sorgente. Questo passaggio è necessario prima di eseguire la fase di pulizia perché la pulizia comunica con l’origine tramite REST e non riesce con HTTP 503 se la modalità di manutenzione è ancora attiva.

Nel server Commerce di origine eseguire:

bin/magento maintenance:disable

Fase 5 — Pulizia (facoltativa, l’origine deve essere attiva)

Rimuovere i clienti e gli ordini del test sintetico creati in Fase 1 dall’istanza di origine tramite REST. Questa fase può essere eseguita solo dopo la disattivazione della modalità di manutenzione.

Torna alla directory principale del server ed esegui:

./bin/console migration:cleanup

Riprendere o eseguire nuovamente una migrazione

Lo strumento di migrazione tiene traccia dell’avanzamento utilizzando un file .migration_id nella directory principale del progetto. Questo file viene creato automaticamente all’avvio di una nuova migrazione e registra l’identificatore di migrazione corrente.

Riprendi dopo un errore

Se un’esecuzione della migrazione non riesce o viene interrotta, esegui nuovamente lo stesso comando per riprendere dall’ultimo passaggio riuscito (estrazione, caricamento o verifica) anziché riavviare il sistema da zero. I passaggi già completati vengono saltati automaticamente.

Avvia una nuova migrazione

Per ignorare un’esecuzione precedente e avviare una migrazione completamente nuova, eliminare il file .migration_id prima di avviare la migrazione successiva:

rm .migration_id

Se .migration_id esiste e la migrazione precedente è già stata completata, lo strumento stampa un messaggio che indica che la migrazione è già stata eseguita e consiglia di eliminare il file.

Revisione dei registri e debug

Tutti i registri di migrazione vengono scritti nella directory logs/ nella directory principale del progetto e sono organizzati in sottodirectory con marca temporale:

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