[Somente SaaS]{class="badge positive" title="Aplicável somente a projetos do Adobe Commerce as a Cloud Service e do Adobe Commerce Optimizer (infraestrutura SaaS gerenciada pela Adobe)."}

Executar uma migração de dados em massa

Este guia é uma referência operacional passo a passo para executar uma migração de dados de uma instalação local ou PaaS do Adobe Commerce para o Adobe Commerce as a Cloud Service usando a ferramenta de migração de dados em massa. Os valores reais de configuração e os detalhes específicos do ambiente variam de acordo com a sua configuração.

Antes de começar, confirme se você concluiu cada item da lista de verificação de preparação do cliente e verificou o acesso à API com o guia de acesso ao serviço de migração.

Pré-requisitos

Configurar o pacote de ferramentas

Configurar o ambiente para a migração de dados em massa:

Exemplo de arquivos de configuração

Os arquivos .example.env e .my.cnf.example na raiz do repositório são o ponto de partida para a sua configuração. Copie cada arquivo para seu nome de trabalho e preencha os valores necessários.

Configurar o arquivo de ambiente

O arquivo .env na raiz do projeto é a configuração de migração e extração. Ele orienta o pipeline da CLI, incluindo URLs de origem e de destino, OAuth, a conexão remota do CDMS, autenticação SaaS e IMS e outros switches.

Edite o arquivo .env e defina pelo menos os seguintes valores corretamente. Para obter a lista completa de variáveis com suporte, consulte as anotações em linha em .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>

Configurar credenciais do OAuth de origem

Esses quatro valores assinam solicitações da ferramenta de migração para as APIs do armazenamento de origem. Para obtê-los, abra o Admin de origem e vá para Sistema > Extensões > Integrações. Crie ou abra uma integração e copie os valores em .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>

Definir o token da CLI da nuvem

Alinhar configurações de administração do Commerce

Antes da migração, verifique se as configurações a seguir estão consistentes entre a origem e o destino.

Configurar credenciais SaaS e IMS do público-alvo

Estas são as configurações de IMS e API Adobe Commerce as a Cloud Service para o destino. Você precisa da ID do locatário, da ID da organização, das credenciais de servidor para servidor do IMS OAuth e do host IMS correto para o seu ambiente. Coordene com sua equipe da Adobe a organização, o locatário e o acesso ao perfil. Não tente inferir ou estimar valores sensíveis.

Gerar credenciais IMS

Use o Adobe Developer Console. Você precisa de acesso de Developer ou Admin na organização da Adobe para criar projetos. Um logon básico de usuário não é suficiente para adicionar APIs.

O ponto de extremidade do token IMS (ADOBE_IMS_URL) deve corresponder ao ambiente da credencial.

ADOBE_IMS_META_SCOPES deve corresponder aos escopos provisionados nessa credencial. O arquivo .example.env inclui a cadeia de caracteres de escopo separada por vírgulas completa como uma referência. Altere-o somente se a Adobe instruir o.

Mapear credenciais de Adobe I/O para o arquivo de ambiente

Em Developer Console, os valores de servidor para servidor OAuth são apresentados como uma ID de cliente e um segredo de cliente, correspondendo à seguinte estrutura JSON:

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

Mapeie-os para .env (exemplo de espaços reservados):

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

Os hosts da API SaaS diferem entre pré-produção e produção. TARGET_INSTANCE_REST_URL e TARGET_INSTANCE_GRAPHQL_URL devem usar o mesmo ambiente de API do Commerce que sua migração, seja pré-produção ou produção. Não misture um nível com o CDMS ou locatário do outro nível.

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

Para hosts SaaS de produção, substitua na1-sandbox por na1 em ambas as URLs TARGET_INSTANCE_*. Use o ADOBE_IMS_URL correspondente para essa camada, conforme mostrado na tabela anterior.

Definir o endpoint do CDMS

Aponte a ferramenta de migração para o host da API do CDMS que corresponde ao ambiente para o qual você está migrando. Defina CDMS_HOST (e normalmente CDMS_PORT=443) em .env. Use um host, seja de pré-produção ou de produção, não ambos.

Defina ou remova o comentário do bloco que corresponde à sua execução:

# 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

Definir o código de armazenamento

STORE_CODE é o código de exibição de repositório usado pela ferramenta de migração para chamadas da API REST da instância de origem, criação de cliente de teste sintético e limpeza de dados. Ele também é enviado como o cabeçalho x-store-code durante a fase de carregamento.

O padrão de STORE_CODE é default em .example.env. Verifique se isso corresponde ao código de exibição de armazenamento padrão da instância de origem. Para verificar, na origem Admin, vá para Lojas > Todas as Lojas e verifique a coluna Código para a exibição de loja que deve ser usada. Se o código mostrado lá não for default, atualize STORE_CODE em .env para corresponder.

Configurar o arquivo de conexão de banco de dados

O arquivo .my.cnf fornece configurações de conexão MySQL para o lado da extração da ferramenta de migração. Crie-o copiando .my.cnf.example para .my.cnf na raiz do projeto. O nome da seção deve corresponder a SOURCE_CONNECTION_NAME em .env.

Para uma origem no local ou auto-hospedada:

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

Para uma origem Adobe Commerce on Cloud:

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

O campo id= informa à ferramenta que a origem é PaaS e aciona a configuração de túnel usando MAGENTO_CLOUD_CLI_TOKEN. Os valores project_id e environment estão disponíveis em Cloud Console ou pelos comandos magento-cloud project:list e magento-cloud environment:list.

Preparar a rede e as instâncias

A Autenticação básica de HTTP na frente do armazenamento pode bloquear o tráfego da API e da ferramenta. Verifique se está desabilitado para a URL de origem usada pela migração ou se os caminhos da ferramenta são permitidos, para que as solicitações REST e GraphQL possam acessar o armazenamento.

Manter a estabilidade do banco de dados de origem durante a extração

Embora a ferramenta extraia dados do banco de dados de origem, nenhum outro processo deve gravar neles. Gravações simultâneas podem resultar em um instantâneo inconsistente.

Target

Se o catálogo de destino tiver que ser limpo antes da migração, exclua os produtos em Admin em lotes pequenos, por exemplo, 200 de cada vez, para evitar conflitos de catálogo duplicados e tempos limite de exclusão em massa.

Criar e executar a migração

Trabalhar no diretório extraído do projeto com acesso de gravação.

Manter a sessão ativa por SSH

Se você se conectar via SSH, uma rede eliminada poderá eliminar seu shell e interromper uma migração longa. O comando GNU screen mantém a sessão ativa no servidor:

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"

Você também pode usar tmux se ele estiver disponível no servidor.

Criar a imagem do Docker

Crie a imagem Docker usada por bin/console, que contém PHP, CLI e dependências. Execute-a antes da primeira execução ou depois de Dockerfile ou alterações na imagem base.

./bin/console build

Iniciar os serviços de apoio

Inicie os serviços de apoio Docker Compose da ferramenta, como o banco de dados de teste local e, quando habilitado em .env, os serviços locais opcionais. Os serviços exatos dependem da sua configuração. Execute isso após uma criação bem-sucedida e antes dos comandos shell, migração ou em fases.

./bin/console start

Inicialize o contêiner da CLI

Inicie o contêiner da CLI uma vez para que o ponto de entrada possa concluir a configuração, como uma instalação do Composer, se necessário, em relação ao projeto montado. Execute-o uma vez antes da primeira migração em um novo ambiente.

./bin/console shell
exit

Executar a migração

A ferramenta oferece suporte a duas abordagens de migração. Escolha aquele que se adapta ao seu caso de uso.

Migração monofásica

Nenhum modo de manutenção é necessário na instância de origem. Execute o pipeline de migração completa com um único comando:

./bin/console migration

O comando executa todas as etapas do pipeline automaticamente, de ponta a ponta, na seguinte ordem.

Use essa opção quando nenhuma janela de manutenção for necessária, o que é típico para execuções secas completas, ambientes de desenvolvimento ou sandbox ou qualquer migração em que a origem possa permanecer ativa durante a extração.

Migração multifásica com modo de manutenção

O modo de manutenção é necessário na instância de origem para garantir a consistência dos dados durante a extração. A migração é dividida em fases distintas que devem ser executadas em ordem.

Fase 1 — Antes da manutenção (a origem está ativa)

Executar enquanto a instância de origem está ativa e aceitando tráfego. O acesso REST e GraphQL à origem deve estar totalmente disponível. Não ative o modo de manutenção antes que esta fase seja concluída.

Retorne à raiz do servidor e execute:

./bin/console migration:before-maintenance

Fase 2 — Habilitar modo de manutenção (manual)

Ative o modo de manutenção na origem e pause todas as atividades que gravam ou afetam o banco de dados, incluindo trabalhos agendados, integrações de terceiros, processamento de pedidos e sincronização de ativos de mídia.

No servidor do Commerce de origem (instalar raiz), execute:

bin/magento maintenance:enable

Fase 3 — Durante a manutenção (a origem está congelada)

Execute com a instância de origem no modo de manutenção. A origem deve permanecer congelada por toda a duração desta fase. Não desabilite o modo de manutenção até que a Fase 3 seja concluída com êxito.

./bin/console migration:during-maintenance

Fase 4 — Desabilitar modo de manutenção (manual, condicional)

Essa fase desativa o modo de manutenção, reativando o tráfego para a instância de origem. Esta etapa é necessária antes de executar a fase de limpeza, pois a limpeza se comunica com a origem por meio de REST e falha com HTTP 503 se o modo de manutenção ainda estiver ativo.

No servidor Commerce de origem, execute:

bin/magento maintenance:disable

Fase 5 — Limpeza (opcional, a origem deve estar ativa)

Remova os clientes e pedidos de teste sintético criados na Fase 1 da instância de origem por meio do REST. Esta fase pode ser executada somente após o modo de manutenção ser desabilitado.

Retorne à raiz do servidor e execute:

./bin/console migration:cleanup

Retomar ou executar novamente uma migração

A ferramenta de migração acompanha o progresso usando um arquivo .migration_id na raiz do projeto. Esse arquivo é criado automaticamente quando uma nova migração é iniciada e registra o identificador de migração atual.

Retomar após uma falha

Se uma execução de migração falhar ou for interrompida, execute novamente o mesmo comando para retomar da última etapa bem-sucedida (extração, carregamento ou verificação) em vez de reiniciar do zero. As etapas já concluídas são ignoradas automaticamente.

Iniciar uma nova migração

Para descartar uma execução anterior e iniciar uma migração completamente nova, exclua o arquivo .migration_id antes de iniciar a próxima migração:

rm .migration_id

Se .migration_id existir e a migração anterior já tiver sido concluída, a ferramenta imprimirá uma mensagem informando que a migração já foi concluída e aconselhará você a excluir o arquivo.

Revisar logs e depurar

Todos os logs de migração são gravados no diretório logs/ na raiz do projeto e são organizados em subdiretórios com carimbo de data e hora:

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