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 que é 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 o papel de proprietário do bucket legado do Storage (roles/storage.legacyBucketOwner) no bucket ou no projeto usado para realizar a operação.

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

Para informações sobre como conceder papéis nos buckets, consulte Usar o IAM com 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

Linha de comando

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

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. Ter 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 solicitação operations.get:

    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 recurso operations 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

Linha de comando

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

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. Ter 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 solicitação operations.get:

    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

Linha de comando

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

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. Ter 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 solicitação operations.post:

    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 as propriedades de uma operação de longa duração:

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

  • Hora de término: o horário em que a operação de longa duração foi concluída.

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

  • Type: o tipo de operação de longa duração invocado.

  • 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.

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.