Usar a replicação entre buckets

Nesta página, descrevemos como usar a replicação entre buckets, que usa o Serviço de transferência do Cloud Storage para copiar objetos novos e atualizados de forma assíncrona de um bucket de origem para um de destino. Ao usar a replicação entre buckets, você cria e gerencia jobs de replicação, que são um tipo de job no Serviço de transferência do Cloud Storage.

Antes de começar

Antes de começar, conclua as etapas a seguir.

Ativar a API Storage Transfer Service

Ative a API Storage Transfer Service, se ainda não tiver feito isso.

Acessar os papéis necessários

Para receber as permissões necessárias para usar a replicação entre buckets, peça ao administrador para conceder a você o papel do IAM de Usuário de transferência do Storage (roles/storagetransfer.user) no bucket ou no projeto.

Esse papel predefinido contém as permissões necessárias para usar a replicação entre buckets. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para usar a replicação entre buckets:

storagetransfer.jobs.create
storagetransfer.jobs.delete
storagetransfer.jobs.get
storagetransfer.jobs.list
storagetransfer.jobs.run
storagetransfer.jobs.update

Para instruções sobre como conceder papéis nos buckets, consulte Usar o IAM com buckets. Para instruções sobre como conceder papéis a projetos, consulte Gerenciar o acesso aos projetos.

Conceder os papéis necessários

A replicação entre buckets usa o Pub/Sub para receber notificações de mudanças no bucket de origem e o Serviço de transferência do Cloud Storage para replicar objetos do bucket de origem para o de destino. Para usar a replicação entre buckets, também é necessário conceder as permissões necessárias ao agente de serviço usado pelo Serviço de transferência do Cloud Storage para replicar dados e ao agente de serviço usado pelo Pub/Sub para gravar notificações.

Conceder os papéis necessários ao agente de serviço do Serviço de transferência do Cloud Storage

O Serviço de transferência do Cloud Storage usa um agente de serviço gerenciado pelo Google para replicar dados. O endereço de e-mail desse agente de serviço segue o formato de nomenclatura project-PROJECT_NUMBER@storage-transfer-service.iam.gserviceaccount.com. É possível acessar o endereço de e-mail do agente de serviço do Serviço de transferência do Cloud Storage usando a API googleServiceAccounts.get do Serviço de transferência do Cloud Storage.

O agente de serviço do Serviço de transferência do Cloud Storage precisa das seguintes permissões para replicar seus objetos e configurar notificações do Pub/Sub para o bucket de origem:

Permissões necessárias

storage.buckets.get nos buckets de origem e de destino
storage.buckets.update no bucket de origem
storage.objects.list no bucket de origem
storage.objects.get no bucket de origem
storage.objects.rewrite no bucket de destino
pubsub.topics.create no projeto

Essas permissões podem ser concedidas pelo papel de editor do Pub/Sub (roles/pubsub.editor) e pelo papel de administrador do Storage (roles/storage.admin). Para uma função menos permissiva do que a de administrador do Storage, você também pode usar uma função personalizada.

Conceder os papéis necessários ao agente de serviço do Cloud Storage

O Cloud Storage usa um agente de serviço gerenciado pelo Google para gerenciar notificações do Pub/Sub. O endereço de e-mail desse agente de serviço segue o formato de nomenclatura service-PROJECT_NUMBER@gs-project-accounts.iam.gserviceaccount.com.

O agente de serviço do Cloud Storage precisa das seguintes permissões para configurar o Pub/Sub e publicar mensagens em um tópico:

Permissões necessárias

pubsub.topics.publish no tópico do Pub/Sub
pubsub.subscriptions.consume no tópico do Pub/Sub
pubsub.subscriptions.create no projeto

Essa permissão pode ser concedida pelo papel de editor do Pub/Sub (roles/pubsub.publisher).

Criar um job de replicação

Console

Ao usar o console do Google Cloud, é possível criar um job de replicação para buckets existentes ou novos durante o processo de criação de bucket.

Para criar um job de replicação para um novo bucket, siga as instruções para criar um novo bucket.

Para criar um job de replicação para um bucket, siga estas etapas:

No Console do Google Cloud, acesse a página Buckets do Cloud Storage.

Acessar buckets
Na lista de buckets, clique no nome do bucket de origem cujos objetos você quer replicar.
Na página Detalhes do bucket, clique na guia Configuração.
Localize a opção Replicação entre buckets e clique em Editar.
No painel Editar replicação entre buckets que é aberto, clique em Adicionar um destino.
Na seção Escolher um destino, selecione um bucket de destino e clique em Próxima.
Na seção Escolher as configurações de replicação, faça o seguinte:
- Opcional: para filtrar objetos a serem replicados por prefixo de nome de objeto, marque a caixa de seleção Replicar objetos com base no prefixo na seção Escolher quais objetos serão replicados.
  - Para incluir objetos por prefixo, insira um prefixo na seção Incluir objetos com prefixo e clique em Adicionar um prefixo.
  - Para excluir objetos por prefixo, insira um prefixo na seção Excluir objetos com prefixo e clique em Adicionar um prefixo.
- Opcional: para definir uma classe de armazenamento para objetos replicados, selecione uma classe de armazenamento no menu da seção Definir classe de armazenamento para objetos replicados.
  
  Se você pular esta etapa, os objetos replicados vão usar a classe de armazenamento do bucket de destino por padrão.
1. Clique em Salvar.

Linha de comando

Ao usar a CLI do Google Cloud, é possível criar um job de replicação para buckets existentes.

Para criar um job de replicação, use o comando gcloud alpha transfer jobs create com a flag --replication:

gcloud alpha transfer jobs create gs://SOURCE_BUCKET_NAME gs://DESTINATION_BUCKET_NAME --replication

Substitua:

SOURCE_BUCKET_NAME pelo nome do bucket de origem que você quer replicar. Por exemplo, my-source-bucket.
DESTINATION_BUCKET_NAME pelo nome do bucket de destino. Por exemplo, my-destination-bucket.

APIs REST

API JSON

Ao usar a API JSON, é possível criar um job de replicação para buckets existentes.

Ter a gcloud CLI instalada e inicializada para gerar um token de acesso para o cabeçalho Authorization.

Como alternativa, é possível criar um token de acesso usando o OAuth 2.0 Playground e incluí-lo no cabeçalho Authorization.
Crie um arquivo JSON que contenha um objeto TransferJob com um recurso ReplicationSpec inicializado:
```
TransferJob {
 "name": "TRANSFER_JOB_NAME",
 ...
 ReplicationSpec: {
   "gcsDataSource": {
     "bucketName": "SOURCE_BUCKET_NAME"
   },
   "gcsDataSink" {
     "bucketName": "DESTINATION_BUCKET_NAME"
   },
   "objectConditions": {
   },
   "transferOptions": {
     "overwriteWhen": "OVERWRITE_OPTION"
   }
 }
 ...
}
```
Substitua:
- TRANSFER_JOB_NAME pelo nome que você quer atribuir ao job de replicação. Consulte a documentação de referência de transferJobs para saber mais sobre os requisitos de nomenclatura.
- SOURCE_BUCKET_NAME com o nome do bucket de origem que contém os objetos que você quer replicar. Por exemplo, example-source-bucket.
- DESTINATION_BUCKET_NAME com o nome do bucket de destino em que os objetos serão replicados. Por exemplo, example-destination-bucket.
- OVERWRITE_OPTION com uma opção de como os objetos existentes no bucket de destino podem ser substituídos como resultado de um job de replicação, o que pode acontecer quando o objeto de destino e o de origem têm o mesmo nome. O valor precisa ser um dos indicados abaixo:
  - ALWAYS: sempre substituir objetos no bucket de destino
  - DIFFERENT: só substituir objetos no bucket de destino se os dados do objeto de destino forem diferentes dos dados do objeto de origem
  - NEVER: nunca substituir objetos no bucket de destino

Use o cURL para chamar a API REST do Serviço de transferência do Cloud Storage com uma solicitação transferJobs.create:

curl -X POST --data-binary @JSON_FILE_NAME \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://storagetransfer.googleapis.com/v1/transferJobs"

Em que:

JSON_FILE_NAME é o nome do arquivo JSON criado na Etapa 2.

Para verificar o status do job de replicação, consulte os registros do Cloud Logging para o Serviço de transferência do Cloud Storage.

Listar jobs de replicação

Console

Não é possível listar jobs de replicação usando o console do Google Cloud. Consulte Conferir o job de replicação para instruções sobre como conferir um único job de replicação por vez.

Linha de comando

Use o comando gcloud alpha transfer jobs list com a flag --job-type:

gcloud alpha transfer jobs list --job-type=replication

APIs REST

API JSON

Ter a gcloud CLI instalada e inicializada para gerar um token de acesso para o cabeçalho Authorization.

Como alternativa, é possível criar um token de acesso usando o OAuth 2.0 Playground e incluí-lo no cabeçalho Authorization.

Use o cURL para chamar a API REST do Serviço de transferência do Cloud Storage com uma solicitação transferJobs.list:

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://storagetransfer.googleapis.com/v1/transferJobs"

Visualizar um job de replicação

Console

No Console do Google Cloud, acesse a página Buckets do Cloud Storage.

Acessar buckets
Na lista de buckets, clique no nome do bucket de origem cujo job de replicação entre buckets você quer conferir.
Na página Detalhes do bucket, clique na guia Configuração.
Localize a opção Replicação entre buckets e clique em Editar.

O painel Editar replicação entre buckets aparece, mostrando o job de replicação para cada bucket de destino.

Na página Buckets, você pode conferir a coluna Replicação, que mostra se um bucket tem um job de replicação Turbo ou um job de replicação entre buckets em execução. Para instruções sobre como exibir a coluna Replicação, consulte Mostrar colunas.

Linha de comando

Use o comando gcloud alpha transfer jobs describe:

gcloud alpha transfer jobs describe JOB_NAME

Substitua:

JOB_NAME com o ID exclusivo do job de replicação. Por exemplo, 1234567890. Para encontrar o ID do job de transferência, listar seus jobs de replicação.

APIs REST

API JSON

Ter a gcloud CLI instalada e inicializada para gerar um token de acesso para o cabeçalho Authorization.

Como alternativa, é possível criar um token de acesso usando o OAuth 2.0 Playground e incluí-lo no cabeçalho Authorization.
Use cURL para chamar a API REST do Serviço de transferência do Cloud Storage com uma solicitação transferJobs.get:
```
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://storagetransfer.googleapis.com/v1/transferJobs/JOB_NAME"
```
Substitua:
- JOB_NAME com o ID exclusivo do job de replicação. Por exemplo, 1234567890. Para encontrar o ID do job de replicação, listar seus jobs de replicação.

Atualizar um job de replicação

É possível atualizar os seguintes campos de um job de replicação:

A descrição do job de replicação
A configuração para executar um job de replicação
A configuração de notificações publicadas no Pub/Sub
O comportamento de geração de registros para operações de jobs de replicação
O status do job de replicação (ativado, desativado ou excluído)

Console

Ao usar o console do Google Cloud, só é possível pausar ou retomar um job de replicação para atualizar.

No Console do Google Cloud, acesse a página Buckets do Cloud Storage.

Acessar buckets
Na lista de buckets, clique no nome do bucket de origem que você quer pausar ou retomar a replicação.
Na página Detalhes do bucket, clique na guia Configuração.
Localize a opção Replicação entre buckets e clique em Editar.
No painel Editar replicação entre buckets que aparece, clique em Pausar ou Retomar ao lado do job de replicação que você quer atualizar.

Linha de comando

Use o comando gcloud alpha transfer jobs update com as flags que controlam as propriedades do job de replicação que você quer atualizar. Para uma lista de flags possíveis, consulte a documentação gcloud alpha transfer jobs update.

Por exemplo, para atualizar o comportamento de substituição de objeto do job de replicação, execute o comando gcloud alpha transfer jobs update com a flag --overwrite-when:

gcloud alpha transfer jobs update JOB_NAME --overwrite-when=OVERWRITE_OPTION

Substitua:

JOB_NAME com o ID exclusivo do job de replicação. Por exemplo, 1234567890. Para encontrar o ID do job de transferência, listar ou visualizar o job de transferência.
OVERWRITE_OPTION com uma opção para definir como os objetos existentes no bucket de destino podem ser substituídos como resultado de um job de replicação, o que pode acontecer quando o objeto de destino e o de origem têm o mesmo nome. O valor precisa ser um dos indicados abaixo:
- always: sempre substitui os objetos de destino.
- different: só substitua objetos no bucket de destino se os dados do objeto de destino forem diferentes dos dados do objeto de origem.
- never: nunca substitua objetos de destino.

APIs REST

API JSON

Ter a gcloud CLI instalada e inicializada para gerar um token de acesso para o cabeçalho Authorization.

Como alternativa, é possível criar um token de acesso usando o OAuth 2.0 Playground e incluí-lo no cabeçalho Authorization.
Crie um arquivo JSON que contenha a estrutura a seguir, que inclui os campos do objeto TransferJob que você quer atualizar:
```
{
 "projectId": string,
 "transferJob": {
   object (TransferJob)
 },
   "updateTransferJobFieldMask": UPDATE_MASK
}
```
Em que:
- object (TransferJob) é substituído pelos campos do job de replicação que você quer atualizar. Consulte a representação de recursos TransferJob para mais informações.
- UPDATE_MASK é uma lista separada por vírgulas dos nomes dos campos que você quer atualizar. Os valores podem ser um ou mais dos seguintes: description, transferSpec, notificationConfig, loggingConfig, status.
Para mais informações sobre os nomes de campos que podem ser incluídos, consulte o corpo da solicitação transferJobs.patch.
Use o cURL para chamar a API REST do Serviço de transferência do Cloud Storage com uma solicitação transferJobs.patch:
```
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://storagetransfer.googleapis.com/v1/transferJobs/JOB_NAME"
```
Substitua:
- JOB_NAME com o ID exclusivo do job de replicação. Por exemplo, 1234567890. Para encontrar o ID do job de replicação, listar seus jobs de replicação.

Excluir um job de replicação

Console

No Console do Google Cloud, acesse a página Buckets do Cloud Storage.

Acessar buckets
Na lista de buckets, clique no nome do bucket de origem que você quer parar de replicar.
Na página Detalhes do bucket, clique na guia Configuração.
Localize a opção Replicação entre buckets e clique em Editar.
No painel Editar replicação entre buckets que aparece, clique em Excluir ao lado do job de replicação que você quer excluir.
Na caixa de diálogo que aparece, clique em Confirmar.

Linha de comando

Use o comando gcloud alpha transfer jobs delete:

gcloud alpha transfer jobs delete JOB_NAME

Substitua:

JOB_NAME com o ID exclusivo do job de replicação. Por exemplo, 1234567890. Para encontrar o ID do job de replicação, listar seus jobs de replicação.

APIs REST

API JSON

Ter a gcloud CLI instalada e inicializada para gerar um token de acesso para o cabeçalho Authorization.

Como alternativa, é possível criar um token de acesso usando o OAuth 2.0 Playground e incluí-lo no cabeçalho Authorization.
Use o cURL para chamar a API REST do Serviço de transferência do Cloud Storage com uma solicitação transferJobs.delete:
```
curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://storagetransfer.googleapis.com/v1/transferJobs/JOB_NAME"
```
Substitua:
- JOB_NAME com o ID exclusivo do job de replicação. Por exemplo, 1234567890. Para encontrar o ID do job de replicação, listar seus jobs de replicação.