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

Para usar esse recurso no Cloud Storage, o seguinte é necessário:

  1. Ter permissão suficiente para ver e atualizar intervalos e objetos no Cloud Storage:

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

    • Para usar o IAM, é necessário ter storage.buckets.update, storage.buckets.get, storage.objects.update e permissões storage.objects.get do intervalo pertinente. Consulte Como usar permissões do IAM para instruções sobre como conseguir um papel, por exemplo, roles/storage.admin, com essas permissões.

    • Se você usar ACLs, precisará da permissão PROPRIETÁRIO no intervalo em questão e nos objetos dentro dele. Consulte Como configurar ACLs para 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 intervalo. Quando essa propriedade é ativada, novos objetos adicionados ao intervalo recebem automaticamente uma retenção baseada em evento.

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

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

Console

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

  3. Selecione a guia Bloqueio de intervalo 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 intervalo pertinente. Por exemplo, my-bucket.

Amostras de código

C++

Para saber mais, consulte a documentação de referência da API Cloud Storage 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 saber mais, consulte a documentação de referência da API Cloud Storage 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 saber mais, consulte a documentação de referência da API Cloud Storage Go .

bucket := c.Bucket(bucketName)
bucketAttrsToUpdate := storage.BucketAttrsToUpdate{
	DefaultEventBasedHold: true,
}
if _, err := bucket.Update(ctx, bucketAttrsToUpdate); err != nil {
	return err
}

Java

Para saber mais, consulte a documentação de referência da API Cloud Storage 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 saber mais, consulte a documentação de referência da API Cloud Storage Node.js .

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

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

/**
 * 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.
await storage.bucket(bucketName).setMetadata({
  defaultEventBasedHold: true,
});

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

PHP

Para saber mais, consulte a documentação de referência da API Cloud Storage 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 saber mais, consulte a documentação de referência da API Cloud Storage para Python .

# 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 saber mais, consulte a documentação de referência da API Cloud Storage Ruby .

# project_id  = "Your Google Cloud project ID"
# bucket_name = "Name of your Google Cloud Storage bucket"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new project_id: project_id
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 API com uma PATCH solicitação de Intervalo:

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

    em que:

    • [JSON_FILE_NAME] é o nome do arquivo criado na Etapa 2.
    • [OAUTH2_TOKEN] é o token de acesso gerado na Etapa 1;
    • [BUCKET_NAME] é o nome do intervalo 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 intervalo

Para verificar se um intervalo 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 Platform.
    Abra o navegador do Cloud Storage
  2. Na lista de intervalos, clique no nome do intervalo para o qual você quer verificar o status baseado em eventos padrão.

  3. Selecione a guia Bloqueio de intervalo 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 intervalo 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 saber mais, consulte a documentação de referência da API Cloud Storage 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 saber mais, consulte a documentação de referência da API Cloud Storage 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 saber mais, consulte a documentação de referência da API Cloud Storage Go .

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 saber mais, consulte a documentação de referência da API Cloud Storage 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 saber mais, consulte a documentação de referência da API Cloud Storage Node.js .

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

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

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

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

PHP

Para saber mais, consulte a documentação de referência da API Cloud Storage 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 saber mais, consulte a documentação de referência da API Cloud Storage para Python .

# bucket_name = "my-bucket"

storage_client = storage.Client()
bucket = storage_client.bucket(bucket_name)
bucket.reload()

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 saber mais, consulte a documentação de referência da API Cloud Storage Ruby .

# project_id  = "Your Google Cloud project ID"
# bucket_name = "Name of your Google Cloud Storage bucket"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new project_id: project_id
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 Intervalo que inclui os fields desejados:

    curl -X GET -H "Authorization: Bearer [OAUTH2_TOKEN]" \
    "https://www.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 intervalo pertinente. Por exemplo, my-bucket.

    Se o intervalo 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 intervalo:

Console

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

  3. Selecione a guia Bloqueio de intervalo 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 intervalo pertinente. Por exemplo, my-bucket.

Amostras de código

C++

Para saber mais, consulte a documentação de referência da API Cloud Storage 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 saber mais, consulte a documentação de referência da API Cloud Storage 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 saber mais, consulte a documentação de referência da API Cloud Storage Go .

bucket := c.Bucket(bucketName)
bucketAttrsToUpdate := storage.BucketAttrsToUpdate{
	DefaultEventBasedHold: false,
}
if _, err := bucket.Update(ctx, bucketAttrsToUpdate); err != nil {
	return err
}

Java

Para saber mais, consulte a documentação de referência da API Cloud Storage 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 saber mais, consulte a documentação de referência da API Cloud Storage Node.js .

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

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

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

// 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}.`);

PHP

Para saber mais, consulte a documentação de referência da API Cloud Storage 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 saber mais, consulte a documentação de referência da API Cloud Storage para Python .

# bucket_name = "my-bucket"

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

bucket.default_event_based_hold = False
bucket.patch()

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

Ruby

Para saber mais, consulte a documentação de referência da API Cloud Storage Ruby .

# project_id  = "Your Google Cloud project ID"
# bucket_name = "Name of your Google Cloud Storage bucket"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new project_id: project_id
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 API com uma PATCH solicitação de Intervalo:

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

    em que:

    • [JSON_FILE_NAME] é o nome do arquivo criado na Etapa 2.
    • [OAUTH2_TOKEN] é o token de acesso gerado na Etapa 1;
    • [BUCKET_NAME] é o nome do intervalo 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 intervalo:

Console

  1. Abra o navegador do Cloud Storage no Console do Google Cloud Platform.
    Abra o navegador do Cloud Storage
  2. Na lista de intervalos, clique no nome do intervalo 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 intervalo pertinente. Por exemplo, my-bucket.
  • [OBJECT_NAME] é o nome do objeto pertinente. Por exemplo, pets/dog.png.

Amostras de código

C++

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

A amostra a seguir define uma retenção baseada em evento 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";
}

A amostra a seguir define uma retenção temporária 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 saber mais, consulte a documentação de referência da API Cloud Storage C# .

A amostra a seguir define uma retenção baseada em evento 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
    });
}

A amostra a seguir define uma retenção temporária 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 saber mais, consulte a documentação de referência da API Cloud Storage Go .

A amostra a seguir define uma retenção baseada em evento em um objeto:

o := client.Bucket(bucket).Object(object)
objectAttrsToUpdate := storage.ObjectAttrsToUpdate{
	EventBasedHold: true,
}
if _, err := o.Update(ctx, objectAttrsToUpdate); err != nil {
	return err
}

A amostra a seguir define uma retenção temporária em um objeto:

o := client.Bucket(bucket).Object(object)
objectAttrsToUpdate := storage.ObjectAttrsToUpdate{
	TemporaryHold: true,
}
if _, err := o.Update(ctx, objectAttrsToUpdate); err != nil {
	return err
}

Java

Para saber mais, consulte a documentação de referência da API Cloud Storage Java .

A amostra a seguir define uma retenção baseada em evento 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);

A amostra a seguir define uma retenção temporária 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 saber mais, consulte a documentação de referência da API Cloud Storage Node.js .

A amostra a seguir define uma retenção baseada em evento em um objeto:

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

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

/**
 * 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';

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

A amostra a seguir define uma retenção temporária em um objeto:

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

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

/**
 * 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';

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

PHP

Para saber mais, consulte a documentação de referência da API Cloud Storage PHP .

A amostra a seguir define uma retenção baseada em evento 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);
}

A amostra a seguir define uma retenção temporária 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 saber mais, consulte a documentação de referência da API Cloud Storage para Python .

A amostra a seguir define uma retenção baseada em evento em um objeto:

# 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))

A amostra a seguir define uma retenção temporária em um objeto:

# 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 saber mais, consulte a documentação de referência da API Cloud Storage Ruby .

A amostra a seguir define uma retenção baseada em evento em um objeto:

# project_id  = "Your Google Cloud project ID"
# 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 project_id: project_id
bucket  = storage.bucket bucket_name
file    = bucket.file file_name

file.set_event_based_hold!

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

A amostra a seguir define uma retenção temporária em um objeto:

# project_id  = "Your Google Cloud project ID"
# 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 project_id: project_id
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://www.googleapis.com/storage/v1/b/[BUCKET_NAME]/o/[OBJECT_NAME]"

    em que:

    • [JSON_FILE_NAME] é o nome do arquivo criado na Etapa 2.
    • [OAUTH2_TOKEN] é o token de acesso gerado na Etapa 1;
    • [BUCKET_NAME] é o nome do intervalo 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 a retenção de um objeto no seu intervalo:

Console

  1. Abra o navegador do Cloud Storage no Console do Google Cloud Platform.
    Abra o navegador do Cloud Storage
  2. Na lista de intervalos, clique no nome do intervalo 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 intervalo pertinente. Por exemplo, my-bucket.
  • [OBJECT_NAME] é o nome do objeto pertinente. Por exemplo, pets/dog.png.

Amostras de código

C++

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

A amostra a seguir define uma retenção baseada em evento 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";
}

A amostra a seguir define uma retenção temporária 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 saber mais, consulte a documentação de referência da API Cloud Storage C# .

A amostra a seguir libera uma retenção baseada em evento 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,
    });
}

O exemplo a seguir libera uma retenção temporária 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 saber mais, consulte a documentação de referência da API Cloud Storage Go .

A amostra a seguir libera uma retenção baseada em evento em um objeto:

o := client.Bucket(bucket).Object(object)
objectAttrsToUpdate := storage.ObjectAttrsToUpdate{
	EventBasedHold: false,
}
if _, err := o.Update(ctx, objectAttrsToUpdate); err != nil {
	return err
}

O exemplo a seguir libera uma retenção temporária em um objeto:

o := client.Bucket(bucket).Object(object)
objectAttrsToUpdate := storage.ObjectAttrsToUpdate{
	TemporaryHold: false,
}
if _, err := o.Update(ctx, objectAttrsToUpdate); err != nil {
	return err
}

Java

Para saber mais, consulte a documentação de referência da API Cloud Storage Java .

A amostra a seguir libera uma retenção baseada em evento 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);

O exemplo a seguir libera uma retenção temporária 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 saber mais, consulte a documentação de referência da API Cloud Storage Node.js .

A amostra a seguir libera uma retenção baseada em evento em um objeto:

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

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

/**
 * 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';

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

O exemplo a seguir libera uma retenção temporária em um objeto:

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

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

/**
 * 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';

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

PHP

Para saber mais, consulte a documentação de referência da API Cloud Storage PHP .

A amostra a seguir libera uma retenção baseada em evento 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);
}

O exemplo a seguir libera uma retenção temporária 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 saber mais, consulte a documentação de referência da API Cloud Storage para Python .

A amostra a seguir libera uma retenção baseada em evento em um objeto:

# 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))

O exemplo a seguir libera uma retenção temporária em um objeto:

# 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 saber mais, consulte a documentação de referência da API Cloud Storage Ruby .

A amostra a seguir libera uma retenção baseada em evento em um objeto:

# project_id  = "Your Google Cloud project ID"
# 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 project_id: project_id
bucket  = storage.bucket bucket_name
file    = bucket.file file_name

file.release_event_based_hold!

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

O exemplo a seguir libera uma retenção temporária em um objeto:

# project_id  = "Your Google Cloud project ID"
# 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 project_id: project_id
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://www.googleapis.com/storage/v1/b/[BUCKET_NAME]/o/[OBJECT_NAME]"

    em que:

    • [JSON_FILE_NAME] é o nome do arquivo criado na Etapa 2.
    • [OAUTH2_TOKEN] é o token de acesso gerado na Etapa 1;
    • [BUCKET_NAME] é o nome do intervalo 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

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Precisa de ajuda? Acesse nossa página de suporte.