Usar o Controle de versões de objetos

Visão geral Uso

Nesta página, você verá como ativar, desativar e verificar o status do Controle de versões de objeto em um bucket. Consulte Como trabalhar com objetos com controle de versão para saber como listar, restaurar e excluir objetos retidos pelo Controle de versão de objeto.

Importante: não há limite padrão para o número de versões de objetos que você pode ter. Cada versão não atual de um objeto custa o mesmo que a versão ativa do objeto. Se você ativar o controle de versões, pense em usar o Gerenciamento do ciclo de vida de objetos, que pode remover as versões mais antigas de um objeto conforme as versões mais recentes se tornam não atuais.

Funções exigidas

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

Permissões necessárias

• storage.buckets.get
• storage.buckets.update
• storage.buckets.list
  • Essa permissão só é necessária ao usar o console do Google Cloud para executar as instruções nesta página.

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

Para informações sobre como conceder papéis nos buckets, consulte Usar o IAM com buckets. Para informações sobre como conceder papéis em projetos, consulte Gerenciar acesso a projetos.

Definir o controle de versão de objeto em um bucket

Observação: o controle de versão de objeto não pode ser ativado em um bucket que atualmente tem uma política de retenção.

Console

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

   Acessar buckets

2. Na lista de buckets, clique no nome daquele em que você quer ativar ou desativar o controle de versões de objetos.

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

   O status atual do controle de versões de objeto está na seção Controle de versões de objeto.

4. Na seção Controle de versões de objeto, clique no status atual para fazer alterações.

   A caixa de diálogo Controle de versões de objetos é exibida.

   1. Se você estiver ativando o controle de versões de objeto e quiser minimizar os custos de armazenamento, marque a caixa de seleção Adicionar regras de ciclo de vida recomendadas para gerenciar custos de versão.

5. Clique em Confirmar.

Linha de comando

Use o comando gcloud storage buckets update com a flag apropriada:

gcloud storage buckets update gs://BUCKET_NAME FLAG

Em que:

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

• FLAG é --versioning para ativar o controle de versão de objeto ou --no-versioning para desativá-lo.

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

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

Bibliotecas de cliente

C++

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

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

O exemplo a seguir ativa o controle de versão de objeto em um bucket:

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::move(original).status();

  StatusOr<gcs::BucketMetadata> patched = client.PatchBucket(
      bucket_name,
      gcs::BucketMetadataPatchBuilder().SetVersioning(
          gcs::BucketVersioning{true}),
      gcs::IfMetagenerationMatch(original->metageneration()));
  if (!patched) throw std::move(patched).status();

  if (patched->versioning().has_value()) {
    std::cout << "Object versioning for bucket " << bucket_name << " is "
              << (patched->versioning()->enabled ? "enabled" : "disabled")
              << "\n";
  } else {
    std::cout << "Object versioning for bucket " << bucket_name
              << " is disabled.\n";
  }
}

A amostra a seguir mostra como desativar o controle de versão de objeto em um bucket:

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::move(original).status();

  StatusOr<gcs::BucketMetadata> patched = client.PatchBucket(
      bucket_name,
      gcs::BucketMetadataPatchBuilder().SetVersioning(
          gcs::BucketVersioning{false}),
      gcs::IfMetagenerationMatch(original->metageneration()));
  if (!patched) throw std::move(patched).status();

  auto versioning =
      patched->versioning().value_or(gcs::BucketVersioning{false});
  std::cout << "Object versioning for bucket " << bucket_name << " is "
            << (versioning.enabled ? "enabled" : "disabled") << "\n";
}

C#

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

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

O exemplo a seguir ativa o controle de versão de objeto em um bucket:

using Google.Apis.Storage.v1.Data;
using Google.Cloud.Storage.V1;
using System;

public class BucketEnableVersioningSample
{
	public Bucket BucketEnableVersioning(string bucketName = "your-bucket-name")
	{
		var storage = StorageClient.Create();
		var bucket = storage.GetBucket(bucketName);

		if (bucket.Versioning == null)
		{
			bucket.Versioning = new Bucket.VersioningData();
		}
		bucket.Versioning.Enabled = true;

		bucket = storage.UpdateBucket(bucket);
		Console.WriteLine($"Versioning is now enabled for bucket {bucketName}.");
		return bucket;
	}
}

A amostra a seguir mostra como desativar o controle de versão de objeto em um bucket:

using Google.Apis.Storage.v1.Data;
using Google.Cloud.Storage.V1;
using System;

public class BucketDisableVersioningSample
{
	public Bucket BucketDisableVersioning(string bucketName = "your-bucket-name")
	{
		var storage = StorageClient.Create();
		var bucket = storage.GetBucket(bucketName);

		if (bucket.Versioning?.Enabled != true)
		{
			Console.WriteLine($"Versioning already disabled for bucket {bucketName}.");
		}
		else
		{
        	    bucket.Versioning.Enabled = false;

		    bucket = storage.UpdateBucket(bucket);
                    Console.WriteLine($"Versioning is now disabled for bucket {bucketName}.");
                }
		return bucket;
	}
}

Go

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

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

O exemplo a seguir ativa o controle de versão de objeto em um bucket:

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

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

// enableVersioning enables object versioning on a bucket.
func enableVersioning(w io.Writer, bucketName string) error {
	// bucketName := "bucket-name"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %w", err)
	}
	defer client.Close()

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

	bucket := client.Bucket(bucketName)
	bucketAttrsToUpdate := storage.BucketAttrsToUpdate{
		VersioningEnabled: true,
	}
	if _, err := bucket.Update(ctx, bucketAttrsToUpdate); err != nil {
		return fmt.Errorf("Bucket(%q).Update: %w", bucketName, err)
	}
	fmt.Fprintf(w, "Versioning was enabled for %v\n", bucketName)
	return nil
}

A amostra a seguir mostra como desativar o controle de versão de objeto em um bucket:

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

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

// disableVersioning disables object versioning on a bucket.
func disableVersioning(w io.Writer, bucketName string) error {
	// bucketName := "bucket-name"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %w", err)
	}
	defer client.Close()

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

	bucket := client.Bucket(bucketName)
	bucketAttrsToUpdate := storage.BucketAttrsToUpdate{
		VersioningEnabled: false,
	}
	if _, err := bucket.Update(ctx, bucketAttrsToUpdate); err != nil {
		return fmt.Errorf("Bucket(%q).Update: %w", bucketName, err)
	}
	fmt.Fprintf(w, "Versioning was disabled for %v\n", bucketName)
	return nil
}

Java

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

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

O exemplo a seguir ativa o controle de versão de objeto em um bucket:

import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class EnableBucketVersioning {
  public static void enableBucketVersioning(String projectId, String bucketName) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    Bucket bucket = storage.get(bucketName);
    bucket.toBuilder().setVersioningEnabled(true).build().update();

    System.out.println("Versioning is now enabled for bucket " + bucketName);
  }
}

A amostra a seguir mostra como desativar o controle de versão de objeto em um bucket:

import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class DisableBucketVersioning {
  public static void disableBucketVersioning(String projectId, String bucketName) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    Bucket bucket = storage.get(bucketName);
    bucket.toBuilder().setVersioningEnabled(false).build().update();

    System.out.println("Versioning is now disabled for bucket " + bucketName);
  }
}

Node.js

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

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

O exemplo a seguir ativa o controle de versão de objeto em um bucket:

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

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

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

async function enableBucketVersioning() {
  await storage.bucket(bucketName).setMetadata({
    versioning: {
      enabled: true,
    },
  });

  console.log(`Versioning is enabled for bucket ${bucketName}`);
}

enableBucketVersioning().catch(console.error);

A amostra a seguir mostra como desativar o controle de versão de objeto em um bucket:

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

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

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

async function disableBucketVersioning() {
  await storage.bucket(bucketName).setMetadata({
    versioning: {
      enabled: false,
    },
  });

  console.log(`Versioning is disabled for bucket ${bucketName}`);
}

disableBucketVersioning().catch(console.error);

PHP

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

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

O exemplo a seguir ativa o controle de versão de objeto em um bucket:

use Google\Cloud\Storage\StorageClient;

/**
 * Enable versioning on the specified bucket.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 */
function enable_versioning(string $bucketName): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $bucket->update([
        'versioning' => [
            'enabled' => true,
        ]
    ]);

    printf('Versioning is now enabled for bucket %s', $bucketName);
}

A amostra a seguir mostra como desativar o controle de versão de objeto em um bucket:

use Google\Cloud\Storage\StorageClient;

/**
 * Disable versioning of the given bucket.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 */
function disable_versioning(string $bucketName): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $bucket->update([
        'versioning' => [
            'enabled' => false,
        ]
    ]);

    printf('Versioning is now disabled for bucket %s', $bucketName);
}

Python

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

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

O exemplo a seguir ativa o controle de versão de objeto em um bucket:

from google.cloud import storage


def enable_versioning(bucket_name):
    """Enable versioning for this bucket."""
    # bucket_name = "my-bucket"

    storage_client = storage.Client()

    bucket = storage_client.get_bucket(bucket_name)
    bucket.versioning_enabled = True
    bucket.patch()

    print(f"Versioning was enabled for bucket {bucket.name}")
    return bucket

A amostra a seguir mostra como desativar o controle de versão de objeto em um bucket:

from google.cloud import storage


def disable_versioning(bucket_name):
    """Disable versioning for this bucket."""
    # bucket_name = "my-bucket"

    storage_client = storage.Client()

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

    print(f"Versioning was disabled for bucket {bucket}")
    return bucket

Ruby

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

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

O exemplo a seguir ativa o controle de versão de objeto em um bucket:

def enable_versioning bucket_name:
  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  require "google/cloud/storage"

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

  bucket.versioning = true

  puts "Versioning was enabled for bucket #{bucket_name}"
end

A amostra a seguir mostra como desativar o controle de versão de objeto em um bucket:

def disable_versioning bucket_name:
  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  require "google/cloud/storage"

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

  bucket.versioning = false

  puts "Versioning was disabled for bucket #{bucket_name}"
end

APIs REST

API JSON

1. Ter a gcloud CLI instalada e inicializadapara gerar um token de acesso para o cabeçalho Authorization.

   Como alternativa, é possível criar um token de acesso usando o OAuth 2.0 Playground e incluí-lo no cabeçalho Authorization.

2. Crie um arquivo JSON com as informações a seguir:

   {
     "versioning": {
       "enabled": STATE
     }
   }

   Em que STATE é true ou false.

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

   curl -X PATCH --data-binary @JSON_FILE_NAME \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=versioning"

   Em que:

   • JSON_FILE_NAME é o caminho para o arquivo JSON criado na Etapa 2.
   • BUCKET_NAME é o nome do bucket pertinente. Por exemplo, my-bucket.

API XML

1. Ter a gcloud CLI instalada e inicializadapara gerar um token de acesso para o cabeçalho Authorization.

   Como alternativa, é possível criar um token de acesso usando o OAuth 2.0 Playground e incluí-lo no cabeçalho Authorization.

2. Crie um arquivo XML que contenha as seguintes informações:

   <VersioningConfiguration>
     <Status>STATE</Status>
   </VersioningConfiguration>

   Em que STATE é Enabled ou Suspended.

3. Use cURL para chamar a API XML com uma solicitação de bucket PUT e um parâmetro de string de consulta versioning:

   curl -X PUT --data-binary @XML_FILE_NAME \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://storage.googleapis.com/BUCKET_NAME?versioning"

   Em que:

   • XML_FILE_NAME é o caminho para o arquivo XML criado na Etapa 2.
   • BUCKET_NAME é o nome do bucket pertinente. Por exemplo, my-bucket.

Depois que o controle de versão de objeto é ativado, sempre que uma versão de objeto ativa é substituída ou excluída, ela se torna não atual.

Verificar se o controle de versão de objeto está ativado

Para verificar se o Controle de versão de objeto está ativado em um bucket:

Console

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

   Acessar buckets

2. Na lista de buckets, o status do controle de versões de objeto de cada bucket está na coluna Proteção.

Se ativado, o texto Controle de versões de objeto é exibido.

Linha de comando

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

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

Em que BUCKET_NAME é o nome do bucket com o status que você quer visualizar. Por exemplo, my-bucket.

Se for bem-sucedido e o controle de versões de objetos estiver ativado, a resposta será semelhante a este exemplo:

versioning:
  enabled: true

Se for bem-sucedido e o controle de versões de objetos não estiver ativado, a resposta será semelhante ao exemplo a seguir:

null

APIs REST

API JSON

1. Ter a gcloud CLI instalada e inicializadapara gerar um token de acesso para o cabeçalho Authorization.

   Como alternativa, é possível criar um token de acesso usando o OAuth 2.0 Playground e incluí-lo no cabeçalho Authorization.

2. Use cURL para chamar a API JSON com uma solicitação bucket GET:

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

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

Se for bem-sucedido e o controle de versões de objetos estiver ativado, a resposta será semelhante a este exemplo:

{
  "versioning": {
    "enabled": true
  }
}

Se for bem-sucedido e o controle de versões de objetos não estiver ativado, a resposta será semelhante ao exemplo a seguir:

{}

API XML

1. Ter a gcloud CLI instalada e inicializadapara gerar um token de acesso para o cabeçalho Authorization.

   Como alternativa, é possível criar um token de acesso usando o OAuth 2.0 Playground e incluí-lo no cabeçalho Authorization.

2. Use cURL para chamar a API XML com uma solicitação de bucket GET e um parâmetro de string de consulta versioning:

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

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

Se for bem-sucedido e o controle de versões de objetos estiver ativado, a resposta será semelhante a este exemplo:

<VersioningConfiguration>
  <Status>Enabled</Status>
</VersioningConfiguration>

Se for bem-sucedido e o controle de versões de objetos não estiver ativado, a resposta será semelhante ao exemplo a seguir:

<VersioningConfiguration/>

A seguir

• Saiba mais sobre como controlar versões de objetos.
• Saiba como trabalhar com objetos não atuais.
• Saiba como usar o Gerenciamento do ciclo de vida de objetos para gerenciar automaticamente as versões de objetos.
• Saiba como usar pré-condições de solicitação para evitar disputas.