Usar operações de longa duração no Cloud Storage

Nesta página, descrevemos como usar operações de longa duração que são iniciadas com o uso de chamadas de método no Cloud Storage. Para informações detalhadas sobre a semântica de uma operação de longa duração retornada de uma chamada de método específica, consulte a documentação específica do recurso.

Acessar os papéis necessários

Para receber as permissões necessárias para gerenciar operações de longa duração no Cloud Storage, peça ao administrador para conceder a você o papel de Administrador do Storage (roles/storage.admin) ou de Proprietário do bucket legado do Storage (roles/storage.legacyBucketOwner) no bucket ou no projeto usado para realizar a operação subjacente.

Esses papéis predefinidos contêm as seguintes permissões, que são necessárias para gerenciar operações de longa duração no Cloud Storage:

• storage.bucketOperations.cancel
• storage.bucketOperations.get
• storage.bucketOperations.list
• storage.buckets.list (essa permissão é necessária apenas ao usar o Google Cloud console)

Observação: O usuário que inicia uma operação de longa duração sempre pode acessar os detalhes dela, independentemente de ter ou não a permissão storage.bucketOperations.get do IAM. Os usuários que não iniciaram a operação de longa duração precisam ter a permissão storage.bucketOperations.get para acessar os detalhes dela. As permissões storage.bucketOperations.list e storage.bucketOperations.cancel são sempre necessárias para listar e cancelar operações de longa duração.

Para informações sobre como conceder papéis nos buckets, consulte Definir e gerenciar políticas do IAM em buckets. Para informações sobre como conceder papéis em projetos, consulte Gerenciar acesso.

Acessar os detalhes de uma operação de longa duração

Console

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

   Acessar buckets

2. Na lista de buckets, clique no nome do bucket associado à operação de longa duração.

3. Clique na guia Operações.

Linha de comando

**Observação** :a CLI do Google Cloud especifica automaticamente um projeto padrão, que pode ser controlado usando a flag --project.

Para ver detalhes ou verificar o status de uma operação de longa duração, use o gcloud storage operations describe comando:

gcloud storage operations describe projects/_/buckets/BUCKET_NAME/operations/OPERATION_ID

Substitua:

• BUCKET_NAME com o nome do bucket que contém a operação de longa duração. Por exemplo, my-bucket.

• OPERATION_ID pelo ID da operação de longa duração que é retornada na resposta dos métodos que você chama. Por exemplo, a resposta a seguir é retornada ao chamar gcloud storage restore e o ID da operação de longa duração é BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP:

  Created: projects/_/buckets/my-bucket/operations/BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP

APIs REST

API JSON

1. Tenha a CLI gcloud instalada e inicializada, o que permite gerar um token de acesso para o cabeçalho Authorization.

2. Use cURL para chamar a API JSON com uma operations.get solicitação:

   curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/operations/OPERATION_ID"

   Substitua:

   • BUCKET_NAME com o nome do bucket associado à operação de longa duração.

   • OPERATION_ID pelo ID da operação de longa duração que é retornada na resposta dos métodos que você chama. Por exemplo, a resposta a seguir é retornada ao chamar gcloud storage restore e o ID da operação de longa duração é BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP:

     Created: projects/_/buckets/my-bucket/operations/BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP

Se a solicitação for bem-sucedida, um operations recurso será retornado:

{
  "kind": "storage#operation",
  "name": "projects/_/buckets/bucket/operations/operation_id",
  "metadata": {
    "@type": OperationMetadataType*,
    metadata OperationMetadata*
  },
  "done": boolean,
  "response": {
    "@type": ResponseResourceType*,
    response ResponseResource*
  }
}

Listar as operações de longa duração em um bucket

Console

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

   Acessar buckets

2. Na lista de buckets, clique no nome do bucket.

3. Clique na guia Operações.

Linha de comando

Para listar as operações de longa duração em um bucket, use o gcloud storage operations list comando:

gcloud storage operations list gs://BUCKET_NAME

Substitua:

• BUCKET_NAME com o nome do bucket que contém as operações de longa duração. Por exemplo, my-bucket.

APIs REST

API JSON

1. Tenha a CLI gcloud instalada e inicializada, o que permite gerar um token de acesso para o cabeçalho Authorization.

2. Use cURL para chamar a API JSON com uma operations.get solicitação:

   curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/operations"

   Substitua:

   • BUCKET_NAME com o nome do bucket associado às operações de longa duração que você quer listar.

Se a solicitação for bem-sucedida, você receberá uma resposta semelhante a esta:

{
  "kind": "storage#operations",
  "nextPageToken": string,
  "operations": [
    operations Resource
  ]
}

Cancelar uma operação de longa duração

Observação: o cancelamento de uma operação de longa duração é assíncrono e é feito com o melhor esforço. Uma solicitação de cancelamento em uma operação de longa duração define o campo requested cancellation, mas não há garantia de que a solicitação será respeitado.

Console

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

   Acessar buckets

2. Na lista de buckets, clique no nome do bucket associado à operação de longa duração que você quer cancelar.

3. Clique na guia Operações.

4. Na linha da operação de longa duração, clique em Mais opções e em clique em Cancelar.

Linha de comando

**Observação** :a CLI do Google Cloud especifica automaticamente um projeto padrão, que pode ser controlado usando a flag --project.

Para cancelar uma operação de longa duração, use o gcloud storage operations cancel comando:

gcloud storage operations cancel projects/_/buckets/BUCKET_NAME/operations/OPERATION_ID

Substitua:

• BUCKET_NAME com o nome do bucket que contém a operação de longa duração. Por exemplo, my-bucket.

• OPERATION_ID pelo ID da operação de longa duração que é retornada na resposta dos métodos que você chama. Por exemplo, a resposta a seguir é retornada ao chamar gcloud storage restore e o ID da operação de longa duração é BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP:

  Created: projects/_/buckets/my-bucket/operations/BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP

APIs REST

API JSON

1. Tenha a CLI gcloud instalada e inicializada, o que permite gerar um token de acesso para o cabeçalho Authorization.

2. Use cURL para chamar a API JSON com uma operations.post solicitação:

   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/operations/OPERATION_ID/cancel"

   Substitua:

   • BUCKET_NAME com o nome do bucket associado à operação de longa duração que você quer cancelar.

   • OPERATION_ID pelo ID da operação de longa duração que é retornada na resposta dos métodos que você chama. Por exemplo, a resposta a seguir é retornada ao chamar gcloud storage restore e o ID da operação de longa duração é BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP:

     Created: projects/_/buckets/my-bucket/operations/BcazhBlHv2uZwnlh1UdamOfKbpVpb67drEwVoI2hlkE1e0eaXqw7fPBWP0802TJry4pInGC4h3wxtOi31RmpCC_lvnSocj_-jP

Metadados

As operações de longa duração têm metadados associados a elas. Os metadados a seguir identificam propriedades de uma operação de longa duração:

• Hora de criação: a hora em que a operação de longa duração foi criada.

• Hora de término: a hora em que a operação de longa duração terminou de ser executada.

• Hora de atualização: a hora em que a operação de longa duração foi modificada pela última vez.

• Tipo: a chamada de API que iniciou a operação de longa duração.

• Cancelamento solicitado: indica se o usuário solicitou o cancelamento da operação de longa duração.

• Porcentagem de progresso: o progresso estimado da operação de longa duração, em porcentagem. Um valor de -1 significa que o progresso é desconhecido.

No Google Cloud console do, a porcentagem de progresso e os metadados de cancelamento solicitado são exibidos em um campo Status combinado.

Tratamento de erros

Operações de longa duração são iniciadas em APIs assíncronas e exigem práticas de tratamento de erros diferentes das APIs síncronas. Ao contrário das APIs síncronas, a resposta a chamadas de API assíncronas pode indicar sucesso mesmo se as operações de longa duração acabarem falhando. Em vez de depender do código do status retornado nos cabeçalhos de resposta, analise os metadados de operações de longa duração no corpo da resposta para determinar se uma chamada de API foi bem-sucedida.

Por exemplo, se você fizer uma solicitação de restauração em massa de exclusão reversível, ela vai retornar um código de status HTTP bem-sucedido (200 OK), mesmo que um erro ocorra durante a operação. Para verificar se a operação de restauração em massa foi bem-sucedida, consulte o status da operação de longa duração.

Observe que as APIs de operação de longa duração (Get, List, Cancel) são síncronas e retornam erros normais.