Usar objetos com controle de versão

Visão geral Configuração

Nesta página, você verá como listar, acessar, restaurar e excluir objetos não atuais, que normalmente se aplicam a buckets com o Controle de versões de objetos ativado. Os objetos não atuais também são chamados de objetos com controle de versões.

Antes de começar

Para trabalhar com objetos não atuais, siga estas etapas de pré-requisito.

Ativar o controle de versão de objetos

Se você ainda não tiver feito isso, ative o controle de versões de objetos no seu bucket.

Acessar os papéis necessários

Para receber as permissões necessárias para gerenciar objetos não atuais, peça ao administrador para conceder a você o papel do IAM de Usuário do objeto do Storage (roles/storage.objectUser) no projeto. Esse papel predefinido contém as permissões necessárias para gerenciar objetos não atuais. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

• storage.objects.create
• storage.objects.delete
• storage.objects.get
• storage.objects.list

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

Para informações sobre como conceder papéis em projetos, consulte Gerenciar acesso a projetos.

Dependendo do caso de uso, serão necessárias permissões adicionais ou papéis alternativos:

• Se você planeja usar o console Google Cloud para executar as tarefas nesta página, também precisará da permissão storage.buckets.list, que não está incluída no papel de Usuário de objetos do Storage (roles/storage.objectUser). Para receber essa permissão, peça ao administrador para conceder a você o papel de Administrador do Storage (roles/storage.admin) no projeto.

• Se o acesso uniforme no nível do bucket estiver desativado para seu bucket, serão necessárias outras permissões nos seguintes cenários:

  • Se você planeja retornar objetos não atuais com as ACLs deles, também precisará da permissão storage.objects.getIamPolicy, que não está incluída no papel Usuário do objeto do Storage (roles/storage.objectUser). Para receber essa permissão, peça ao administrador para conceder a você o papel de Administrador de objetos do Storage (roles/storage.objectAdmin) no projeto.

  • Se você planeja renomear ou restaurar objetos não atuais que tenham ACLs, também precisará da permissão storage.objects.setIamPolicy, que não está incluída no papel Usuário do objeto do Storage (roles/storage.objectUser). Para receber essa permissão, peça ao administrador para conceder a você o papel de Administrador de objetos do Storage (roles/storage.objectAdmin) no projeto.

Listar versões de objetos não atuais

Para listar versões ativas e não atuais de objetos e visualizar osgeneration números deles:

Console

Observação :o console do Google Cloud tem um limite de 1.000 versões de um objeto que pode ser listado. Para consultar mais versões de um objeto, use a gcloud CLI.

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 que contém o objeto desejado.

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

3. Para visualizar objetos não atuais, clique no menu suspenso Mostrar e selecione Objetos ativos e não atuais.

4. Na lista de objetos, clique no nome do objeto cujas versões você quer ver.

   A página Detalhes do objeto é aberta com a guia Objeto ativo selecionada.

5. Clique na guia Histórico de versões para ver todas as versões do objeto.

Linha de comando

Use o comando gcloud storage ls --all-versions:

gcloud storage ls --all-versions gs://BUCKET_NAME

Em que BUCKET_NAME é o nome do bucket que contém os objetos. Por exemplo, my-bucket.

A resposta terá esta aparência:

gs://BUCKET_NAME/OBJECT_NAME1#GENERATION_NUMBER1
gs://BUCKET_NAME/OBJECT_NAME2#GENERATION_NUMBER2
gs://BUCKET_NAME/OBJECT_NAME3#GENERATION_NUMBER3
...

Observação :use a flag --long junto com a flag --all-versions para receber os números de metageração na resposta. Use as flags --full e --all-versions para receber Noncurrent Time de versões arquivadas de um objeto.

Bibliotecas de cliente

C++

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

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

namespace gcs = ::google::cloud::storage;
[](gcs::Client client, std::string const& bucket_name) {
  for (auto&& object_metadata :
       client.ListObjects(bucket_name, gcs::Versions{true})) {
    if (!object_metadata) throw std::move(object_metadata).status();

    std::cout << "bucket_name=" << object_metadata->bucket()
              << ", object_name=" << object_metadata->name()
              << ", generation=" << object_metadata->generation() << "\n";
  }
}

C#

Saiba mais na documentação de referência C# da API Cloud Storage.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

using Google.Cloud.Storage.V1;
using System;
using System.Collections.Generic;

public class ListFileArchivedGenerationSample
{
	public IEnumerable<Google.Apis.Storage.v1.Data.Object> ListFileArchivedGeneration(string bucketName = "your-bucket-name")
	{
		var storage = StorageClient.Create();

		var storageObjects = storage.ListObjects(bucketName, options: new ListObjectsOptions
		{
			Versions = true
		});

		foreach (var storageObject in storageObjects)
		{
			Console.WriteLine($"Filename: {storageObject.Name}, Generation: {storageObject.Generation}");
		}

		return storageObjects;
	}
}

Go

Saiba mais na documentação de referência Go da API Cloud Storage.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

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

	"cloud.google.com/go/storage"
	"google.golang.org/api/iterator"
)

// listFilesAllVersion lists both live and noncurrent versions of objects within specified bucket.
func listFilesAllVersion(w io.Writer, bucket string) error {
	// bucket := "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()

	it := client.Bucket(bucket).Objects(ctx, &storage.Query{
		// Versions true to output all generations of objects
		Versions: true,
	})
	for {
		attrs, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return fmt.Errorf("Bucket(%q).Objects(): %w", bucket, err)
		}
		fmt.Fprintln(w, attrs.Name, attrs.Generation, attrs.Metageneration)
	}
	return nil
}

Java

Saiba mais na documentação de referência Java da API Cloud Storage.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

import com.google.api.gax.paging.Page;
import com.google.cloud.storage.Blob;
import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class ListObjectsWithOldVersions {
  public static void listObjectsWithOldVersions(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);
    Page<Blob> blobs = bucket.list(Storage.BlobListOption.versions(true));

    for (Blob blob : blobs.iterateAll()) {
      System.out.println(blob.getName() + "," + blob.getGeneration());
    }
  }
}

Node.js

Saiba mais na documentação de referência Node.js da API Cloud Storage.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

/**
 * 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 listFilesWithOldVersions() {
  const [files] = await storage.bucket(bucketName).getFiles({
    versions: true,
  });

  console.log('Files:');
  files.forEach(file => {
    console.log(file.name, file.generation);
  });
}

listFilesWithOldVersions().catch(console.error);

PHP

Saiba mais na documentação de referência PHP da API Cloud Storage.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

use Google\Cloud\Storage\StorageClient;

/**
 * List objects in a specified bucket with all archived generations.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 */
function list_file_archived_generations(string $bucketName): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);

    $objects = $bucket->objects([
        'versions' => true,
    ]);

    foreach ($objects as $object) {
        print($object->name() . ',' . $object->info()['generation'] . PHP_EOL);
    }
}

Python

Saiba mais na documentação de referência Python da API Cloud Storage.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

from google.cloud import storage


def list_file_archived_generations(bucket_name):
    """Lists all the blobs in the bucket with generation."""
    # bucket_name = "your-bucket-name"

    storage_client = storage.Client()

    blobs = storage_client.list_blobs(bucket_name, versions=True)

    for blob in blobs:
        print(f"{blob.name},{blob.generation}")

Ruby

Saiba mais na documentação de referência Ruby da API Cloud Storage.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

def list_file_archived_generations 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.files.each do |file|
    puts "#{file.name},#{file.generation}"
  end
end

APIs REST

API JSON

1. Ter CLI gcloud instalada e inicializada, o que permite gerar um token de acesso para o cabeçalho Authorization.

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

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

   Em que BUCKET_NAME é o nome do bucket que contém os objetos. Por exemplo, my-bucket.

Versões arquivadas de objetos têm uma propriedade timeDeleted.

API XML

1. Ter CLI gcloud instalada e inicializada, o que permite gerar um token de acesso para o 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 versions:

   curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://storage.googleapis.com/BUCKET_NAME?versions&list-type=2"

   Em que BUCKET_NAME é o nome do bucket que contém os objetos. Por exemplo, my-bucket.

Há algumas diferenças nos resultados da solicitação GET quando se usa o parâmetro da consulta versions e quando ele não é usado. Especificamente, o Cloud Storage retorna as seguintes informações quando um parâmetro de consulta versions é incluído na solicitação:

• Um elemento Version que contém informações sobre cada objeto.
• Um elemento DeletedTime que contém a hora em que a versão do objeto foi arquivada (excluída ou substituída).
• Um elemento IsLatest que indica se o objeto específico é a versão mais recente.
• Um elemento NextGenerationMarker será retornado se a listagem de objetos for uma listagem parcial. Isso ocorre quando você tem muitas versões de objeto em um bucket. Use o valor desse elemento no parâmetro de consulta generationmarker das solicitações subsequentes para retomar a partir do último ponto. O parâmetro de consulta generationmarker é usado da mesma forma que o parâmetro de consulta marker para paginar uma listagem de um bucket sem controle de versão.

Acessar versões de objetos não atuais

Para usar a versão arquivada de um objeto ao realizar tarefas como fazer o download de um objeto, visualizar metadados ou atualizar metadados:

Console

O acesso geral a uma versão não atual não está disponível no console doGoogle Cloud . Com o console Google Cloud , só é possível mover, copiar, restaurar ou excluir uma versão arquivada. Essas ações são realizadas na lista do histórico de versões de um objeto.

Linha de comando

1. Anexe o número de geração da versão arquivada ao nome do objeto:

   OBJECT_NAME#GENERATION_NUMBER

   Em que:

   • OBJECT_NAME é o nome da versão arquivada. Por exemplo, pets/dog.png.
   • GENERATION_NUMBER é o número de geração da versão arquivada. Por exemplo, 1560468815691234.

2. Usando a string da etapa anterior, continue como normalmente faria para a versão ativa do objeto. Por exemplo, para ver os metadados de uma versão de objeto não atual, use o comando gcloud storage objects describe:

   gcloud storage objects describe gs://my-bucket/pets/dog.png#1560468815691234

APIs REST

API JSON

1. Anexe o número de geração da versão arquivada ao URI do objeto:

   https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?generation=GENERATION_NUMBER

   Em que:

   • BUCKET_NAME é o nome do bucket que contém a versão arquivada. Por exemplo, my-bucket.
   • OBJECT_NAME é o nome codificado por URL da versão arquivada. Por exemplo, pets/dog.png, codificado em URL como pets%2Fdog.png.
   • GENERATION_NUMBER é o número de geração da versão arquivada. Por exemplo, 1560468815691234.

2. Usando o URI da etapa anterior, continue como faria normalmente para a versão ativa do objeto. Por exemplo, para consultar os metadados de uma versão de objeto não atual, use cURL para chamar a API JSON com Objects: get:

   curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://storage.googleapis.com/storage/v1/b/my-bucket/o/pets/dog.png?generation=1560468815691234"

API XML

1. Anexe o número de geração da versão arquivada ao URI do objeto:

   https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME?generation=GENERATION_NUMBER

   Em que:

   • BUCKET_NAME é o nome do bucket que contém a versão arquivada. Por exemplo, my-bucket.
   • OBJECT_NAME é o nome codificado por URL da versão arquivada. Por exemplo, pets/dog.png, codificado em URL como pets%2Fdog.png.
   • GENERATION_NUMBER é o número de geração da versão arquivada. Por exemplo, 1560468815691234.

2. Usando o URI da etapa anterior, continue como faria normalmente para a versão ativa do objeto. Por exemplo, para visualizar os metadados de uma versão de objeto não atual, use cURL para chamar a API XML com uma HEAD Solicitação de objeto:

   curl -I GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://storage.googleapis.com/my-bucket/pets/dog.png?generation=1560468815691234"

Observação: não é possível fazer solicitações que substituam ou reescrevam um objeto não atual. O Cloud Storage não é compatível com a especificação de um número de geração para o objeto de destino.

Restaurar versões de objetos não atuais

No Cloud Storage, restaurar uma versão de objeto não atual significa fazer uma cópia dela. Ao fazer isso, a cópia se torna a versão ativa, restaurando efetivamente a versão. Se já houver uma versão ativa e o bucket tiver o recurso de controle de versões de objeto ativado, a restauração da versão não atual fará com que a versão ativa preexistente se torne não atual.

Console

Observação: o console do Google Cloud tem um limite de 1.000 versões de um objeto que pode ser listado.

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 que contém o objeto desejado.

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

3. Para visualizar objetos não atuais, clique no menu suspenso Mostrar e selecione Objetos ativos e não atuais.

4. Na lista de objetos, clique no nome da versão que você quer restaurar.

   A página Detalhes do objeto é aberta com a guia Objeto ativo selecionada.

5. Clique na guia Histórico de versões.

6. Clique no botão Restaurar da versão pretendida.

   O painel da versão do objeto de restauração é aberto.

7. Clique em Confirmar.

Linha de comando

Use o comando gcloud storage cp:

gcloud storage cp gs://BUCKET_NAME/OBJECT_NAME#GENERATION_NUMBER gs://BUCKET_NAME

Em que:

• BUCKET_NAME é o nome do bucket que contém a versão não atual que você quer restaurar. Por exemplo, my-bucket.
• OBJECT_NAME é o nome da versão não atual que você quer restaurar. Por exemplo, pets/dog.png.
• GENERATION_NUMBER é o número de geração da versão arquivada que você quer restaurar. Por exemplo, 1560468815691234.

Se funcionar, a resposta será parecida com esta:

Operation completed over 1 objects/58.8 KiB.

Observação: alguns shells, como zsh quando a opção extendedglob está ativada, tratam o caractere hash, #, como um caractere especial. Se esse for o caso, você precisa colocar esse argumento entre aspas simples (ou aspas duplas no Windows).

Bibliotecas de cliente

C++

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

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

namespace gcs = ::google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& source_bucket_name,
   std::string const& source_object_name,
   std::string const& destination_bucket_name,
   std::string const& destination_object_name,
   std::int64_t source_object_generation) {
  StatusOr<gcs::ObjectMetadata> copy =
      client.CopyObject(source_bucket_name, source_object_name,
                        destination_bucket_name, destination_object_name,
                        gcs::SourceGeneration{source_object_generation});
  if (!copy) throw std::move(copy).status();

  std::cout << "Successfully copied " << source_object_name << " generation "
            << source_object_generation << " in bucket " << source_bucket_name
            << " to bucket " << copy->bucket() << " with name "
            << copy->name()
            << ".\nThe full metadata after the copy is: " << *copy << "\n";
}

C#

Saiba mais na documentação de referência C# da API Cloud Storage.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

using Google.Cloud.Storage.V1;
using System;

public class CopyFileArchivedGenerationSample
{
    public Google.Apis.Storage.v1.Data.Object CopyFileArchivedGeneration(
        string sourceBucketName = "source-bucket-name",
        string sourceObjectName = "source-file",
        string destBucketName = "destination-bucket-name",
        string destObjectName = "destination-file-name",
        long? generation = 1579287380533984)
    {
        var storage = StorageClient.Create();
        var copyOptions = new CopyObjectOptions
        {
            SourceGeneration = generation
        };

        var copiedFile = storage.CopyObject(sourceBucketName, sourceObjectName,
            destBucketName, destObjectName, copyOptions);

        Console.WriteLine($"Generation {generation} of the object {sourceBucketName}/{sourceObjectName} " +
            $"was copied to to {destBucketName}/{destObjectName}.");

        return copiedFile;
    }
}

Go

Saiba mais na documentação de referência Go da API Cloud Storage.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

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

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

// copyOldVersionOfObject copies a noncurrent version of an object.
func copyOldVersionOfObject(w io.Writer, bucket, srcObject, dstObject string, gen int64) error {
	// bucket := "bucket-name"
	// srcObject := "source-object-name"
	// dstObject := "destination-object-name"

	// gen is the generation of srcObject to copy.
	// gen := 1587012235914578
	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()

	src := client.Bucket(bucket).Object(srcObject)
	dst := client.Bucket(bucket).Object(dstObject)

	// Optional: set a generation-match precondition to avoid potential race
	// conditions and data corruptions. The request to copy is aborted if the
	// object's generation number does not match your precondition.
	// For a dst object that does not yet exist, set the DoesNotExist precondition.
	dst = dst.If(storage.Conditions{DoesNotExist: true})
	// If the destination object already exists in your bucket, set instead a
	// generation-match precondition using its generation number.
	// attrs, err := dst.Attrs(ctx)
	// if err != nil {
	// 	return fmt.Errorf("object.Attrs: %w", err)
	// }
	// dst = dst.If(storage.Conditions{GenerationMatch: attrs.Generation})

	if _, err := dst.CopierFrom(src.Generation(gen)).Run(ctx); err != nil {
		return fmt.Errorf("Object(%q).CopierFrom(%q).Generation(%v).Run: %w", dstObject, srcObject, gen, err)
	}
	fmt.Fprintf(w, "Generation %v of object %v in bucket %v was copied to %v\n", gen, srcObject, bucket, dstObject)
	return nil
}

Java

Saiba mais na documentação de referência Java da API Cloud Storage.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

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

public class CopyOldVersionOfObject {
  public static void copyOldVersionOfObject(
      String projectId,
      String bucketName,
      String objectToCopy,
      long generationToCopy,
      String newObjectName) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

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

    // The ID of the GCS object to copy an old version of
    // String objectToCopy = "your-object-name";

    // The generation of objectToCopy to copy
    // long generationToCopy = 1579287380533984;

    // What to name the new object with the old data from objectToCopy
    // String newObjectName = "your-new-object";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();

    // Optional: set a generation-match precondition to avoid potential race
    // conditions and data corruptions. The request returns a 412 error if the
    // preconditions are not met.
    Storage.BlobTargetOption precondition;
    if (storage.get(bucketName, newObjectName) == null) {
      // For a target object that does not yet exist, set the DoesNotExist precondition.
      // This will cause the request to fail if the object is created before the request runs.
      precondition = Storage.BlobTargetOption.doesNotExist();
    } else {
      // If the destination already exists in your bucket, instead set a generation-match
      // precondition. This will cause the request to fail if the existing object's generation
      // changes before the request runs.
      precondition =
          Storage.BlobTargetOption.generationMatch(
              storage.get(bucketName, newObjectName).getGeneration());
    }

    Storage.CopyRequest copyRequest =
        Storage.CopyRequest.newBuilder()
            .setSource(BlobId.of(bucketName, objectToCopy, generationToCopy))
            .setTarget(BlobId.of(bucketName, newObjectName), precondition)
            .build();
    storage.copy(copyRequest);

    System.out.println(
        "Generation "
            + generationToCopy
            + " of object "
            + objectToCopy
            + " in bucket "
            + bucketName
            + " was copied to "
            + newObjectName);
  }
}

Node.js

Saiba mais na documentação de referência Node.js da API Cloud Storage.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

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

// The ID of the GCS file to copy an old version of
// const srcFilename = "your-file-name";

// The generation of fileToCopy to copy
// const generation = 1579287380533984;

// The ID of the bucket to copy the file to
// const destBucketName = 'target-file-bucket';

// What to name the new file with the old data from srcFilename
// const destFileName = "your-new-file";

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

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

async function copyOldVersionOfFile() {
  // Copies the file to the other bucket

  // Optional:
  // Set a generation-match precondition to avoid potential race conditions
  // and data corruptions. The request to copy is aborted if the object's
  // generation number does not match your precondition. For a destination
  // object that does not yet exist, set the ifGenerationMatch precondition to 0
  // If the destination object already exists in your bucket, set instead a
  // generation-match precondition using its generation number.
  const copyOptions = {
    preconditionOpts: {
      ifGenerationMatch: destinationGenerationMatchPrecondition,
    },
  };

  await storage
    .bucket(srcBucketName)
    .file(srcFilename, {
      generation,
    })
    .copy(storage.bucket(destBucketName).file(destFileName), copyOptions);

  console.log(
    `Generation ${generation} of file ${srcFilename} in bucket ${srcBucketName} was copied to ${destFileName} in bucket ${destBucketName}`
  );
}

copyOldVersionOfFile().catch(console.error);

PHP

Saiba mais na documentação de referência PHP da API Cloud Storage.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

use Google\Cloud\Storage\StorageClient;

/**
 * Copy archived generation of a given object to a new object.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 * @param string $objectToCopy The name of the object to copy.
 *        (e.g. 'my-object')
 * @param string $generationToCopy The generation of the object to copy.
 *        (e.g. 1579287380533984)
 * @param string $newObjectName The name of the target object.
 *        (e.g. 'my-object-1579287380533984')
 */
function copy_file_archived_generation(string $bucketName, string $objectToCopy, string $generationToCopy, string $newObjectName): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);

    $object = $bucket->object($objectToCopy, [
        'generation' => $generationToCopy,
    ]);

    $object->copy($bucket, [
        'name' => $newObjectName,
    ]);

    printf(
        'Generation %s of object %s in bucket %s was copied to %s',
        $generationToCopy,
        $objectToCopy,
        $bucketName,
        $newObjectName
    );
}

Python

Saiba mais na documentação de referência Python da API Cloud Storage.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

from google.cloud import storage


def copy_file_archived_generation(
        bucket_name, blob_name, destination_bucket_name, destination_blob_name, generation
):
    """Copies a blob from one bucket to another with a new name with the same generation."""
    # bucket_name = "your-bucket-name"
    # blob_name = "your-object-name"
    # destination_bucket_name = "destination-bucket-name"
    # destination_blob_name = "destination-object-name"
    # generation = 1579287380533984

    storage_client = storage.Client()

    source_bucket = storage_client.bucket(bucket_name)
    source_blob = source_bucket.blob(blob_name)
    destination_bucket = storage_client.bucket(destination_bucket_name)

    # Optional: set a generation-match precondition to avoid potential race conditions
    # and data corruptions. The request to copy is aborted if the object's
    # generation number does not match your precondition. For a destination
    # object that does not yet exist, set the if_generation_match precondition to 0.
    # If the destination object already exists in your bucket, set instead a
    # generation-match precondition using its generation number.
    destination_generation_match_precondition = 0

    # source_generation selects a specific revision of the source object, as opposed to the latest version.
    blob_copy = source_bucket.copy_blob(
        source_blob, destination_bucket, destination_blob_name, source_generation=generation, if_generation_match=destination_generation_match_precondition
    )

    print(
        "Generation {} of the blob {} in bucket {} copied to blob {} in bucket {}.".format(
            generation,
            source_blob.name,
            source_bucket.name,
            blob_copy.name,
            destination_bucket.name,
        )
    )

Ruby

Saiba mais na documentação de referência Ruby da API Cloud Storage.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

def copy_file_archived_generation source_bucket_name:,
                                  source_file_name:,
                                  generation:,
                                  destination_bucket_name:,
                                  destination_file_name:
  # The ID of the bucket the original object is in
  # source_bucket_name = "source-bucket-name"

  # The ID of the GCS object to copy
  # source_file_name = "source-file-name"

  # The generation of your GCS object to copy
  # generation = 1579287380533984

  # The ID of the bucket to copy the object to
  # destination_bucket_name = "destination-bucket-name"

  # The ID of the new GCS object
  # destination_file_name = "destination-file-name"

  require "google/cloud/storage"

  storage = Google::Cloud::Storage.new

  source_bucket = storage.bucket source_bucket_name, skip_lookup: true
  source_file = source_bucket.file source_file_name
  destination_bucket = storage.bucket destination_bucket_name, skip_lookup: true

  destination_file = source_file.copy destination_bucket, destination_file_name, generation: generation

  puts "Generation #{generation} of the file #{source_file.name} in bucket #{source_bucket.name} copied to file " \
       "#{destination_file.name} in bucket #{destination_bucket.name}"
end

APIs REST

API JSON

1. Ter CLI gcloud instalada e inicializada, o que permite gerar um token de acesso para o cabeçalho Authorization.

2. Use cURL para chamar a API JSON com uma solicitação de objeto POST:

   curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Length: 0" \
     "https://storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME/rewriteTo/b/BUCKET_NAME/o/OBJECT_NAME?sourceGeneration=GENERATION_NUMBER"

   Em que:

   • BUCKET_NAME é o nome do bucket que contém a versão não atual que você quer restaurar. Por exemplo, my-bucket.
   • OBJECT_NAME é o nome codificado por URL da versão arquivada que você quer restaurar. Por exemplo, pets/dog.png, codificado por URL como pets%2Fdog.png.
   • GENERATION_NUMBER é o número de geração da versão arquivada que você quer restaurar. Por exemplo, 1560468815691234.

API XML

1. Ter CLI gcloud instalada e inicializada, o que permite gerar um token de acesso para o cabeçalho Authorization.

2. Use cURL para chamar a API XML com uma solicitação PUT Objeto:

   curl -X PUT \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-copy-source: BUCKET_NAME/OBJECT_NAME" \
     -H "x-goog-copy-source-generation:GENERATION_NUMBER" \
     "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"

   Em que:

   • BUCKET_NAME é o nome do bucket que contém a versão não atual que você quer restaurar. Por exemplo, my-bucket.
   • OBJECT_NAME é o nome codificado por URL da versão arquivada que você quer restaurar. Por exemplo, pets/dog.png, codificado por URL como pets%2Fdog.png.
   • GENERATION_NUMBER é o número de geração da versão arquivada que você quer restaurar. Por exemplo, 1560468815691234.

Depois de restaurar a versão do objeto, a versão original não atual continuará existindo no bucket. Se você não precisar mais da versão não atual, será possível excluí-la ou configurar o Gerenciamento de ciclo de vida de objetos para removê-la quando as condições especificadas forem atendidas.

Excluir versões de objeto não atuais

Console

Observação: o console do Google Cloud tem um limite de 1.000 versões de um objeto que pode ser listado.

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 que contém o objeto desejado.

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

3. Para visualizar objetos não atuais, clique no menu suspenso Mostrar e selecione Objetos ativos e não atuais.

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

5. Na lista de objetos, clique no nome do objeto cuja versão você quer excluir.

   A página Detalhes do objeto é aberta com a guia Objeto ativo selecionada.

6. Clique na guia Histórico de versões.

7. Marque a caixa de seleção da versão desejada.

8. Clique no botão Excluir.

   O painel de exclusão de versão será aberto.

9. Confirme se você quer excluir o objeto digitando delete no campo de texto.

10. Clique em Excluir.

Linha de comando

Use o comando gcloud storage rm:

gcloud storage rm gs://BUCKET_NAME/OBJECT_NAME#GENERATION_NUMBER

Em que:

• BUCKET_NAME é o nome do bucket que contém a versão arquivada que você quer excluir. Por exemplo, my-bucket.
• OBJECT_NAME é o nome da versão arquivada que você quer excluir. Por exemplo, pets/dog.png.
• GENERATION_NUMBER é o número de geração da versão arquivada que você quer excluir. Por exemplo, 1560468815691234.

Se funcionar, a resposta será parecida com esta:

Operation completed over 1 objects.

Observação: remova todas as versões de um objeto, incluindo as ativas e não atuais, usando a flag --all-versions e omitindo o #GENERATION_NUMBER. Você pode remover todas as versões de todos os objetos, e possivelmente o próprio bucket, usando a sinalização --recursive.

Bibliotecas de cliente

C++

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

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

namespace gcs = ::google::cloud::storage;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& object_name, std::int64_t object_generation) {
  google::cloud::Status status = client.DeleteObject(
      bucket_name, object_name, gcs::Generation{object_generation});
  if (!status.ok()) throw std::runtime_error(status.message());

  std::cout << "Deleted " << object_name << " generation "
            << object_generation << " in bucket " << bucket_name << "\n";
}

C#

Saiba mais na documentação de referência C# da API Cloud Storage.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

using Google.Cloud.Storage.V1;
using System;

public class DeleteFileArchivedGenerationSample
{
    public void DeleteFileArchivedGeneration(
        string bucketName = "your-bucket-name",
        string objectName = "your-object-name",
        long? generation = 1579287380533984)
    {
        var storage = StorageClient.Create();

        storage.DeleteObject(bucketName, objectName, new DeleteObjectOptions
        {
            Generation = generation
        });

        Console.WriteLine($"Generation ${generation} of file {objectName} was deleted from bucket {bucketName}.");
    }
}

Go

Saiba mais na documentação de referência Go da API Cloud Storage.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

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

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

// deleteOldVersionOfObject deletes a noncurrent version of an object.
func deleteOldVersionOfObject(w io.Writer, bucketName, objectName string, gen int64) error {
	// bucketName := "bucket-name"
	// objectName := "object-name"

	// gen is the generation of objectName to delete.
	// gen := 1587012235914578
	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()

	obj := client.Bucket(bucketName).Object(objectName)
	if err := obj.Generation(gen).Delete(ctx); err != nil {
		return fmt.Errorf("Bucket(%q).Object(%q).Generation(%v).Delete: %w", bucketName, objectName, gen, err)
	}
	fmt.Fprintf(w, "Generation %v of object %v was deleted from %v\n", gen, objectName, bucketName)
	return nil
}

Java

Saiba mais na documentação de referência Java da API Cloud Storage.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

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

public class DeleteOldVersionOfObject {
  public static void deleteOldVersionOfObject(
      String projectId, String bucketName, String objectName, long generationToDelete) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

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

    // The ID of your GCS object
    // String objectName = "your-object-name";

    // The generation of objectName to delete
    // long generationToDelete = 1579287380533984;

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    storage.delete(BlobId.of(bucketName, objectName, generationToDelete));

    System.out.println(
        "Generation "
            + generationToDelete
            + " of object "
            + objectName
            + " was deleted from "
            + bucketName);
  }
}

Node.js

Saiba mais na documentação de referência Node.js da API Cloud Storage.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

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

// The ID of your GCS file
// const fileName = 'your-file-name';

// The generation of fileName to delete
// const generation = 1579287380533984;

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

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

async function deleteOldVersionOfFile() {
  // Deletes the file from the bucket with given version
  await storage
    .bucket(bucketName)
    .file(fileName, {
      generation,
    })
    .delete();

  console.log(
    `Generation ${generation} of file ${fileName} was deleted from ${bucketName}`
  );
}

deleteOldVersionOfFile().catch(console.error);

PHP

Saiba mais na documentação de referência PHP da API Cloud Storage.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

use Google\Cloud\Storage\StorageClient;

/**
 * Delete an archived generation of the given object.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 * @param string $objectName The name of your Cloud Storage object.
 *        (e.g. 'my-object')
 * @param string $generationToDelete the generation of the object to delete.
 *        (e.g. 1579287380533984)
 */
function delete_file_archived_generation(string $bucketName, string $objectName, string $generationToDelete): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);

    $object = $bucket->object($objectName, [
        'generation' => $generationToDelete,
    ]);

    $object->delete();

    printf(
        'Generation %s of object %s was deleted from %s',
        $generationToDelete,
        $objectName,
        $bucketName
    );
}

Python

Saiba mais na documentação de referência Python da API Cloud Storage.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

from google.cloud import storage


def delete_file_archived_generation(bucket_name, blob_name, generation):
    """Delete a blob in the bucket with the given generation."""
    # bucket_name = "your-bucket-name"
    # blob_name = "your-object-name"
    # generation = 1579287380533984

    storage_client = storage.Client()

    bucket = storage_client.get_bucket(bucket_name)
    bucket.delete_blob(blob_name, generation=generation)
    print(
        f"Generation {generation} of blob {blob_name} was deleted from {bucket_name}"
    )

Ruby

Saiba mais na documentação de referência Ruby da API Cloud Storage.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

def delete_file_archived_generation bucket_name:, file_name:, generation:
  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  # The ID of your GCS object
  # file_name = "your-file-name"

  # The generation of the file to delete
  # generation = 1579287380533984

  require "google/cloud/storage"

  storage = Google::Cloud::Storage.new
  bucket = storage.bucket bucket_name, skip_lookup: true

  file = bucket.file file_name

  file.delete generation: generation

  puts "Generation #{generation} of file #{file_name} was deleted from #{bucket_name}"
end

APIs REST

API JSON

1. Ter CLI gcloud instalada e inicializada, o que permite gerar um token de acesso para o cabeçalho Authorization.

2. Use cURL para chamar a API JSON com uma solicitação de objeto DELETE:

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

   Em que:

   • BUCKET_NAME é o nome do bucket que contém a versão arquivada que você quer excluir. Por exemplo, my-bucket.
   • OBJECT_NAME é o nome codificado por URL da versão arquivada que você quer restaurar. Por exemplo, pets/dog.png, codificado por URL como pets%2Fdog.png.
   • GENERATION_NUMBER é o número de geração da versão arquivada que você quer excluir. Por exemplo, 1560468815691234.

API XML

1. Ter CLI gcloud instalada e inicializada, o que permite gerar um token de acesso para o cabeçalho Authorization.

2. Use cURL para chamar a API XML com uma solicitação DELETE Objeto:

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

   Em que:

   • BUCKET_NAME é o nome do bucket que contém a versão arquivada que você quer excluir. Por exemplo, my-bucket.
   • OBJECT_NAME é o nome codificado por URL da versão arquivada que você quer restaurar. Por exemplo, pets/dog.png, codificado por URL como pets%2Fdog.png.
   • GENERATION_NUMBER é o número de geração da versão arquivada que você quer excluir. Por exemplo, 1560468815691234.

A seguir

• Saiba mais sobre o controle de versão de objetos, incluindo um exemplo detalhado.
• Saiba como desativar o controle de versões de objetos em um bucket.
• Saiba como usar o Gerenciamento do ciclo de vida de objetos para gerenciar automaticamente as versões de objetos.