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

Esta página descreve como usar operações de longa duração que são iniciadas através de chamadas de métodos no Cloud Storage. Para ver informações detalhadas sobre a semântica de uma operação de longa duração devolvida por uma chamada de método específica, consulte a documentação específica da funcionalidade.

Obtenha as funções necessárias

Para receber as autorizações necessárias para gerir operações de longa duração no Cloud Storage, peça ao seu administrador para lhe conceder a função de administrador do armazenamento (roles/storage.admin) ou a função de proprietário do contentor antigo do armazenamento (roles/storage.legacyBucketOwner) no contentor ou no projeto usado para realizar a operação subjacente.

Estas funções predefinidas contêm as seguintes autorizações, que são necessárias para gerir operações de longa duração no Cloud Storage:

  • storage.bucketOperations.cancel
  • storage.bucketOperations.get
  • storage.bucketOperations.list

Para ver informações sobre a concessão de funções em contentores, consulte o artigo Use o IAM com contentores. Para obter informações sobre a atribuição de funções em projetos, consulte o artigo Faça a gestão do acesso.

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

Linha de comandos

Para obter os detalhes ou verificar o estado 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

Substituição:

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

  • OPERATION_ID com o ID da operação de longa duração, que é devolvido na resposta dos métodos que chama. Por exemplo, a seguinte resposta é devolvida 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 lhe permite gerar um token de acesso para o cabeçalho Authorization.

  2. Use cURL para chamar a API JSON com um pedido operations.get:

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

    Substituição:

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

    • OPERATION_ID com o ID da operação de longa duração, que é devolvido na resposta dos métodos que chama. Por exemplo, a seguinte resposta é devolvida 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 o pedido for bem-sucedido, é devolvido um recursooperations:

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

Liste as operações de longa duração num contentor

Linha de comandos

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

gcloud storage operations list gs://BUCKET_NAME

Substituição:

  • BUCKET_NAME com o nome do contentor 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 lhe permite gerar um token de acesso para o cabeçalho Authorization.

  2. Use cURL para chamar a API JSON com um pedido operations.get:

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

    Substituição:

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

Se o pedido for bem-sucedido, recebe uma resposta semelhante à seguinte:

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

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

Linha de comandos

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

Substituição:

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

  • OPERATION_ID com o ID da operação de longa duração, que é devolvido na resposta dos métodos que chama. Por exemplo, a seguinte resposta é devolvida 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 lhe permite gerar um token de acesso para o cabeçalho Authorization.

  2. Use cURL para chamar a API JSON com um pedido operations.post:

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

    Substituição:

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

    • OPERATION_ID com o ID da operação de longa duração, que é devolvido na resposta dos métodos que chama. Por exemplo, a seguinte resposta é devolvida 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. Os seguintes metadados 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 fim: a hora em que a operação de longa duração terminou.

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

  • Tipo: o tipo de operação de longa duração invocada.

  • Cancelamento pedido: indica se o utilizador pediu o cancelamento da operação de longa duração.

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

Processamento de erros

As operações de longa duração são iniciadas a partir de APIs assíncronas e requerem práticas de processamento de erros diferentes das APIs síncronas. Ao contrário das APIs síncronas, a resposta às chamadas de API assíncronas pode indicar êxito, mesmo que a operação de longa duração acabe por falhar. Em vez de se basear no código de estado devolvido nos cabeçalhos da resposta, deve analisar os metadados da operação de longa duração no corpo da resposta para determinar se uma chamada API foi bem-sucedida.

Por exemplo, se fizer um pedido de restauro em massa de eliminação reversível, é devolvido um código de estado HTTP bem-sucedido (200 OK), mesmo que ocorra um erro ao longo da operação. Para verificar se a operação de restauro em massa foi bem-sucedida, obtenha o estado da operação de longa duração.

Tenha em atenção que as APIs de operação de longa duração (Get, List e Cancel) são síncronas e devolvem erros normais.