Copiar trabalhos no Azure Cosmos DB (versão prévia)

Aplica-se a: ✅ NoSQL

Você pode executar cópias de dados no Azure Cosmos DB usando trabalhos de cópia de contêiner.

Talvez seja necessário copiar dados da sua conta do Azure Cosmos DB se você quiser atingir qualquer um desses cenários:

Copiar todos os itens de um contêiner para outro.
Altere a granularidade na qual a taxa de transferência é provisionada: do banco de dados até o contêiner e vice-versa.
Alterar a chave de partição de um contêiner.
Atualize as chaves exclusivas de um contêiner.
Renomear um contêiner ou banco de dados.
Altere o modo de capacidade de uma conta de sem servidor para provisionada ou vice-versa.
Adote novos recursos com suporte apenas para novos contêineres, por exemplo, chaves de partição hierárquicas.

Os trabalhos de cópia podem ser criados e gerenciados usando comandos da CLI do Azure.

Pré-requisitos

Habilite o backup contínuo na conta de origem do Azure Cosmos DB.
Habilite a versão prévia do recurso Todas as versões e excluir o feed de alterações (versão prévia) na assinatura da conta de origem.

Habilitar cópia online

Para habilitar a cópia online em sua conta de origem, execute as etapas a seguir usando a CLI do Azure.

# Set shell variables.
 $resourceGroupName = <azure_resource_group>
 $accountName = <azure_cosmos_db_account_name>
 $EnableOnlineContainerCopy = "EnableOnlineContainerCopy"

# List down existing capabilities of your account.
 $cosmosdb = az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $accountName

$capabilities = (($cosmosdb | ConvertFrom-Json).capabilities)

# Append EnableOnlineContainerCopy capability in the list of capabilities.
 $capabilitiesToAdd = @()
 foreach ($item in $capabilities) {
    $capabilitiesToAdd += $item.name
 }
 $capabilitiesToAdd += $EnableOnlineContainerCopy

 # Update Cosmos DB account
 az cosmosdb update --capabilities $capabilitiesToAdd \
    -n $accountName -g $resourceGroupName

Importante

Todas as operações de gravação na conta de origem são cobradas com RUs duplas para preservar as versões anteriores e atuais das alterações nos itens no contêiner. Esse aumento na taxa de RU está sujeito a alterações no futuro.

Copie os dados de um contêiner

Crie o contêiner de destino do Azure Cosmos DB usando as configurações que você deseja usar (chave de partição, granularidade de taxa de transferência, unidades de solicitação, chave exclusiva e assim por diante).
Criar o trabalho de cópia de contêiner.
Monitore o progresso do trabalho de cópia.
Depois que todos os documentos forem copiados, interrompa as atualizações no contêiner de origem e chame a API de conclusão para marcar o trabalho como concluído.
Retome as operações apontando adequadamente o aplicativo ou cliente para o contêiner de origem ou de destino, conforme pretendido.

Como funciona a cópia do contêiner?

A plataforma aloca instâncias de computação do lado do servidor para a conta de destino do Azure Cosmos DB para executar os trabalhos de cópia do contêiner.
Um único trabalho é executado em todas as instâncias simultaneamente.
Os trabalhos de cópia online utilizam todas as versões e o modo de feed de alterações de exclusão para copiar os dados e replicar alterações incrementais do contêiner de origem para o contêiner de destino.
Após a conclusão do trabalho, a plataforma desaloca essas instâncias após 15 minutos de inatividade.

Você pode executar trabalhos de cópia de coleta offline para copiar dados dentro da mesma conta do Azure Cosmos DB para Mongo DB.

Copiar dados de uma coleção

Crie a coleção de destino do Azure Cosmos DB usando as configurações que deseja usar (chave de partição, granularidade de taxa de transferência, unidades de solicitação, chave exclusiva e assim por diante).
Interrompa as operações na coleção de origem pausando as instâncias do aplicativo ou quaisquer clientes que se conectem a ele.
Crie o trabalho de cópia.
Monitore o progresso do trabalho de cópia e aguarde até que ele seja concluído.
Retome as operações apontando adequadamente o aplicativo ou cliente para a coleção de origem ou destino, conforme pretendido.

Observação

Recomendamos fortemente que você pare de executar qualquer operação na coleção de origem antes de iniciar o trabalho de cópia da coleção offline. Exclusões e atualizações de itens feitas na coleção de origem depois que você inicia o trabalho de cópia podem não ser capturadas. Se você continuar a executar operações na coleção de origem enquanto o trabalho de cópia estiver em andamento, poderá ter dados duplicados ou ausentes na coleção de destino.

Como funciona a cópia de coleção?

A plataforma aloca instâncias de computação do lado do servidor para a conta do Azure Cosmos DB de destino.
Essas instâncias são alocadas quando um ou mais trabalhos de cópia de coleção são criados na conta.
Os trabalhos de cópia são executados nessas instâncias.
Um único trabalho é executado em todas as instâncias simultaneamente.
As instâncias são compartilhadas por todos os trabalhos de cópia em execução na mesma conta.
Os trabalhos de cópia offline utilizam fluxos de alterações para copiar os dados e replicar alterações incrementais da coleção de origem para a coleção de destino.
A plataforma pode desalocar as instâncias caso elas fiquem inativas por mais do que 15 minutos.

Você pode executar a cópia de tabela offline para copiar dados de uma tabela para outra tabela dentro da mesma conta do Azure Cosmos DB for Apache Cassandra.

Copiar dados de uma tabela

Crie a tabela de destino do Azure Cosmos DB usando as configurações que você deseja usar (chave de partição, granularidade de taxa de transferência, unidades de solicitação e assim por diante).
Interrompa as operações na tabela de origem pausando as instâncias do aplicativo ou quaisquer clientes que se conectem a ela.
Crie o trabalho de cópia.
Monitore o progresso do trabalho de cópia e aguarde até que ele seja concluído.
Retome as operações apontando adequadamente o aplicativo ou cliente para a tabela de origem ou de destino, conforme pretendido.

Observação

É altamente recomendável que você pare de executar qualquer operação na tabela de origem antes de iniciar o trabalho de cópia da tabela offline. Exclusões e atualizações de itens feitas na tabela de origem depois que você inicia o trabalho de cópia podem não ser capturadas. Se você continuar a executar operações na tabela de origem enquanto o trabalho de cópia estiver em andamento, poderá ter dados duplicados ou ausentes na tabela de destino.

Como funciona a cópia de tabela?

A plataforma aloca instâncias de computação do lado do servidor para a conta do Azure Cosmos DB de destino.
Essas instâncias são alocadas quando um ou mais trabalhos de cópia são criados na conta.
Os trabalhos de cópia são executados nessas instâncias.
Um único trabalho é executado em todas as instâncias simultaneamente.
As instâncias são compartilhadas por todos os trabalhos de cópia em execução na mesma conta.
Os trabalhos de cópia offline utilizam Alterar feed para copiar os dados e replicar alterações incrementais da tabela de origem para a tabela de destino.
A plataforma pode desalocar as instâncias caso elas fiquem inativas por mais do que 15 minutos.

Fatores que afetam a taxa de um trabalho de cópia

A taxa de progresso do trabalho de cópia de contêiner é determinada por estes fatores:

A configuração da taxa de transferência de contêiner ou banco de dados de origem.
A configuração da taxa de transferência de contêiner ou banco de dados de destino.

Dica

Defina a taxa de transferência do contêiner de destino como pelo menos duas vezes a taxa de transferência do contêiner de origem.
Instâncias de computação do lado do servidor que são alocadas para a conta do Azure Cosmos DB para realizar a transferência de dados.

Importante

O SKU padrão oferece duas instâncias do lado do servidor de 4 vCPU e 16 GB por conta.

Limitações

Critérios de elegibilidade para pré-visualização

Os trabalhos de cópia de contêiner não funcionam com contas que têm os seguintes recursos habilitados. Desabilite esses recursos antes de executar trabalhos de cópia de contêiner:

Partição de mesclagem

Configurações de conta

A configuração de TTL (vida útil) não é ajustada no contêiner de destino. Como resultado, se um documento não tiver expirado no contêiner de origem, ele iniciará sua contagem regressiva novamente no contêiner de destino.

Perguntas frequentes

Há um contrato de nível de serviço para trabalhos de cópia de contêiner?

Atualmente, há suporte para trabalhos de cópia de contêiner com base no melhor esforço. Não fornecemos nenhuma garantia de SLA (contrato de nível de serviço) para o tempo necessário para que os trabalhos terminem.

Posso criar várias tarefas de cópia de contêiner dentro de uma conta?

Sim, é possível criar vários trabalhos na mesma conta. Os trabalhos são executados consecutivamente. Você pode listar todos os trabalhos criados em uma conta e monitorar o progresso deles.

Posso copiar um banco de dados inteiro dentro da conta do Azure Cosmos DB?

Você precisa criar um trabalho para cada contêiner no banco de dados.

Tenho uma conta do Cosmos DB com várias regiões. Em qual região o trabalho de cópia de contêiner será executado?

O trabalho de cópia do contêiner é executado na região de gravação. Em uma conta configurada com gravações de várias regiões, o trabalho é executado em uma das regiões na lista de regiões de gravação.

O que acontece com os trabalhos de cópia de contêiner quando a região de gravação da conta é alterada?

A região de gravação da conta pode ser alterada no cenário raro de uma interrupção de região ou devido ao failover manual. Nesse cenário, os trabalhos de cópia de contêiner incompletos criados na conta falham. Você precisaria recriar esses trabalhos que falharam. Os trabalhos recriados são executados na nova região de gravação (atual).

Regiões com suporte

Atualmente, a cópia de contêiner é compatível com as seguintes regiões:

Américas	Europa e África	Pacífico Asiático
Sul do Brasil	França Central	Austrália Central
Canadá Central	Sul da França	Austrália Central 2
Leste do Canadá	Norte da Alemanha	Leste da Austrália
EUA Central	Centro-oeste da Alemanha	Índia Central
EUA Central EUAP	Europa Setentrional	Leste do Japão
Leste dos EUA	Leste da Noruega	Coreia Central
Leste dos EUA 2	Oeste da Noruega	Sudeste Asiático
Leste dos EUA 2 EUAP	Norte da Suíça	EAU Central
Centro-Norte dos EUA	Oeste da Suíça	Índia Ocidental
Centro-Sul dos EUA	Sul do Reino Unido	Ásia Oriental
Centro-oeste dos EUA	Oeste do Reino Unido	Sul da Malásia
Oeste dos EUA	Oeste da Europa	Oeste do Japão
Oeste dos EUA 2	Israel Central	Sudeste da Austrália
Sem suporte	Norte da África do Sul	Sem suporte

Problemas conhecidos e comuns

Ao usar o recurso de cópia de contêiner online, se o id campo for modificado no contêiner de origem, o contêiner de destino armazenará dois documentos separados, cada um correspondente aos valores distintos id .
Ao alterar as chaves de partição durante a cópia de dados para o contêiner de destino, verifique se a nova chave de partição e id as combinações são exclusivas no contêiner.

Por exemplo, considere o seguinte cenário:

Chave de partição original:/department
Documentos de origem:
```
{
    "id": "101",
    "employeeName": "John Doe",
    "department": "HR"
},
{
    "id": "101",
    "employeeName": "John Doe",
    "department": "Finance"
}
```
Nova chave de partição:/employeeName
Documentos resultantes no contêiner de destino:
```
{
    "id": "101",
    "employeeName": "John Doe",
    "department": "HR"
},
{
    "id": "101",
    "employeeName": "John Doe",
    "department": "Finance"
}
```
Nesse caso, os dois documentos agora compartilham a mesma chave de partição (/employeeName) e combinação id ("employeeName": "John Doe", "id": "101"), o que causa um conflito. Esse conflito resulta em um erro de inserção. Para evitar esses problemas, garanta que a nova chave de partição e as combinações de id sejam únicas em todos os documentos do contêiner de destino.
Erro – A chave de partição atingiu o tamanho máximo de 20 GB

Ao modificar chaves de partição durante a cópia de dados para o contêiner de destino, verifique se a nova chave de partição permanece dentro do limite de tamanho da chave de partição lógica de 20 GB. Se esse limite for excedido, o trabalho falhará com o seguinte erro:
```
"code": "403",
"message": "Response status code does not indicate success: Forbidden (403); Substatus: 1014; ActivityId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx; Reason: (Message: {"Errors":["Partition key reached maximum size of 20 GB. Learn more: https://aka.ms/CosmosDB/sql/errors/full-pk"]"
```
Erro – o recurso proprietário não existe

Se a criação do trabalho falhar e exibir o erro "Recurso de proprietário não existe" (código de erro 404), o contêiner de destino ainda não foi criado ou o nome do contêiner usado para criar o trabalho não corresponderá a um nome de contêiner real.

Certifique-se de que o contêiner de destino seja criado antes de executar o trabalho e de que o nome do contêiner no trabalho corresponda a um nome de contêiner real.
```
"code": "404",
"message": "Response status code does not indicate success: NotFound (404); Substatus: 1003; ActivityId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx; Reason: (Message: {\"Errors\":[\"Owner resource does not exist\"]
```
Erro – Erro ao obter recursos para o trabalho

Esse erro pode ocorrer devido a problemas internos do servidor. Para resolver esse problema, entre em contato com o suporte da Microsoft abrindo uma Nova Solicitação de Suporte no portal do Azure. Para Tipo de problema, selecione Migração de Dados. Para Subtipo de problema, selecione Cópia de contêiner dentro da conta.
```
"code": "500"
"message": "Error while getting resources for job, StatusCode: 500, SubStatusCode: 0, OperationId:  xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, ActivityId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
```

Próxima etapa

Criar e gerenciar trabalhos de cópia de contêiner no Azure Cosmos DB

Comentários

Esta página foi útil?

Last updated on 2025-09-01