Como usar retenções de objeto

Acessar conceitos

Nesta página, você verá como usar as retenções de objeto, incluindo a colocação de retenções por padrão em novos objetos e a colocação de retenções em objetos individuais.

Pré-requisitos

Antes de usar este recurso no Cloud Storage, realize estas etapas:

  1. Tenha permissão suficiente para ver e atualizar buckets e objetos no Cloud Storage:

    • Se você é proprietário do projeto que contém o bucket, provavelmente já tem as permissões necessárias.

    • Se você usa o IAM, é necessário ter as permissões storage.buckets.update, storage.buckets.get, storage.objects.update e storage.objects.get no bucket relevante. Consulte Como usar as permissões do IAM para ver instruções sobre como conseguir um papel, como o de Administrador do Storage, que tenha essas permissões.

    • Se você usar ACLs, precisará da permissão PROPRIETÁRIO no bucket em questão e nos objetos dentro dele. Consulte Como configurar ACLs para ver instruções sobre como fazer isso.

Como trabalhar com a propriedade de retenção baseada em evento padrão

As tarefas a seguir mostram como ativar, visualizar e desativar a propriedade de retenção baseada em eventos padrão em um bucket. Quando essa propriedade é ativada, novos objetos adicionados ao bucket recebem automaticamente uma retenção baseada em evento.

Como ativar a propriedade de retenção baseada em evento padrão

Para colocar automaticamente uma retenção baseada em eventos em cada novo objeto adicionado a um bucket:

Console

  1. Abra o navegador do Cloud Storage no Console do Google Cloud.
    Abra o navegador do Cloud Storage
  2. Na lista de buckets, clique no nome do bucket para o qual você quer ativar a propriedade de retenção baseada em eventos padrão.

  3. Selecione a guia Retenção na parte superior da página.

  4. Na seção Opção de retenção baseada em evento padrão, clique no botão Desativado.

    Se for bem-sucedido, o botão mudará para Ativado.

Consulte a Solução de problemas para informações detalhadas sobre erros de operações com falha no navegador do Cloud Storage.

gsutil

Use o comando gsutil retention event-default set:

gsutil retention event-default set gs://BUCKET_NAME

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

Amostras de código

C++

Para mais informações, consulte a documentação de referência da API Cloud Storage para C++.

Ver no GitHub (em inglês) Feedback
namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name) {
  StatusOr<gcs::BucketMetadata> original =
      client.GetBucketMetadata(bucket_name);

  if (!original) throw std::runtime_error(original.status().message());
  StatusOr<gcs::BucketMetadata> patched_metadata = client.PatchBucket(
      bucket_name,
      gcs::BucketMetadataPatchBuilder().SetDefaultEventBasedHold(true),
      gcs::IfMetagenerationMatch(original->metageneration()));

  if (!patched_metadata) {
    throw std::runtime_error(patched_metadata.status().message());
  }

  std::cout << "The default event-based hold for objects in bucket "
            << bucket_name << " is "
            << (patched_metadata->default_event_based_hold() ? "enabled"
                                                             : "disabled")
            << "\n";
}

C#

Para mais informações, consulte a documentação de referência da API Cloud Storage para C#.

private void EnableBucketDefaultEventBasedHold(string bucketName)
{
    var storage = StorageClient.Create();
    var bucket = storage.GetBucket(bucketName);
    bucket.DefaultEventBasedHold = true;
    bucket = storage.UpdateBucket(bucket, new UpdateBucketOptions()
    {
        // Use IfMetagenerationMatch to avoid race conditions.
        IfMetagenerationMatch = bucket.Metageneration
    });
    Console.WriteLine($"Default event-based hold was enabled for {bucketName}");
}

Go

Para mais informações, consulte a documentação de referência da API Cloud Storage para Go.

ctx := context.Background()

bucket := c.Bucket(bucketName)
bucketAttrsToUpdate := storage.BucketAttrsToUpdate{
	DefaultEventBasedHold: true,
}
ctx, cancel := context.WithTimeout(ctx, time.Second*10)
defer cancel()
if _, err := bucket.Update(ctx, bucketAttrsToUpdate); err != nil {
	return err
}

Java

Para mais informações, consulte a documentação de referência da API Cloud Storage para Java.

Ver no GitHub (em inglês) Feedback
// Instantiate a Google Cloud Storage client
Storage storage = StorageOptions.getDefaultInstance().getService();

// The name of a bucket, e.g. "my-bucket"
// String bucketName = "my-bucket";

Bucket bucket =
    storage.update(BucketInfo.newBuilder(bucketName).setDefaultEventBasedHold(true).build());

System.out.println("Default event-based hold was enabled for " + bucketName);

Node.js

Para mais informações, consulte a documentação de referência da API Cloud Storage para Node.js.

Ver no GitHub (em inglês) Feedback

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const bucketName = 'Name of a bucket, e.g. my-bucket';

// Enables a default event-based hold for the bucket.

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function enableDefaultEventBasedHold() {
  // Enables a default event-based hold for the bucket.
  await storage.bucket(bucketName).setMetadata({
    defaultEventBasedHold: true,
  });

  console.log(`Default event-based hold was enabled for ${bucketName}.`);
}

enableDefaultEventBasedHold().catch(console.error);

PHP

Para mais informações, consulte a documentação de referência da API Cloud Storage para PHP.

use Google\Cloud\Storage\StorageClient;

/**
 * Enables a default event-based hold for a bucket.
 *
 * @param string $bucketName the name of your Cloud Storage bucket.
 */
function enable_default_event_based_hold($bucketName)
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $bucket->update(['defaultEventBasedHold' => true]);
    printf('Default event-based hold was enabled for %s' . PHP_EOL, $bucketName);
}

Python

Para mais informações, consulte a documentação de referência da API Cloud Storage para Python.

Ver no GitHub (em inglês) Feedback
from google.cloud import storage

def enable_default_event_based_hold(bucket_name):
    """Enables the default event based hold on a given bucket"""
    # bucket_name = "my-bucket"

    storage_client = storage.Client()

    bucket = storage_client.bucket(bucket_name)
    bucket.default_event_based_hold = True
    bucket.patch()

    print("Default event based hold was enabled for {}".format(bucket_name))

Ruby

Para mais informações, consulte a documentação de referência da API Cloud Storage para Ruby.

# bucket_name = "Name of your Google Cloud Storage bucket"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new
bucket  = storage.bucket bucket_name

bucket.update do |b|
  b.default_event_based_hold = true
end

puts "Default event-based hold was enabled for #{bucket_name}."

APIs REST

API JSON

  1. Receba um token de acesso de autorização do OAuth 2.0 Playground. Configure o Playground para usar suas credenciais do OAuth.
  2. Crie um arquivo .json com as informações a seguir:

    {
      "defaultEventBasedHold": true
    }
  3. Use cURL para chamar a API JSON com uma solicitação de bucket PATCH:

    curl -X PATCH --data-binary @JSON_FILE_NAME.json \
    -H "Authorization: Bearer OAUTH2_TOKEN" \
    -H "Content-Type: application/json" \
    "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=defaultEventBasedHold"

    Em que:

    • JSON_FILE_NAME é o nome do arquivo que você criou na etapa 2;
    • OAUTH2_TOKEN é o token de acesso gerado na etapa 1;
    • BUCKET_NAME é o nome do bucket pertinente. Por exemplo, my-bucket.

API XML

A API XML não pode ser usada para trabalhar com retenções de objeto. Use uma das outras ferramentas do Cloud Storage, como o gsutil.

Como conseguir o status de retenção padrão de um bucket

Para ver se um bucket coloca as retenções baseadas em eventos em novos objetos por padrão:

Console

  1. Abra o navegador do Cloud Storage no Console do Google Cloud.
    Abra o navegador do Cloud Storage
  2. Na lista de buckets, clique no nome do bucket para o qual você quer verificar o status baseado em eventos padrão.

  3. Selecione a guia Retenção na parte superior da página.

  4. O status aparece na seção Opção de retenção baseada em evento padrão.

Consulte a Solução de problemas para informações detalhadas sobre erros de operações com falha no navegador do Cloud Storage.

gsutil

Use o seguinte gsutil ls comando:

gsutil ls -L -b gs://BUCKET_NAME

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

A resposta terá esta aparência:

gs://my-bucket/ :
  Storage class:         STANDARD
  ...
  ...
  Default Event-Based Hold: True
  ...

Se o bucket não colocar retenções baseadas em eventos em novos objetos por padrão, o gsutil omitirá Default Event-Based Hold da saída completamente.

Amostras de código

C++

Para mais informações, consulte a documentação de referência da API Cloud Storage para C++.

Ver no GitHub (em inglês) Feedback
namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name) {
  StatusOr<gcs::BucketMetadata> bucket_metadata =
      client.GetBucketMetadata(bucket_name);

  if (!bucket_metadata) {
    throw std::runtime_error(bucket_metadata.status().message());
  }

  std::cout << "The default event-based hold for objects in bucket "
            << bucket_metadata->name() << " is "
            << (bucket_metadata->default_event_based_hold() ? "enabled"
                                                            : "disabled")
            << "\n";
}

C#

Para mais informações, consulte a documentação de referência da API Cloud Storage para C#.

private bool GetBucketDefaultEventBasedHold(string bucketName)
{
    var storage = StorageClient.Create();
    var bucket = storage.GetBucket(bucketName);
    bool? defaultEventBasedHoldOrNull = bucket?.DefaultEventBasedHold;
    bool defaultEventBasedHold =
        defaultEventBasedHoldOrNull.HasValue ? defaultEventBasedHoldOrNull.Value : false;
    Console.WriteLine("Default event-based hold: {0}", defaultEventBasedHold);
    return defaultEventBasedHold;
}

Go

Para mais informações, consulte a documentação de referência da API Cloud Storage para Go.

ctx := context.Background()

ctx, cancel := context.WithTimeout(ctx, time.Second*10)
defer cancel()
attrs, err := c.Bucket(bucketName).Attrs(ctx)
if err != nil {
	return nil, err
}
log.Printf("Default event-based hold enabled? %t\n",
	attrs.DefaultEventBasedHold)

Java

Para mais informações, consulte a documentação de referência da API Cloud Storage para Java.

Ver no GitHub (em inglês) Feedback
// Instantiate a Google Cloud Storage client
Storage storage = StorageOptions.getDefaultInstance().getService();

// The name of a bucket, e.g. "my-bucket"
// String bucketName = "my-bucket";

Bucket bucket =
    storage.get(bucketName, BucketGetOption.fields(BucketField.DEFAULT_EVENT_BASED_HOLD));

if (bucket.getDefaultEventBasedHold() != null && bucket.getDefaultEventBasedHold()) {
  System.out.println("Default event-based hold is enabled for " + bucketName);
} else {
  System.out.println("Default event-based hold is not enabled for " + bucketName);
}

Node.js

Para mais informações, consulte a documentação de referência da API Cloud Storage para Node.js.

Ver no GitHub (em inglês) Feedback
/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const bucketName = 'Name of a bucket, e.g. my-bucket';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function getDefaultEventBasedHold() {
  // get bucketName metadata
  const [metadata] = await storage.bucket(bucketName).getMetadata();
  console.log(`Default event-based hold: ${metadata.defaultEventBasedHold}.`);
}

getDefaultEventBasedHold().catch(console.error);

PHP

Para mais informações, consulte a documentação de referência da API Cloud Storage para PHP.

use Google\Cloud\Storage\StorageClient;

/**
 * Enables a default event-based hold for a bucket.
 *
 * @param string $bucketName the name of your Cloud Storage bucket.
 */
function get_default_event_based_hold($bucketName)
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);

    if ($bucket->info()['defaultEventBasedHold']) {
        printf('Default event-based hold is enabled for ' . $bucketName . PHP_EOL);
    } else {
        printf('Default event-based hold is not enabled for ' . $bucketName . PHP_EOL);
    }
}

Python

Para mais informações, consulte a documentação de referência da API Cloud Storage para Python.

Ver no GitHub (em inglês) Feedback
from google.cloud import storage

def get_default_event_based_hold(bucket_name):
    """Gets the default event based hold on a given bucket"""
    # bucket_name = "my-bucket"

    storage_client = storage.Client()

    bucket = storage_client.get_bucket(bucket_name)

    if bucket.default_event_based_hold:
        print("Default event-based hold is enabled for {}".format(bucket_name))
    else:
        print(
            "Default event-based hold is not enabled for {}".format(
                bucket_name
            )
        )

Ruby

Para mais informações, consulte a documentação de referência da API Cloud Storage para Ruby.

# bucket_name = "Name of your Google Cloud Storage bucket"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new
bucket  = storage.bucket bucket_name

if bucket.default_event_based_hold?
  puts "Default event-based hold is enabled for #{bucket_name}."
else
  puts "Default event-based hold is not enabled for #{bucket_name}."
end

APIs REST

API JSON

  1. Receba um token de acesso de autorização do OAuth 2.0 Playground. Configure o Playground para usar suas credenciais do OAuth.
  2. Use cURL para chamar a API JSON com uma solicitação deGET bucket que inclui os fields desejados:

    curl -X GET -H "Authorization: Bearer OAUTH2_TOKEN" \
    "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=defaultEventBasedHold"

    Em que:

    • OAUTH2_TOKEN é o token de acesso gerado na etapa 1;
    • BUCKET_NAME é o nome do bucket pertinente. Por exemplo, my-bucket.

    Se o bucket tiver uma retenção baseada em evento padrão ativada para ele, a resposta será semelhante ao exemplo a seguir:

    {
      "retentionPolicy": true
    }

API XML

A API XML não pode ser usada para trabalhar com retenções de objeto. Use uma das outras ferramentas do Cloud Storage, como o gsutil.

Como desativar uma retenção baseada em eventos padrão

Para desativar uma retenção baseada em eventos padrão em um bucket:

Console

  1. Abra o navegador do Cloud Storage no Console do Google Cloud.
    Abra o navegador do Cloud Storage
  2. Na lista de buckets, clique no nome do bucket no qual você quer desativar a retenção baseada em eventos padrão.

  3. Selecione a guia Retenção na parte superior da página.

  4. Na seção Opção de retenção baseada em evento padrão, clique no botão Ativado.

    Se for bem-sucedido, o botão mudará para Desativado.

Consulte a Solução de problemas para informações detalhadas sobre erros de operações com falha no navegador do Cloud Storage.

gsutil

Use o comando gsutil retention event-default release:

gsutil retention event-default release gs://BUCKET_NAME

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

Amostras de código

C++

Para mais informações, consulte a documentação de referência da API Cloud Storage para C++.

Ver no GitHub (em inglês) Feedback
namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name) {
  StatusOr<gcs::BucketMetadata> original =
      client.GetBucketMetadata(bucket_name);

  if (!original) throw std::runtime_error(original.status().message());
  StatusOr<gcs::BucketMetadata> patched_metadata = client.PatchBucket(
      bucket_name,
      gcs::BucketMetadataPatchBuilder().SetDefaultEventBasedHold(false),
      gcs::IfMetagenerationMatch(original->metageneration()));

  if (!patched_metadata) {
    throw std::runtime_error(patched_metadata.status().message());
  }

  std::cout << "The default event-based hold for objects in bucket "
            << bucket_name << " is "
            << (patched_metadata->default_event_based_hold() ? "enabled"
                                                             : "disabled")
            << "\n";
}

C#

Para mais informações, consulte a documentação de referência da API Cloud Storage para C#.

private void DisableBucketDefaultEventBasedHold(string bucketName)
{
    var storage = StorageClient.Create();
    var bucket = storage.GetBucket(bucketName);
    bucket.DefaultEventBasedHold = false;
    bucket = storage.UpdateBucket(bucket, new UpdateBucketOptions()
    {
        // Use IfMetagenerationMatch to avoid race conditions.
        IfMetagenerationMatch = bucket.Metageneration
    });
    Console.WriteLine($"Default event-based hold was disabled for {bucketName}");
}

Go

Para mais informações, consulte a documentação de referência da API Cloud Storage para Go.

ctx := context.Background()

bucket := c.Bucket(bucketName)
bucketAttrsToUpdate := storage.BucketAttrsToUpdate{
	DefaultEventBasedHold: false,
}
ctx, cancel := context.WithTimeout(ctx, time.Second*10)
defer cancel()
if _, err := bucket.Update(ctx, bucketAttrsToUpdate); err != nil {
	return err
}

Java

Para mais informações, consulte a documentação de referência da API Cloud Storage para Java.

Ver no GitHub (em inglês) Feedback
// Instantiate a Google Cloud Storage client
Storage storage = StorageOptions.getDefaultInstance().getService();

// The name of a bucket, e.g. "my-bucket"
// String bucketName = "my-bucket";

Bucket bucket =
    storage.update(BucketInfo.newBuilder(bucketName).setDefaultEventBasedHold(false).build());

System.out.println("Default event-based hold was disabled for " + bucketName);

Node.js

Para mais informações, consulte a documentação de referência da API Cloud Storage para Node.js.

Ver no GitHub (em inglês) Feedback
/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const bucketName = 'Name of a bucket, e.g. my-bucket';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function disableDefaultEventBasedHold() {
  // Disables a default event-based hold for a bucket.
  await storage.bucket(bucketName).setMetadata({
    defaultEventBasedHold: false,
  });
  console.log(`Default event-based hold was disabled for ${bucketName}.`);
}

disableDefaultEventBasedHold().catch(console.error);

PHP

Para mais informações, consulte a documentação de referência da API Cloud Storage para PHP.

use Google\Cloud\Storage\StorageClient;

/**
 * Disables a default event-based hold for a bucket.
 *
 * @param string $bucketName the name of your Cloud Storage bucket.
 */
function disable_default_event_based_hold($bucketName)
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $bucket->update(['defaultEventBasedHold' => false]);
    printf('Default event-based hold was disabled for %s' . PHP_EOL, $bucketName);
}

Python

Para mais informações, consulte a documentação de referência da API Cloud Storage para Python.

Ver no GitHub (em inglês) Feedback
from google.cloud import storage

def disable_default_event_based_hold(bucket_name):
    """Disables the default event based hold on a given bucket"""
    # bucket_name = "my-bucket"

    storage_client = storage.Client()

    bucket = storage_client.get_bucket(bucket_name)
    bucket.default_event_based_hold = False
    bucket.patch()

    print("Default event based hold was disabled for {}".format(bucket_name))

Ruby

Para mais informações, consulte a documentação de referência da API Cloud Storage para Ruby.

# bucket_name = "Name of your Google Cloud Storage bucket"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new
bucket  = storage.bucket bucket_name

bucket.update do |b|
  b.default_event_based_hold = false
end

puts "Default event-based hold was disabled for #{bucket_name}."

APIs REST

API JSON

  1. Receba um token de acesso de autorização do OAuth 2.0 Playground. Configure o Playground para usar suas credenciais do OAuth.
  2. Crie um arquivo .json com as informações a seguir:

    {
      "defaultEventBasedHold": false
    }
  3. Use cURL para chamar a API JSON com uma solicitação de bucket PATCH:

    curl -X PATCH --data-binary @JSON_FILE_NAME.json \
    -H "Authorization: Bearer OAUTH2_TOKEN" \
    -H "Content-Type: application/json" \
    "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=defaultEventBasedHold"

    Em que:

    • JSON_FILE_NAME é o nome do arquivo que você criou na etapa 2;
    • OAUTH2_TOKEN é o token de acesso gerado na etapa 1;
    • BUCKET_NAME é o nome do bucket pertinente. Por exemplo, my-bucket.

API XML

A API XML não pode ser usada para trabalhar com retenções de objeto. Use uma das outras ferramentas do Cloud Storage, como o gsutil.

Como trabalhar com retenções de objeto

As tarefas a seguir mostram como colocar, visualizar e liberar retenções em objetos.

Como colocar uma retenção de objeto

Para colocar uma retenção em um objeto no seu bucket:

Console

  1. Abra o navegador do Cloud Storage no Console do Google Cloud.
    Abra o navegador do Cloud Storage
  2. Na lista de buckets, clique no nome do bucket que contém os objetos em que você quer colocar retenções.

  3. Marque a caixa de seleção ao lado dos nomes dos objetos que você quer colocar retenções.

  4. Clique no botão Gerenciar retenções.

    A janela Gerenciar retenções é exibida.

  5. Selecione a caixa de seleção para os tipos de retenção que você quer colocar nos objetos selecionados

  6. Clique em Salvar configurações de retenção.

Consulte a Solução de problemas para informações detalhadas sobre erros de operações com falha no navegador do Cloud Storage.

gsutil

Use o comando gsutil retention:

gsutil retention HOLD_TYPE set gs://BUCKET_NAME/OBJECT_NAME

Onde:

  • HOLD_TYPE é o tipo de retenção que você quer aplicar ao seu objeto. Por exemplo, temp ou event. Consulte Retenções de objetos para saber mais sobre os tipos de retenção.
  • BUCKET_NAME é o nome do bucket pertinente. Por exemplo, my-bucket.
  • OBJECT_NAME é o nome do objeto relevante. Por exemplo, pets/dog.png.

Amostras de código

C++

Para mais informações, consulte a documentação de referência da API Cloud Storage para C++.

No exemplo a seguir, uma retenção baseada em evento é definida em um objeto:

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& object_name) {
  StatusOr<gcs::ObjectMetadata> original =
      client.GetObjectMetadata(bucket_name, object_name);
  if (!original) throw std::runtime_error(original.status().message());

  StatusOr<gcs::ObjectMetadata> updated = client.PatchObject(
      bucket_name, object_name,
      gcs::ObjectMetadataPatchBuilder().SetEventBasedHold(true),
      gcs::IfMetagenerationMatch(original->metageneration()));
  if (!updated) throw std::runtime_error(updated.status().message());

  std::cout << "The event hold for object " << updated->name()
            << " in bucket " << updated->bucket() << " is "
            << (updated->event_based_hold() ? "enabled" : "disabled") << "\n";
}

No exemplo a seguir, uma retenção temporária é definida em um objeto:

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& object_name) {
  StatusOr<gcs::ObjectMetadata> original =
      client.GetObjectMetadata(bucket_name, object_name);
  if (!original) throw std::runtime_error(original.status().message());

  StatusOr<gcs::ObjectMetadata> updated = client.PatchObject(
      bucket_name, object_name,
      gcs::ObjectMetadataPatchBuilder().SetTemporaryHold(true),
      gcs::IfMetagenerationMatch(original->metageneration()));
  if (!updated) throw std::runtime_error(updated.status().message());

  std::cout << "The temporary hold for object " << updated->name()
            << " in bucket " << updated->bucket() << " is "
            << (updated->temporary_hold() ? "enabled" : "disabled") << "\n";
}

C#

Para mais informações, consulte a documentação de referência da API Cloud Storage para C#.

No exemplo a seguir, uma retenção baseada em evento é definida em um objeto:

private void SetObjectEventBasedHold(string bucketName,
    string objectName)
{
    var storage = StorageClient.Create();
    var storageObject = storage.GetObject(bucketName, objectName);
    storageObject.EventBasedHold = true;
    storageObject = storage.UpdateObject(storageObject, new UpdateObjectOptions()
    {
        // Use IfMetagenerationMatch to avoid race conditions.
        IfMetagenerationMatch = storageObject.Metageneration
    });
}

No exemplo a seguir, uma retenção temporária é definida em um objeto:

private void SetObjectTemporaryHold(string bucketName,
    string objectName)
{
    var storage = StorageClient.Create();
    var storageObject = storage.GetObject(bucketName, objectName);
    storageObject.TemporaryHold = true;
    storageObject = storage.UpdateObject(storageObject, new UpdateObjectOptions()
    {
        // Use IfMetagenerationMatch to avoid race conditions.
        IfMetagenerationMatch = storageObject.Metageneration,
    });
}

Go

Para mais informações, consulte a documentação de referência da API Cloud Storage para Go.

No exemplo a seguir, uma retenção baseada em evento é definida em um objeto:

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/storage"
)

// setEventBasedHold sets EventBasedHold flag of an object to true.
func setEventBasedHold(w io.Writer, bucket, object string) error {
	// bucket := "bucket-name"
	// object := "object-name"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %v", err)
	}
	defer client.Close()

	ctx, cancel := context.WithTimeout(ctx, time.Second*10)
	defer cancel()

	o := client.Bucket(bucket).Object(object)
	objectAttrsToUpdate := storage.ObjectAttrsToUpdate{
		EventBasedHold: true,
	}
	if _, err := o.Update(ctx, objectAttrsToUpdate); err != nil {
		return fmt.Errorf("Object(%q).Update: %v", object, err)
	}
	fmt.Fprintf(w, "Default event based hold was enabled for %v.\n", object)
	return nil
}

No exemplo a seguir, uma retenção temporária é definida em um objeto:

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/storage"
)

// setTemporaryHold sets TemporaryHold flag of an object to true.
func setTemporaryHold(w io.Writer, bucket, object string) error {
	// bucket := "bucket-name"
	// object := "object-name"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %v", err)
	}
	defer client.Close()

	ctx, cancel := context.WithTimeout(ctx, time.Second*10)
	defer cancel()

	o := client.Bucket(bucket).Object(object)
	objectAttrsToUpdate := storage.ObjectAttrsToUpdate{
		TemporaryHold: true,
	}
	if _, err := o.Update(ctx, objectAttrsToUpdate); err != nil {
		return fmt.Errorf("Object(%q).Update: %v", object, err)
	}
	fmt.Fprintf(w, "Temporary hold was enabled for %v.\n", object)
	return nil
}

Java

Para mais informações, consulte a documentação de referência da API Cloud Storage para Java.

No exemplo a seguir, uma retenção baseada em evento é definida em um objeto:

// Instantiate a Google Cloud Storage client
Storage storage = StorageOptions.getDefaultInstance().getService();

// The name of a bucket, e.g. "my-bucket"
// String bucketName = "my-bucket";

// The name of a blob, e.g. "my-blob"
// String blobName = "my-blob";

BlobId blobId = BlobId.of(bucketName, blobName);
Blob blob = storage.update(BlobInfo.newBuilder(blobId).setEventBasedHold(true).build());

System.out.println("Event-based hold was set for " + blobName);

No exemplo a seguir, uma retenção temporária é definida em um objeto:

// Instantiate a Google Cloud Storage client
Storage storage = StorageOptions.getDefaultInstance().getService();

// The name of a bucket, e.g. "my-bucket"
// String bucketName = "my-bucket";

// The name of a blob, e.g. "my-blob"
// String blobName = "my-blob";

BlobId blobId = BlobId.of(bucketName, blobName);
Blob blob = storage.update(BlobInfo.newBuilder(blobId).setTemporaryHold(true).build());

System.out.println("Temporary hold was set for " + blobName);

Node.js

Para mais informações, consulte a documentação de referência da API Cloud Storage para Node.js.

No exemplo a seguir, uma retenção baseada em evento é definida em um objeto:

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const bucketName = 'Name of a bucket, e.g. my-bucket';
// const filename = 'File to access, e.g. file.txt';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function setEventBasedHold() {
  // Set event-based hold
  await storage.bucket(bucketName).file(fileName).setMetadata({
    eventBasedHold: true,
  });
  console.log(`Event-based hold was set for ${fileName}.`);
}

setEventBasedHold().catch(console.error);

No exemplo a seguir, uma retenção temporária é definida em um objeto:

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const bucketName = 'Name of a bucket, e.g. my-bucket';
// const filename = 'File to access, e.g. file.txt';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function setTemporaryHold() {
  await storage.bucket(bucketName).file(fileName).setMetadata({
    temporaryHold: true,
  });
  console.log(`Temporary hold was set for ${fileName}.`);
}

setTemporaryHold().catch(console.error);

PHP

Para mais informações, consulte a documentação de referência da API Cloud Storage para PHP.

No exemplo a seguir, uma retenção baseada em evento é definida em um objeto:

use Google\Cloud\Storage\StorageClient;

/**
 * Sets an event-based hold for an object.
 *
 * @param string $bucketName the name of your Cloud Storage bucket.
 * @param string $objectName the name of your Cloud Storage object.
 */
function set_event_based_hold($bucketName, $objectName)
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $object = $bucket->object($objectName);
    $object->update(['eventBasedHold' => true]);
    printf('Event-based hold was set for %s' . PHP_EOL, $objectName);
}

No exemplo a seguir, uma retenção temporária é definida em um objeto:

use Google\Cloud\Storage\StorageClient;

/**
 * Sets a temporary hold for an object.
 *
 * @param string $bucketName the name of your Cloud Storage bucket.
 * @param string $objectName the name of your Cloud Storage object.
 */
function set_temporary_hold($bucketName, $objectName)
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $object = $bucket->object($objectName);
    $object->update(['temporaryHold' => true]);
    printf('Temporary hold was set for %s' . PHP_EOL, $objectName);
}

Python

Para mais informações, consulte a documentação de referência da API Cloud Storage para Python.

No exemplo a seguir, uma retenção baseada em evento é definida em um objeto:

from google.cloud import storage

def set_event_based_hold(bucket_name, blob_name):
    """Sets a event based hold on a given blob"""
    # bucket_name = "my-bucket"
    # blob_name = "my-blob"

    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)
    blob = bucket.blob(blob_name)

    blob.event_based_hold = True
    blob.patch()

    print("Event based hold was set for {}".format(blob_name))

No exemplo a seguir, uma retenção temporária é definida em um objeto:

from google.cloud import storage

def set_temporary_hold(bucket_name, blob_name):
    """Sets a temporary hold on a given blob"""
    # bucket_name = "my-bucket"
    # blob_name = "my-blob"

    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)
    blob = bucket.blob(blob_name)

    blob.temporary_hold = True
    blob.patch()

    print("Temporary hold was set for #{blob_name}")

Ruby

Para mais informações, consulte a documentação de referência da API Cloud Storage para Ruby.

No exemplo a seguir, uma retenção baseada em evento é definida em um objeto:

# bucket_name = "Your Google Cloud Storage bucket name"
# file_name   = "Name of a file in the Cloud Storage bucket"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new
bucket  = storage.bucket bucket_name
file    = bucket.file file_name

file.set_event_based_hold!

puts "Event-based hold was set for #{file_name}."

No exemplo a seguir, uma retenção temporária é definida em um objeto:

# bucket_name = "Your Google Cloud Storage bucket name"
# file_name   = "Name of a file in the Cloud Storage bucket"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new
bucket  = storage.bucket bucket_name
file    = bucket.file file_name

file.set_temporary_hold!

puts "Temporary hold was set for #{file_name}."

APIs REST

API JSON

  1. Receba um token de acesso de autorização do OAuth 2.0 Playground. Configure o Playground para usar suas credenciais do OAuth.
  2. Crie um arquivo .json com as informações a seguir:

    {
      "HOLD_TYPE": true
    }

    Em que HOLD_TYPE é o tipo de retenção que você quer aplicar ao seu objeto. Por exemplo, temporaryHold ou eventBasedHold. Consulte Retenções de objetos para saber mais sobre os tipos de retenção.

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

    curl -X PATCH --data-binary @JSON_FILE_NAME.json \
    -H "Authorization: Bearer OAUTH2_TOKEN" \
    -H "Content-Type: application/json" \
    "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME"

    Em que:

    • JSON_FILE_NAME é o nome do arquivo que você criou na etapa 2;
    • OAUTH2_TOKEN é o token de acesso gerado na etapa 1;
    • BUCKET_NAME é o nome do bucket pertinente. Por exemplo, my-bucket.
    • OBJECT_NAME é o nome do objeto relevante. Por exemplo, pets/dog.png.

API XML

A API XML não pode ser usada para trabalhar com retenções de objeto. Use uma das outras ferramentas do Cloud Storage, como o gsutil.

Como conseguir o status de retenção de um objeto

Para ver quais retenções existem em um objeto, se houver alguma, siga as instruções gerais sobre Como ver metadados de objeto.

Como liberar uma retenção de objeto

Para liberar um objeto no seu bucket:

Console

  1. Abra o navegador do Cloud Storage no Console do Google Cloud.
    Abra o navegador do Cloud Storage
  2. Na lista de buckets, clique no nome do bucket que contém os objetos de que você remove retenções.

  3. Marque a caixa de seleção ao lado dos nomes dos objetos de que você quer remover as retenções.

  4. Clique no botão Gerenciar retenções.

    A janela Gerenciar retenções é exibida.

  5. Desmarque a caixa de seleção das retenções que você quer remover.

  6. Clique em Salvar configurações de retenção.

Consulte a Solução de problemas para informações detalhadas sobre erros de operações com falha no navegador do Cloud Storage.

gsutil

Use o comando gsutil retention:

gsutil retention HOLD_TYPE release gs://BUCKET_NAME/OBJECT_NAME

Onde:

  • HOLD_TYPE é o tipo de retenção que você quer liberar do seu objeto. Por exemplo, temp ou event. Consulte Retenções de objetos para saber mais sobre os tipos de retenção.
  • BUCKET_NAME é o nome do bucket pertinente. Por exemplo, my-bucket.
  • OBJECT_NAME é o nome do objeto relevante. Por exemplo, pets/dog.png.

Amostras de código

C++

Para mais informações, consulte a documentação de referência da API Cloud Storage para C++.

No exemplo a seguir, uma retenção baseada em evento é definida em um objeto:

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& object_name) {
  StatusOr<gcs::ObjectMetadata> original =
      client.GetObjectMetadata(bucket_name, object_name);
  if (!original) throw std::runtime_error(original.status().message());

  StatusOr<gcs::ObjectMetadata> updated = client.PatchObject(
      bucket_name, object_name,
      gcs::ObjectMetadataPatchBuilder().SetEventBasedHold(false),
      gcs::IfMetagenerationMatch(original->metageneration()));
  if (!updated) throw std::runtime_error(updated.status().message());

  std::cout << "The event hold for object " << updated->name()
            << " in bucket " << updated->bucket() << " is "
            << (updated->event_based_hold() ? "enabled" : "disabled") << "\n";
}

No exemplo a seguir, uma retenção temporária é definida em um objeto:

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& object_name) {
  StatusOr<gcs::ObjectMetadata> original =
      client.GetObjectMetadata(bucket_name, object_name);

  if (!original) throw std::runtime_error(original.status().message());
  StatusOr<gcs::ObjectMetadata> updated = client.PatchObject(
      bucket_name, object_name,
      gcs::ObjectMetadataPatchBuilder().SetTemporaryHold(false),
      gcs::IfMetagenerationMatch(original->metageneration()));

  if (!updated) throw std::runtime_error(updated.status().message());
  std::cout << "The temporary hold for object " << updated->name()
            << " in bucket " << updated->bucket() << " is "
            << (updated->temporary_hold() ? "enabled" : "disabled") << "\n";
}

C#

Para mais informações, consulte a documentação de referência da API Cloud Storage para C#.

No exemplo a seguir, uma retenção baseada em evento é liberada em um objeto:

private void ReleaseObjectEventBasedHold(string bucketName,
    string objectName)
{
    var storage = StorageClient.Create();
    var storageObject = storage.GetObject(bucketName, objectName);
    storageObject.EventBasedHold = false;
    storageObject = storage.UpdateObject(storageObject, new UpdateObjectOptions()
    {
        // Use IfMetagenerationMatch to avoid race conditions.
        IfMetagenerationMatch = storageObject.Metageneration,
    });
}

No exemplo a seguir, uma retenção temporária é liberada em um objeto:

private void ReleaseObjectTemporaryHold(string bucketName,
    string objectName)
{
    var storage = StorageClient.Create();
    var storageObject = storage.GetObject(bucketName, objectName);
    storageObject.TemporaryHold = false;
    storageObject = storage.UpdateObject(storageObject, new UpdateObjectOptions()
    {
        // Use IfMetagenerationMatch to avoid race conditions.
        IfMetagenerationMatch = storageObject.Metageneration,
    });
}

Go

Para mais informações, consulte a documentação de referência da API Cloud Storage para Go.

No exemplo a seguir, uma retenção baseada em evento é liberada em um objeto:

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/storage"
)

// releaseEventBasedHold releases an object with event-based hold.
func releaseEventBasedHold(w io.Writer, bucket, object string) error {
	// bucket := "bucket-name"
	// object := "object-name"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %v", err)
	}
	defer client.Close()

	ctx, cancel := context.WithTimeout(ctx, time.Second*10)
	defer cancel()

	o := client.Bucket(bucket).Object(object)
	objectAttrsToUpdate := storage.ObjectAttrsToUpdate{
		EventBasedHold: false,
	}
	if _, err := o.Update(ctx, objectAttrsToUpdate); err != nil {
		return fmt.Errorf("Object(%q).Update: %v", object, err)
	}
	fmt.Fprintf(w, "Event based hold was released for %v.\n", object)
	return nil
}

No exemplo a seguir, uma retenção temporária é liberada em um objeto:

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/storage"
)

// releaseTemporaryHold releases an object with temporary hold.
func releaseTemporaryHold(w io.Writer, bucket, object string) error {
	// bucket := "bucket-name"
	// object := "object-name"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %v", err)
	}
	defer client.Close()

	ctx, cancel := context.WithTimeout(ctx, time.Second*10)
	defer cancel()

	o := client.Bucket(bucket).Object(object)
	objectAttrsToUpdate := storage.ObjectAttrsToUpdate{
		TemporaryHold: false,
	}
	if _, err := o.Update(ctx, objectAttrsToUpdate); err != nil {
		return fmt.Errorf("Object(%q).Update: %v", object, err)
	}
	fmt.Fprintf(w, "Temporary hold was released for %v.\n", object)
	return nil
}

Java

Para mais informações, consulte a documentação de referência da API Cloud Storage para Java.

No exemplo a seguir, uma retenção baseada em evento é liberada em um objeto:

// Instantiate a Google Cloud Storage client
Storage storage = StorageOptions.getDefaultInstance().getService();

// The name of a bucket, e.g. "my-bucket"
// String bucketName = "my-bucket";

// The name of a blob, e.g. "my-blob"
// String blobName = "my-blob";

BlobId blobId = BlobId.of(bucketName, blobName);
Blob blob = storage.update(BlobInfo.newBuilder(blobId).setEventBasedHold(false).build());

System.out.println("Event-based hold was released for " + blobName);

No exemplo a seguir, uma retenção temporária é liberada em um objeto:

// Instantiate a Google Cloud Storage client
Storage storage = StorageOptions.getDefaultInstance().getService();

// The name of a bucket, e.g. "my-bucket"
// String bucketName = "my-bucket";

// The name of a blob, e.g. "my-blob"
// String blobName = "my-blob";

BlobId blobId = BlobId.of(bucketName, blobName);
Blob blob = storage.update(BlobInfo.newBuilder(blobId).setTemporaryHold(false).build());

System.out.println("Temporary hold was released for " + blobName);

Node.js

Para mais informações, consulte a documentação de referência da API Cloud Storage para Node.js.

No exemplo a seguir, uma retenção baseada em evento é liberada em um objeto:

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const bucketName = 'Name of a bucket, e.g. my-bucket';
// const filename = 'File to access, e.g. file.txt';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function releaseEventBasedHold() {
  await storage.bucket(bucketName).file(fileName).setMetadata({
    eventBasedHold: false,
  });
  console.log(`Event-based hold was released for ${fileName}.`);
}

releaseEventBasedHold().catch(console.error);

No exemplo a seguir, uma retenção temporária é liberada em um objeto:

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const bucketName = 'Name of a bucket, e.g. my-bucket';
// const filename = 'File to access, e.g. file.txt';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function releaseTemporaryHold() {
  await storage.bucket(bucketName).file(fileName).setMetadata({
    temporaryHold: false,
  });
  console.log(`Temporary hold was released for ${fileName}.`);
}

releaseTemporaryHold().catch(console.error);

PHP

Para mais informações, consulte a documentação de referência da API Cloud Storage para PHP.

No exemplo a seguir, uma retenção baseada em evento é liberada em um objeto:

use Google\Cloud\Storage\StorageClient;

/**
 * Releases an event-based hold for an object.
 *
 * @param string $bucketName the name of your Cloud Storage bucket.
 * @param string $objectName the name of your Cloud Storage object.
 */
function release_event_based_hold($bucketName, $objectName)
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $object = $bucket->object($objectName);
    $object->update(['eventBasedHold' => false]);
    printf('Event-based hold was released for %s' . PHP_EOL, $objectName);
}

No exemplo a seguir, uma retenção temporária é liberada em um objeto:

use Google\Cloud\Storage\StorageClient;

/**
 * Releases a temporary hold for an object.
 *
 * @param string $bucketName the name of your Cloud Storage bucket.
 * @param string $objectName the name of your Cloud Storage object.
 */
function release_temporary_hold($bucketName, $objectName)
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $object = $bucket->object($objectName);
    $object->update(['temporaryHold' => false]);
    printf('Temporary hold was released for %s' . PHP_EOL, $objectName);
}

Python

Para mais informações, consulte a documentação de referência da API Cloud Storage para Python.

No exemplo a seguir, uma retenção baseada em evento é liberada em um objeto:

from google.cloud import storage

def release_event_based_hold(bucket_name, blob_name):
    """Releases the event based hold on a given blob"""

    # bucket_name = "my-bucket"
    # blob_name = "my-blob"

    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)
    blob = bucket.blob(blob_name)

    blob.event_based_hold = False
    blob.patch()

    print("Event based hold was released for {}".format(blob_name))

No exemplo a seguir, uma retenção temporária é liberada em um objeto:

from google.cloud import storage

def release_temporary_hold(bucket_name, blob_name):
    """Releases the temporary hold on a given blob"""

    # bucket_name = "my-bucket"
    # blob_name = "my-blob"

    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)
    blob = bucket.blob(blob_name)

    blob.temporary_hold = False
    blob.patch()

    print("Temporary hold was release for #{blob_name}")

Ruby

Para mais informações, consulte a documentação de referência da API Cloud Storage para Ruby.

No exemplo a seguir, uma retenção baseada em evento é liberada em um objeto:

# bucket_name = "Your Google Cloud Storage bucket name"
# file_name   = "Name of a file in the Cloud Storage bucket"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new
bucket  = storage.bucket bucket_name
file    = bucket.file file_name

file.release_event_based_hold!

puts "Event-based hold was released for #{file_name}."

No exemplo a seguir, uma retenção temporária é liberada em um objeto:

# bucket_name = "Your Google Cloud Storage bucket name"
# file_name   = "Name of a file in the Cloud Storage bucket"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new
bucket  = storage.bucket bucket_name
file    = bucket.file file_name

file.release_temporary_hold!

puts "Temporary hold was released for #{file_name}."

APIs REST

API JSON

  1. Receba um token de acesso de autorização do OAuth 2.0 Playground. Configure o Playground para usar suas credenciais do OAuth.
  2. Crie um arquivo .json com as informações a seguir:

    {
      "HOLD_TYPE": false
    }

    Em que HOLD_TYPE é o tipo de retenção que você quer liberar do seu objeto. Por exemplo, temporaryHold ou eventBasedHold. Consulte Retenções de objetos para saber mais sobre os tipos de retenção.

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

    curl -X PATCH --data-binary @JSON_FILE_NAME.json \
    -H "Authorization: Bearer OAUTH2_TOKEN" \
    -H "Content-Type: application/json" \
    "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME"

    Em que:

    • JSON_FILE_NAME é o nome do arquivo que você criou na etapa 2.
    • OAUTH2_TOKEN é o token de acesso gerado na etapa 1;
    • BUCKET_NAME é o nome do bucket pertinente. Por exemplo, my-bucket.
    • OBJECT_NAME é o nome do objeto relevante. Por exemplo, pets/dog.png.

API XML

A API XML não pode ser usada para trabalhar com retenções de objeto. Use uma das outras ferramentas do Cloud Storage, como o gsutil.

A seguir