Ativar e usar configurações de retenção de objetos

Visão geral

Nesta página, descrevemos como usar o recurso de bloqueio de retenção de objetos, incluindo a ativação em um bucket e a definição de configurações de retenção para objetos dentro do bucket.

Funções exigidas

Para receber as permissões necessárias para ativar o recurso de bloqueio de retenção de objetos em um bucket e definir as configurações de retenção nos objetos, peça ao administrador para conceder a você o papel do IAM de Administrador do Storage (roles/storage.admin) no bucket ou no projeto que o contém. Esse papel predefinido contém as permissões necessárias para definir e gerenciar as configurações de retenção. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

• storage.buckets.create
• storage.buckets.enableObjectRetention
• storage.buckets.get
• storage.buckets.list
  • Essa permissão só é necessária ao usar o console do Google Cloud para executar as instruções nesta página.
• storage.objects.get
• storage.objects.list
  • Essa permissão só é necessária ao usar o console do Google Cloud para executar as instruções nesta página.
• storage.objects.overrideUnlockedRetention
  • Essa permissão só será necessária se você planeja bloquear ou reduzir uma configuração de retenção existente.
• storage.objects.setRetention
• storage.objects.update

Talvez você também consiga receber essas permissões com papéis personalizados.

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.

Ativar retenções de objetos para um bucket

Só é possível ativar retenções de objetos como parte da criação do bucket, e se a retenção de objetos estiver ativada em um bucket, ela não poderá ser desativada. Use as instruções a seguir para ativar as retenções de objetos em um bucket:

Console

Crie um bucket como você faria normalmente e, na etapa Escolher como proteger os dados do objeto, selecione Retenção (para conformidade). por Ativar a retenção de objetos.

Linha de comando

Crie um bucket como faria normalmente e inclua a sinalização --enable-per-object-retention no comando.

APIs REST

API JSON

Crie um bucket como faria normalmente e inclua o parâmetro de consulta enableObjectRetention=true como parte da solicitação.

API XML

Crie um bucket normalmente e inclua o cabeçalho x-goog-bucket-object-lock-enabled: True como parte da solicitação.

Ver o status de retenção de objetos de um bucket

Para ver se as retenções de objetos estão ativadas em um bucket:

Console

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

   Acessar buckets

2. Clique no nome do bucket para verificar o status dele.

3. Clique na guia Proteção.

4. O status de retenção de objetos do bucket é exibido na seção Retenção de objetos.

Linha de comando

Use o comando gcloud storage buckets describe com a flag --format:

gcloud storage buckets describe gs://BUCKET_NAME --format="default(per_object_retention)"

Em que BUCKET_NAME é o nome do bucket da política de retenção que você quer visualizar. Por exemplo, my-bucket.

Se tiver êxito e houver uma política de retenção no bucket, a resposta será semelhante a esta:

per_object_retention:
  mode: Enabled

Se tiver êxito e não houver uma política de retenção no bucket, a resposta será semelhante a esta:

null

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 bucket GET que inclui o campo objectRetention:

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

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

API XML

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 XMLGET com uma solicitação do bucket ?object-lock com o escopo definido como :

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

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

Definir a configuração de retenção de um objeto

Cuidado: definir o modo de uma configuração de retenção como Locked (COMPLIANCE na API XML) é uma ação irreversível. e as condições abaixo serão aplicadas:

• Não é possível remover a configuração de retenção do objeto.
• Não é possível diminuir o tempo de retenção do objeto.

Para definir uma configuração de retenção para um objeto, ele precisa ser armazenado em um bucket em que as retenções de objetos estejam ativadas. Para definir uma configuração de retenção para um objeto:

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 a configuração de retenção que você quer definir ou modificar.

   A página Detalhes do bucket é aberta, com a guia Objetos selecionada.

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

4. Clique no nome do objeto.

   A página Detalhes do objeto é aberta, mostrando os metadados do objeto.

5. Na seção Proteção, clique no ícone Editar () associado à opção Da configuração de retenção de objetos.

   O painel Editar retenção será aberto.

6. Na seção Configuração de retenção de objetos, clique em Ativado ou Desativado.

   1. Se a configuração de retenção estiver ativada, selecione uma data e hora para a configuração na seção Reter até a hora e clique em Desbloqueado ou Bloqueado na seção Modo de retenção.

7. Clique em Confirm.

Observação: também é possível definir uma configuração de retenção para um objeto no momento em que ele é gravado no bucket. Se o bucket para o qual você está enviando o objeto tiver o recurso de retenção ativado, será exibido um painel durante o upload que permite especificar uma configuração de retenção para o objeto.

Linha de comando

Use o comando gcloud storage objects update com as sinalizações apropriadas: Para adicionar ou modificar uma configuração de retenção, use o comando a seguir. Observe que você também precisa incluir a flag --override-unlocked-retention se estiver modificando uma configuração existente de modo a bloqueá-la ou reduzir o tempo de retenção até:

gcloud storage objects update gs://BUCKET_NAME/OBJECT_NAME --retain-until=DATETIME --retention-mode=STATE

Em que:

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

• OBJECT_NAME é o nome do objeto relevante. Por exemplo, kitten.png.

• DATETIME é a data e a hora mais antigas em que o objeto pode ser excluído. Por exemplo, 2028-02-15T05:30:00Z.

• STATE é Locked ou Unlocked.

Se a operação for bem-sucedida, a resposta será semelhante a esta:

Updating gs://my-bucket/kitten.png...
  Completed 1  

Para remover uma configuração de retenção de um objeto, use o seguinte comando:

gcloud storage objects update gs://BUCKET_NAME/OBJECT_NAME --clear-retention --override-unlocked-retention

Em que:

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

• OBJECT_NAME é o nome do objeto relevante. Por exemplo, kitten.png.

Observação: também é possível definir uma configuração de retenção para um objeto no momento em que ele é gravado no bucket. Consulte a documentação do comando, como gcloud storage cp para mais informações.

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. Crie um arquivo JSON com as informações a seguir:

   {
     "retention": {
       "mode": STATE,
       "retainUntilTime": "DATETIME"
     }
   }

   Em que:

   • STATE é Locked ou Unlocked.

   • DATETIME é a data e a hora mais antigas em que o objeto pode ser excluído. Por exemplo, 2028-02-15T05:30:00Z.

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

   curl -X PATCH --data-binary @JSON_FILE_NAME \
   -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?overrideUnlockedRetention=BOOLEAN"

   Em que:

   • JSON_FILE_NAME é o caminho para o arquivo criado na Etapa 2.
   • BUCKET_NAME é o nome do bucket pertinente. Por exemplo, my-bucket.
   • OBJECT_NAME é o nome codificado por URL do objeto relevante. Por exemplo, pets/kitten.png, codificado em URL como pets%2Fkitten.png.
   • BOOLEAN precisará ser true se a solicitação encurtar, remover ou bloquear uma configuração de retenção existente. Caso contrário, o parâmetro overrideUnlockedRetention poderá ser totalmente excluído da solicitação.

Observação: também é possível definir uma configuração de retenção para um objeto no momento em que ele é gravado no bucket. Consulte a documentação da solicitação, como Objetos: inserção para mais informações.

API XML

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. Crie um arquivo XML que contenha as seguintes informações:

   <Retention>
     <Mode>
       STATE
     </Mode>
     <RetainUntilDate>
       DATETIME
     </RetainUntilDate>
   </Retention>

   Em que:

   • STATE é GOVERNANCE ou COMPLIANCE.

   • DATETIME é a data e a hora mais antigas em que o objeto pode ser excluído. Por exemplo, 2028-02-15T05:30:00Z.

3. Use cURL para chamar a API XML com uma solicitação de objeto PUT com escopo definido como ?retention:

   curl -X PUT --data-binary @XML_FILE_NAME \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-bypass-governance-retention: BOOLEAN" \
     "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME?retention"

   Em que:

   • XML_FILE_NAME é o caminho para o arquivo XML criado na Etapa 2.
   • BOOLEAN precisará ser true se a solicitação encurtar, remover ou bloquear uma configuração de retenção existente. Caso contrário, o cabeçalho x-goog-bypass-governance-retention poderá ser excluído da solicitação completamente.
   • BUCKET_NAME é o nome do bucket pertinente. Por exemplo, my-bucket.
   • OBJECT_NAME é o nome codificado por URL do objeto relevante. Por exemplo, pets/kitten.png, codificado em URL como pets%2Fkitten.png.

Observação: também é possível definir uma configuração de retenção para um objeto no momento em que ele é gravado no bucket. Consulte a documentação da solicitação, como PUT Object para mais informações.

Ver a configuração de retenção de um objeto

Para ver qual configuração de retenção está definida em um objeto, se houver alguma, faça o seguinte:

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 a configuração de retenção que você quer visualizar.

   A página Detalhes do bucket é aberta, com a guia Objetos selecionada.

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

4. Clique no nome do objeto.

   A página Detalhes do objeto é aberta, mostrando os metadados do objeto. As informações sobre qualquer configuração de retenção do objeto são mostradas na seção Proteção.

Linha de comando

Use o comando gcloud storage objects describe com a flag --format:

gcloud storage objects describe gs://BUCKET_NAME/OBJECT_NAME --format="default(retention_settings)"

Em que:

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

• OBJECT_NAME é o nome do objeto relevante. Por exemplo, kitten.png.

Se for bem-sucedida e existir uma configuração de retenção para o objeto, a resposta será semelhante a esta:

retention_settings:
  mode: Unlocked
  retainUntilTime: '2028-11-30T14:11:14+00:00'

Se for bem-sucedido e não houver uma configuração de retenção para o objeto, a resposta será semelhante a esta:

null

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 bucket GET que inclui o campo retention:

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

   Em que:

   • BUCKET_NAME é o nome do bucket pertinente. Por exemplo, my-bucket.
   • OBJECT_NAME é o nome do objeto relevante. Por exemplo, kitten.png.

API XML

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 XML com uma solicitação de objeto GET com escopo definido como ?retention:

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

   Em que:

   • BUCKET_NAME é o nome do bucket pertinente. Por exemplo, my-bucket.
   • OBJECT_NAME é o nome do objeto relevante. Por exemplo, kitten.png.

A seguir

• Saiba mais sobre as configurações de retenção.
• Conheça outros recursos que protegem seus dados do Cloud Storage.
• Saiba mais sobe o Gerenciamento do ciclo de vida de objetos, que pode excluir automaticamente os arquivos após o período de armazenamento.