Como usar retenções de objeto

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. Para detalhes sobre esse recurso, incluindo os tipos de retenção que podem ser colocados em objetos, consulte Retenções de objeto.

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, ver 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 Bloqueio de bucket no topo da página.

  4. Na entrada Retenções baseadas em eventos por padrão, clique no botão Desativadas.

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

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string 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.

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


/**
 * 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.

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 Bloqueio de bucket no topo da página.

  4. O status aparece na entrada retenções baseadas em eventos por padrão.

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://[BUCKET_NAME]/ :
  Storage class:         STANDARD
  ...
  ...
  Default Event-Based Hold: On
  ...

Amostras de código

C++

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

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string 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.

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

/**
 * 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.

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 relevante. 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 Bloqueio de bucket no topo da página.

  4. Na entrada retenções baseadas em eventos por padrão, clique no botão Ativadas.

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

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string 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.

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

/**
 * 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.

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, exibir 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.

gsutil

Use o comando gsutil retention:

gsutil retention [HOLD_TYPE] set gs://[BUCKET_NAME]/[OBJECT_NAME]

Em que:

  • [HOLD_TYPE] é o tipo de retenção que você quer aplicar ao seu objeto. Por exemplo, temp ouevent. 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++.

Na amostra a seguir, uma retenção baseada em evento será configurada em um objeto:

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string bucket_name, std::string 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";
}

Na amostra a seguir, uma retenção temporária será configurada em um objeto:

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string bucket_name, std::string 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#.

Na amostra a seguir, uma retenção baseada em evento será configurada 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
    });
}

Na amostra a seguir, uma retenção temporária será configurada 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.

Na amostra a seguir, uma retenção baseada em evento será configurada em um objeto:

ctx := context.Background()

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 err
}

Na amostra a seguir, uma retenção temporária será configurada em um objeto:

ctx := context.Background()

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 err
}

Java

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

Na amostra a seguir, uma retenção baseada em evento será configurada 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);

Na amostra a seguir, uma retenção temporária será configurada 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.

Na amostra a seguir, uma retenção baseada em evento será configurada 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);

Na amostra a seguir, uma retenção temporária será configurada 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 setTemporarydHold() {
  await storage.bucket(bucketName).file(fileName).setMetadata({
    temporaryHold: true,
  });
  console.log(`Temporary hold was set for ${fileName}.`);
}

setTemporarydHold().catch(console.error);

PHP

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

Na amostra a seguir, uma retenção baseada em evento será configurada 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);
}

Na amostra a seguir, uma retenção temporária será configurada 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.

Na amostra a seguir, uma retenção baseada em evento será configurada 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))

Na amostra a seguir, uma retenção temporária será configurada 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.

Na amostra a seguir, uma retenção baseada em evento será configurada 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}."

Na amostra a seguir, uma retenção temporária será configurada 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
    }

    Onde [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 pertinente. 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.

gsutil

Use o comando gsutil retention:

gsutil retention [HOLD_TYPE] release gs://[BUCKET_NAME]/[OBJECT_NAME]

Em que:

  • [HOLD_TYPE] é o tipo de retenção que você quer liberar a partir do seu objeto. Por exemplo, temp ouevent. 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++.

Na amostra a seguir, uma retenção baseada em evento será configurada em um objeto:

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string bucket_name, std::string 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";
}

Na amostra a seguir, uma retenção temporária será configurada em um objeto:

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string bucket_name, std::string 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#.

Na amostra 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,
    });
}

Na amostra 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.

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

ctx := context.Background()

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 err
}

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

ctx := context.Background()

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 err
}

Java

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

Na amostra 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);

Na amostra 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.

Na amostra 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);

Na amostra 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.

Na amostra 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);
}

Na amostra 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.

Na amostra 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))

Na amostra 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.

Na amostra 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}."

Na amostra 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
    }

    Onde [HOLD_TYPE] é o tipo de retenção que você quer liberar a partir do seu objeto. Por exemplo, temporaryHold oueventBasedHold. 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 pertinente. 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