Usar objetos excluídos de forma reversível

Visão geral Configuração

Nesta página, descrevemos como listar, acessar e restaurar objetos excluídos de maneira reversível.

Antes de começar

Para concluir as tarefas nesta página, verifique se você tem o papel do IAM de Administrador do Storage (roles/storage.admin) no bucket ou no projeto que contém o bucket. Esse papel predefinido inclui as permissões necessárias para gerenciar e restaurar a exclusão reversível em um bucket.

Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

  • storage.buckets.get
  • storage.buckets.update
  • storage.buckets.list
    • Essa permissão é necessária se você planeja usar o console do Google Cloud para executar as instruções desta página.
  • storage.objects.restore
  • storage.objects.create
  • storage.objects.delete
    • Essa permissão será necessária se a restauração de um objeto fizer com que um objeto existente seja substituído.
  • storage.buckets.restore
    • Essa permissão é necessária se você quiser restaurar em massa os objetos excluídos de maneira reversível em um bucket.
  • storage.bucketOperations.*
    • Essa permissão é necessária para operações de longa duração.

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 a projetos.

Listar todos os objetos excluídos de forma reversível em um bucket

É possível listar todos os objetos excluídos de maneira reversível em um bucket.

Console

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

    Acessar buckets

  2. Na lista de buckets, clique no nome do bucket que contém os objetos excluídos de maneira reversível. A página Detalhes do bucket é aberta, com a guia Objetos selecionada.

  3. Na lista Mostrar, selecione Somente objetos excluídos de forma reversível. Uma lista de objetos excluídos de maneira reversível será exibida.

Linha de comando

Para exibir uma lista de todos os objetos excluídos de maneira reversível em um bucket, use o comando gcloud storage ls com as flags --soft-deleted e --recursive:

  gcloud storage ls gs://BUCKET_NAME --soft-deleted --recursive

Substitua:

  • BUCKET_NAME: o nome do bucket Por exemplo, my-bucket.

APIs REST

API JSON

  1. Ter a gcloud CLI instalada e inicializadapara 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.

  2. Usar cURL para chamarAPI JSON com um solicitação para listar objetos que usam o parâmetro de consulta ?softDeleted:

    curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o?softDeleted=true"

    Em que BUCKET_NAME é o nome do bucket pertinente. Por exemplo, my-bucket.

Ver todas as versões de um objeto excluídas de maneira reversível

É possível ver todas as versões excluídas de forma reversível de um objeto específico no seu bucket.

Console

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

    Acessar buckets

  2. Na lista de buckets, clique no nome do bucket que contém o objeto com as versões que você quer ver de maneira reversível. A página Detalhes do bucket é aberta, com a guia Objetos selecionada.

  3. Clique no objeto de que você quer ver todas as versões excluídas de forma reversível. A página Detalhes do objeto é exibida.

  4. Clique na guia Histórico de versões.

  5. Na lista Mostrar, selecione Somente objetos excluídos de forma reversível. Uma lista de todas as versões excluídas de maneira reversível desse objeto é exibida.

Linha de comando

Para exibir uma lista de todas as versões de um objeto em um bucket que foram excluídas de maneira reversível, use o comando gcloud storage ls:

  gcloud storage ls gs://BUCKET_NAME/OBJECT_NAME --soft-deleted

Substitua:

  • BUCKET_NAME: o nome do bucket Por exemplo, my-bucket.
  • OBJECT_NAME: o nome do objeto que contém todas as versões dele.

APIs REST

API JSON

  1. Ter a gcloud CLI instalada e inicializadapara 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.

  2. Usar cURL para chamarAPI JSON com um solicitação para listar objetos que usam o parâmetro de consulta ?softDeleted:

    curl -X GET \
  -H "Authorization: Bearer OAUTH2_TOKEN" \
  -H "Content-Type: application/json" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o?softDeleted=true"

    Em que BUCKET_NAME é o nome do bucket pertinente. Por exemplo, my-bucket.

Restaurar um objeto excluído de maneira reversível

É possível restaurar uma versão específica de um objeto excluído de maneira reversível no seu bucket.

Console

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

    Acessar buckets

  2. Na lista de buckets, clique no nome do bucket que contém os objetos excluídos de forma reversível que você quer restaurar. A página Detalhes do bucket é aberta, com a guia Objetos selecionada.

  3. Na lista Mostrar, selecione Somente objetos excluídos de forma reversível.

  4. Navegue até o objeto, que pode estar localizado em uma pasta.

  5. Clique no objeto excluído de maneira reversível. A página Detalhes do objeto é exibida.

  6. Na lista Mostrar, selecione Somente objetos excluídos de forma reversível. Uma lista de todas as versões excluídas de maneira reversível desse objeto é exibida.

  7. Para restaurar uma versão específica de um objeto excluída de forma reversível, clique em Restaurar ao lado dessa versão. O painel da versão do objeto de restauração é aberto.

  8. Clique em Confirm.

Linha de comando

Para restaurar uma versão excluída de forma reversível de um objeto, use o comando gcloud storage restore:

  gcloud storage restore gs://BUCKET_NAME/OBJECT_NAME#GENERATION_NUMBER

Substitua:

  • BUCKET_NAME: o nome do bucket Por exemplo, my-bucket.
  • OBJECT_NAME: o nome do objeto para o qual você quer ver todas as versões.
  • GENERATION_NUMBER: o número de geração do objeto excluído de maneira reversível que você quer restaurar. Se você não especificar o número de geração, a versão mais recente será restaurada. Por exemplo, 1560468815691234.

Para mais opções de restauração de vários objetos em massa, incluindo a restauração de todas as versões de um objeto com a flag all-versions, consulte a referência gcloud storage restore.

APIs REST

API JSON

  1. Ter a gcloud CLI instalada e inicializadapara 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.

  2. Use cURL para chamar a API JSON com uma solicitação de POST Objeto:

    curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME/restore?generation=GENERATION_NUMBER"

    Em que:

    • BUCKET_NAME é o nome do bucket pertinente. Por exemplo, my-bucket.
    • OBJECT_NAME é o nome do objeto excluído de maneira reversível que você quer restaurar. Por exemplo, cat.jpeg.
    • GENERATION_NUMBER é o número de geração do objeto excluído de maneira reversível que você quer restaurar. Se você não especificar o número de geração, a versão mais recente será restaurada. Por exemplo, 1560468815691234.

Restaure em massa objetos excluídos de maneira reversível em um bucket

Se você quiser restaurar um grande número de objetos ou não souber quais objetos específicos quer restaurar, use a operação de restauração em massa. As operações de restauração em massa ocorrem de maneira assíncrona e podem, em alguns casos, levar uma hora ou mais para começar.

A operação de restauração em massa inicia uma operação de longa duração em um bucket. É possível usar a Google Cloud CLI para receber e listar operações de longa duração para visualizar os detalhes e o status da operação de restauração em massa enquanto ela está em andamento.

Console

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

    Acessar buckets

  2. Na lista de buckets, encontre o bucket que contém os objetos que você quer restaurar.

  3. Clique no menu flutuante bucket () associado ao bucket e selecione Criar job de restauração.

    O painel Criar um job de restauração é aberto.

  4. Na seção Escolher quais objetos excluídos de maneira reversível serão restaurados, selecione o período de exclusão a partir do qual você quer restaurar objetos.

  5. (Opcional) Selecione Filtrar por padrão glob e insira um padrão para restaurar apenas objetos que atendam aos critérios desse padrão.

  6. (Opcional) Ative outros comportamentos de restauração na seção Opções de restauração.

  7. Clique em Criar.

Para acompanhar o progresso da operação de restauração em massa, clique no botão Notificações () no cabeçalho do console do Google Cloud.

Linha de comando

Para usar a operação de restauração em massa para restaurar todos os objetos em um bucket, use o comando gcloud storage restore.

O comando a seguir executa a operação de restauração em massa para restaurar de maneira assíncrona todos os objetos do bucket que foram excluídos durante um período específico:

  gcloud storage restore gs://BUCKET_NAME/** \
      --async --deleted-after-time=DELETED_AFTER_TIME \
      --deleted-before-time=DELETED_BEFORE_TIME

Substitua:

  • BUCKET_NAME: o nome do bucket Por exemplo, my-bucket.
  • DELETED_AFTER_TIME: um argumento opcional para especificar a data após a qual os objetos são restaurados. Por exemplo, 2022-12-01.

  • DELETED_BEFORE_TIME: um argumento opcional para especificar a data antes da restauração dos objetos. Por exemplo, 2022-12-21.

    Se bem-sucedido, o comando retornará o ID da operação de longa duração associada à operação de restauração em massa. É possível ver detalhes sobre a operação de longa duração ou cancelar a operação de longa duração para interromper a operação de restauração em massa antes que ela seja concluída.

APIs REST

API JSON

  1. Ter a gcloud CLI instalada e inicializadapara 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.

  2. Use cURL para chamar a API JSON com uma solicitação de POST Objeto:

    curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/bulkRestore"

    Em que BUCKET_NAME é o nome do bucket pertinente. Por exemplo, my-bucket.

Se bem-sucedido, o comando retornará o ID da operação de longa duração associada à operação de restauração em massa. É possível ver detalhes sobre a operação de longa duração ou cancelar a operação de longa duração para interromper a operação de restauração em massa antes que ela seja concluída.

Gerenciar operações de longa duração para restauração em massa

As operações de longa duração na Google Cloud CLI são identificadas por um nome de operação, que é uma combinação do nome do bucket e do ID da operação.

O exemplo a seguir mostra uma operação de longa duração retornada de uma operação de restauração em massa:

done: false
{
  "kind": "storage@operation",
  "name": "projects/_/buckets/my-bucket/operations/CiQyODRlMTY0My0wNGExLTQ3MWItOTE2Zi1hZmQ0ZmM4ZDc4MjQQAg",
  "metadata": {
    "@type": "type.googleapis.com/google.storage.v2.BulkRestoreObjectsMetadata",
    "commonMetadata": {
      "type": "bulk-restore-objects",
      "createTime": "2023-10-20T21:08:11.289Z",
      "updateTime": "2023-10-20T21:18:37.583Z",
      "endTime": "2023-10-20T21:18:37.583Z",
      "requestedCancellation": false,
      "progressPercent": -1,
    },
    "allow_overwrite": false,
    "matchGlobs": ["*"],
    "succeededCount": "0",
    "failedCount": "0",
    "skippedCount": "0",
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.storage.v2.BulkRestoreObjectsResponse"
  }
}

Para informações gerais sobre como gerenciar operações de longa duração, consulte a documentação do gcloud storage operations.

Acessar os detalhes 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: o nome do bucket que contém a operação de longa duração. Por exemplo, my-bucket.

  • OPERATION_ID: o ID da operação de longa duração retornada na resposta da operação de restauração em massa.

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: o nome do bucket que contém as operações de longa duração. Por exemplo, my-bucket.

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: o nome do bucket que contém a operação de longa duração. Por exemplo, my-bucket.

  • OPERATION_ID: o ID da operação de longa duração retornada na resposta da operação de restauração em massa.

Tratamento de erros

Operações de longa duração são retornadas de APIs assíncronas, que exigem práticas de tratamento de erros diferentes das APIs síncronas. Ao contrário das APIs síncronas, as que retornam operações de longa duração são bem-sucedidas mesmo se a operação falhar. Ao usar APIs que retornam operações de longa duração, você responde aos códigos de erro retornados em respostas bem-sucedidas, em vez de responder aos códigos de erro retornados em respostas com falha.

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, Create, Cancel) são síncronas e retornam erros normais.

Novas tentativas

As APIs assíncronas de exclusão reversível são idempotentes por padrão. Portanto, você pode repetir com segurança chamadas de API com exclusão reversível com segurança sem se preocupar em modificar recursos acidentalmente.

A seguir