Use objetos com controlo de versões

Vista geral Configuração

Esta página descreve como listar, aceder, restaurar e eliminar objetos não atuais, o que normalmente se aplica a contentores com a funcionalidade de controlo de versões de objetos ativada. Os objetos não atuais também são denominados objetos com versões.

Antes de começar

Para trabalhar com objetos não atuais, conclua os seguintes passos pré-requisitos.

Ative o controlo de versões de objetos

Se ainda não o fez, ative a criação de versões de objetos no seu contentor.

Obtenha as funções necessárias

Para receber as autorizações de que precisa para gerir objetos não atuais, peça ao seu administrador para lhe conceder a função de utilizador de objetos de armazenamento (roles/storage.objectUser) do IAM no projeto. Esta função predefinida contém as autorizações necessárias para gerir objetos não atuais. Para ver as autorizações exatas necessárias, expanda a secção Autorizações necessárias:

Autorizações necessárias

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

Também pode conseguir estas autorizações com funções personalizadas.

Para informações sobre a atribuição de funções em projetos, consulte o artigo Faça a gestão do acesso a projetos.

Consoante o seu exemplo de utilização, pode precisar de autorizações adicionais ou funções alternativas:

• Se planeia usar a Google Cloud consola para realizar as tarefas nesta página, também precisa da autorização storage.buckets.list, que não está incluída na função de utilizador do objeto de armazenamento (roles/storage.objectUser). Para receber esta autorização, peça ao seu administrador para lhe conceder a função de administrador do armazenamento (roles/storage.admin) no projeto.

• Se o acesso uniforme ao nível do contentor estiver desativado para o seu contentor, precisa de autorizações adicionais nos seguintes cenários:

  • Se planeia devolver objetos não atuais juntamente com as respetivas ACLs, também precisa da autorização storage.objects.getIamPolicy, que não está incluída na função de utilizador do objeto de armazenamento (roles/storage.objectUser). Para receber esta autorização, peça ao seu administrador para lhe conceder a função de administrador de objetos de armazenamento (roles/storage.objectAdmin) no projeto.

  • Se planeia mudar o nome ou restaurar objetos não atuais que tenham ACLs, também precisa da autorização storage.objects.setIamPolicy, que não está incluída na função de utilizador de objetos de armazenamento (roles/storage.objectUser). Para receber esta autorização, peça ao seu administrador para lhe conceder a função de administrador de objetos de armazenamento (roles/storage.objectAdmin) no projeto.

Listar versões de objetos não atuais

Para listar as versões atuais e não atuais de objetos e ver os respetivos generation números:

Consola

Nota: a Google Cloud consola tem um limite de 1000 versões de um objeto que pode listar. Para ver mais versões de um objeto, use a CLI gcloud.

1. Na Google Cloud consola, aceda à página Recipientes do Cloud Storage.
   

   Aceda a Recipientes

2. Na lista de contentores, clique no nome do contentor que contém o objeto pretendido.

   É aberta a página Detalhes do contentor, com o separador Objetos selecionado.

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

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

   É apresentada a página Detalhes do objeto, com o separador Objeto em direto selecionado.

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

Linha de comandos

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

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

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

A resposta tem o seguinte aspeto:

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

Nota: use a flag --long juntamente com a flag --all-versions para obter números de metageração na resposta. Use a flag --full juntamente com a flag --all-versions para obter o Noncurrent Time para versões não atuais de um objeto.

Bibliotecas cliente

C++

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

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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#

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

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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

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

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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

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

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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

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

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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

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

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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

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

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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

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

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 a CLI gcloud instalada e inicializada, o que lhe permite gerar um token de acesso para o cabeçalho Authorization.

2. Use cURL para chamar a API JSON com um pedido de 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"

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

As versões não atuais dos objetos têm uma propriedade timeDeleted.

API XML

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

2. Use cURL para chamar a API XML, com um pedido de GET contentor e o 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"

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

Existem algumas diferenças nos resultados do pedido GET quando usa o parâmetro de consulta versions em comparação com quando não o usa. Em concreto, o Cloud Storage devolve as seguintes informações quando inclui um parâmetro de consulta versions no seu pedido:

• 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 deixou de ser atual (foi eliminada ou substituída).
• Um elemento `IsLatest que indica se o objeto específico é a versão mais recente.
• É devolvido um elemento NextGenerationMarker se a listagem de objetos for uma listagem parcial, o que ocorre quando tem muitas versões de objetos num contentor. Use o valor deste elemento no parâmetro de consulta generationmarker de pedidos subsequentes para retomar a partir do seu último ponto. O parâmetro de consulta generationmarker é usado da mesma forma que usa o parâmetro de consulta marker para navegar numa ficha de um contentor sem versão.

Aceda a versões de objetos não atuais

Para usar a versão não atual de um objeto quando realizar tarefas como: transferir o objeto, ver os respetivos metadados ou atualizar os respetivos metadados:

Consola

O acesso geral a uma versão não atual não está disponível na Google Cloud consola. Usando a Google Cloud consola, só pode mover, copiar, restaurar ou eliminar uma versão não atual. Estas ações são realizadas a partir da lista do histórico de versões de um objeto.

Linha de comandos

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

   OBJECT_NAME#GENERATION_NUMBER

   Onde:

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

2. Usando a string do passo anterior, proceda como faria normalmente para a versão em direto 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 não atual ao URI do objeto:

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

   Onde:

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

2. Usando o URI do passo anterior, proceda como faria normalmente para a versão em direto do objeto. Por exemplo, para ver os metadados de uma versão de objeto não atual, use o cURL para chamar a API JSON com um pedido 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 não atual ao URI do objeto:

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

   Onde:

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

2. Usando o URI do passo anterior, proceda como faria normalmente para a versão em direto do objeto. Por exemplo, para ver os metadados de uma versão de objeto não atual, use cURL para chamar a API XML com um pedido de HEAD objeto:

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

Nota: não pode fazer pedidos que substituam ou reescrevam um objeto não atual, porque o Cloud Storage não suporta a especificação de um número de geração para o objeto de destino.

Restaure versões de objetos não atuais

No Cloud Storage, restaurar uma versão de objeto não atual significa fazer uma cópia da mesma. Quando o faz, a cópia torna-se a versão publicada, o que restaura efetivamente a versão. Se já existir uma versão publicada e o contentor tiver a funcionalidade de controlo de versões de objetos ativada, a restauração da versão não atual faz com que a versão publicada pré-existente se torne não atual.

Consola

Nota: a Google Cloud consola tem um limite de 1000 versões de um objeto que pode listar.

1. Na Google Cloud consola, aceda à página Recipientes do Cloud Storage.
   

   Aceda a Recipientes

2. Na lista de contentores, clique no nome do contentor que contém o objeto pretendido.

   É aberta a página Detalhes do contentor, com o separador Objetos selecionado.

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

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

   É apresentada a página Detalhes do objeto, com o separador Objeto em direto selecionado.

5. Clique no separador Histórico de versões.

6. Clique no botão Restaurar para a versão pretendida.

   É aberto o painel de restauro da versão do objeto.

7. Clique em Confirm.

Linha de comandos

Use o comando gcloud storage cp:

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

Onde:

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

Se for bem-sucedido, a resposta é semelhante ao exemplo seguinte:

Operation completed over 1 objects/58.8 KiB.

Nota: algumas shells, como a zsh quando a opção extendedglob está ativada, tratam o carater cardinal, #, como um carater especial. Se este for o caso para o seu shell, deve incluir esse argumento entre aspas simples (ou aspas duplas para o Windows).

Bibliotecas cliente

C++

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

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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#

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

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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

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

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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

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

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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

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

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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

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

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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

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

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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

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

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 a CLI gcloud instalada e inicializada, o que lhe permite gerar um token de acesso para o cabeçalho Authorization.

2. Use cURL para chamar a API JSON com um pedido de POST objeto:

   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"

   Onde:

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

API XML

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

2. Use cURL para chamar a API XML, com um pedido de 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"

   Onde:

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

Depois de restaurar a versão do objeto, a versão não atual original continua a existir no contentor. Se já não precisar da versão não atual, pode eliminá-la posteriormente ou configurar a gestão do ciclo de vida dos objetos para a remover quando cumprir as condições especificadas.

Elimine versões de objetos não atuais

Consola

Nota: a Google Cloud consola tem um limite de 1000 versões de um objeto que pode listar.

1. Na Google Cloud consola, aceda à página Recipientes do Cloud Storage.
   

   Aceda a Recipientes

2. Na lista de contentores, clique no nome do contentor que contém o objeto pretendido.

   É aberta a página Detalhes do contentor, com o separador Objetos selecionado.

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

4. Navegue para o objeto, que pode estar localizado numa pasta.

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

   É aberta a página Detalhes do objeto, com o separador Objeto em direto selecionado.

6. Clique no separador Histórico de versões.

7. Selecione a caixa de verificação da versão pretendida.

8. Clique no botão Eliminar.

   É aberto o painel Eliminar versão.

9. Confirme que quer eliminar o objeto escrevendo delete no campo de texto.

10. Clique em Eliminar.

Linha de comandos

Use o comando gcloud storage rm:

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

Onde:

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

Se for bem-sucedido, a resposta é semelhante ao exemplo seguinte:

Operation completed over 1 objects.

Nota: pode remover todas as versões de um objeto, incluindo as versões ativas e não atuais, usando a flag --all-versions e omitindo o #GENERATION_NUMBER. Pode remover todas as versões de todos os objetos (e potencialmente o próprio contentor) usando a flag --recursive.

Bibliotecas cliente

C++

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

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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#

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

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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

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

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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

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

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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

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

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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

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

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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

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

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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

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

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 a CLI gcloud instalada e inicializada, o que lhe permite gerar um token de acesso para o cabeçalho Authorization.

2. Use cURL para chamar a API JSON com um pedido de DELETE objeto:

   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"

   Onde:

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

API XML

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

2. Use cURL para chamar a API XML, com um pedido de DELETE objeto:

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

   Onde:

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

O que se segue?

• Saiba mais sobre o controlo de versões de objetos, incluindo um exemplo detalhado.
• Saiba como desativar a criação de versões de objetos num contentor.
• Saiba como usar a gestão do ciclo de vida de objetos para gerir automaticamente as versões de objetos.