Copie, mude o nome e mova objetos

Esta página mostra como copiar, mudar o nome e mover objetos. Embora algumas ferramentas realizem operações de movimento de objetos atómicas, outras ferramentas simulam uma operação de movimento de objetos copiando o objeto para uma nova localização especificada e, em seguida, eliminando o objeto original.

• Para ver instruções sobre como copiar objetos, consulte o artigo Copie objetos.
• Para obter instruções sobre como mover ou mudar o nome de objetos copiando-os, consulte o artigo Mova ou mude o nome de objetos copiando-os.
• Para ver instruções sobre como mudar o nome de objetos de forma atómica, consulte o artigo Mude o nome de objetos de forma atómica.

Aviso: uma vez que a movimentação de objetos através da respetiva cópia inclui a eliminação dos objetos originais do contentor de origem, a utilização deste método para mover objetos cuja classe de armazenamento seja Nearline storage, Coldline storage ou Archive storage pode incorrer em custos de eliminação antecipada. Se mover objetos de forma atómica, não incorre em custos de eliminação antecipada, independentemente da classe de armazenamento dos objetos que estão a ser movidos.

Recomendamos a utilização do Serviço de transferência de armazenamento para mover mais de 1 TB de dados entre contentores.

Antes de começar

Para copiar, mudar o nome ou mover objetos, tem de ter as funções do IAM necessárias. As secções seguintes descrevem os requisitos do IAM para diferentes exemplos de utilização.

Copiar objetos (incluindo mover ou mudar o nome através da cópia)

Para receber as autorizações de que precisa para copiar objetos, peça ao seu administrador que lhe conceda as seguintes funções do IAM no contentor de origem que contém os objetos que quer mover ou no contentor de destino para onde quer mover os objetos:

• Storage Object Viewer (roles/storage.objectViewer) no contentor de origem
• Utilizador de objetos do Storage (roles/storage.objectUser) no contentor de destino
• Para copiar objetos através da Google Cloud consola: Função básica de leitor (roles/viewer) no contentor de origem e no contentor de destino, além de roles/storage.objectViewer e roles/storage.objectUser

Estas funções predefinidas contêm as autorizações necessárias para copiar objetos. Para ver as autorizações exatas que são necessárias, expanda a secção Autorizações necessárias:

Autorizações necessárias

São necessárias as seguintes autorizações para copiar objetos:

• storage.objects.get no contentor de origem
• storage.objects.create no contentor de destino
• storage.objects.delete (obrigatório apenas se estiver a substituir ou a substituir um objeto no contentor de destino como parte de uma operação de cópia ou movimento de objetos) no contentor de destino
• storage.objects.delete (obrigatório apenas se estiver a mover um objeto através de uma operação de cópia e eliminação subjacente) no contentor de origem
• storage.folders.create (obrigatório apenas se o objeto que está a mover estiver localizado numa pasta que quer criar no contentor de destino) no contentor de destino
• storage.objects.list (obrigatório apenas se estiver a copiar, mover ou mudar o nome de um objeto através da Google Cloud consola) nos contentores de origem e destino
• storage.buckets.list (obrigatório apenas se estiver a copiar, mover ou mudar o nome de um objeto através da Google Cloud consola) no projeto que contém os contentores de origem e de destino

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

Para ver informações sobre a concessão de funções em contentores, consulte o artigo Use o IAM com contentores. Para informações sobre a atribuição de funções em projetos, consulte o artigo Faça a gestão do acesso a projetos.

Se o objeto que quer copiar tiver determinadas funcionalidades ativadas, pode precisar de funções adicionais ou alternativas. Por exemplo, se o objeto que quer copiar tiver uma configuração de retenção de objetos que quer manter, precisa de uma função no contentor de destino que inclua a autorização storage.objects.setRetention, como a função de administrador de objetos de armazenamento (roles/storage.objectAdmin). Para mais informações, consulte o artigo Autorizações de IAM para o Cloud Storage.

Mude o nome dos objetos de forma atómica

Para receber as autorizações de que precisa para mudar o nome de objetos de forma atómica, peça ao seu administrador para lhe conceder a função de IAM Utilizador de objetos de armazenamento (roles/storage.objectUser) no contentor que contém o objeto ao qual quer mudar o nome.

Esta função predefinida contém as autorizações necessárias para mudar o nome de objetos de forma atómica. Para ver as autorizações exatas que são necessárias, expanda a secção Autorizações necessárias:

Autorizações necessárias

São necessárias as seguintes autorizações para mudar o nome de objetos de forma atómica:

• storage.objects.move
• storage.objects.create
• storage.objects.delete (obrigatório apenas se estiver a substituir um objeto)

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

Para ver informações sobre a concessão de funções em contentores, consulte o artigo Use o IAM com contentores.

Copie objetos

Esta secção descreve como copiar objetos. Pode copiar objetos de um contentor para outro.

Nota: se estiver a copiar um objeto com mais de 2 GB em diferentes regiões ou classes de armazenamento, recomendamos que use a CLI gcloud para um desempenho ideal.

Consola

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 que quer copiar.

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

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

4. Clique no menu Adicional de objetos () associado ao objeto.

5. Clique em Copiar.

   É apresentado o painel Copiar objeto.

6. No campo Destino, escreva o nome do contentor de destino e o nome do objeto copiado.

   Em alternativa, pode clicar em Procurar para selecionar o destino, mas as opções de procura estão limitadas a contentores no projeto atual.

7. Clique em Copiar.

Para saber como obter informações detalhadas sobre erros relativos a operações do Cloud Storage falhadas na Google Cloud consola, consulte a secção Resolução de problemas.

Linha de comandos

Use o comando gcloud storage cp:

gcloud storage cp gs://SOURCE_BUCKET_NAME/SOURCE_OBJECT_NAME gs://DESTINATION_BUCKET_NAME/NAME_OF_COPY

Onde:

• SOURCE_BUCKET_NAME é o nome do contentor que contém o objeto que quer copiar. Por exemplo, my-bucket.
• SOURCE_OBJECT_NAME é o nome do objeto que quer copiar. Por exemplo, pets/dog.png.
• DESTINATION_BUCKET_NAME é o nome do contentor onde quer copiar o objeto. Por exemplo, another-bucket.
• NAME_OF_COPY é o nome que quer dar à cópia do objeto. Por exemplo, shiba.png.

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

Copying gs://example-bucket/file.txt to gs://other-bucket/file-copy.txt
  Completed files 1/1 | 164.3kiB/164.3kiB 

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) {
  StatusOr<gcs::ObjectMetadata> new_copy_meta =
      client.CopyObject(source_bucket_name, source_object_name,
                        destination_bucket_name, destination_object_name);
  if (!new_copy_meta) throw std::move(new_copy_meta).status();

  std::cout << "Successfully copied " << source_object_name << " in bucket "
            << source_bucket_name << " to bucket " << new_copy_meta->bucket()
            << " with name " << new_copy_meta->name()
            << ".\nThe full metadata after the copy is: " << *new_copy_meta
            << "\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 CopyFileSample
{
    public void CopyFile(
        string sourceBucketName = "source-bucket-name",
        string sourceObjectName = "source-file",
        string destBucketName = "destination-bucket-name",
        string destObjectName = "destination-file-name")
    {
        var storage = StorageClient.Create();
        storage.CopyObject(sourceBucketName, sourceObjectName, destBucketName, destObjectName);

        Console.WriteLine($"Copied {sourceBucketName}/{sourceObjectName} to " + $"{destBucketName}/{destObjectName}.");
    }
}

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

// copyFile copies an object into specified bucket.
func copyFile(w io.Writer, dstBucket, srcBucket, srcObject string) error {
	// dstBucket := "bucket-1"
	// srcBucket := "bucket-2"
	// srcObject := "object"
	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()

	dstObject := srcObject + "-copy"
	src := client.Bucket(srcBucket).Object(srcObject)
	dst := client.Bucket(dstBucket).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).Run(ctx); err != nil {
		return fmt.Errorf("Object(%q).CopierFrom(%q).Run: %w", dstObject, srcObject, err)
	}
	fmt.Fprintf(w, "Blob %v in bucket %v copied to blob %v in bucket %v.\n", srcObject, srcBucket, dstObject, dstBucket)
	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.BlobInfo;
import com.google.cloud.storage.CopyWriter;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.Storage.CopyRequest;
import com.google.cloud.storage.StorageOptions;

public class CopyObject {
  public static void copyObject(
      String projectId, String sourceBucketName, String objectName, String targetBucketName)
      throws Exception {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of the bucket the original object is in
    // String sourceBucketName = "your-source-bucket";

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

    // The ID of the bucket to copy the object to
    // String targetBucketName = "target-object-bucket";

    try (Storage storage =
        StorageOptions.newBuilder().setProjectId(projectId).build().getService()) {
      BlobId sourceId = BlobId.of(sourceBucketName, objectName);
      // you could change "objectName" to rename the object
      BlobId targetId = BlobId.of(targetBucketName, objectName);

      // Recommended: 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;
      BlobInfo existingTarget = storage.get(targetBucketName, objectName);
      if (existingTarget == 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(existingTarget.getGeneration());
      }

      CopyRequest copyRequest =
          CopyRequest.newBuilder()
              .setSource(sourceId)
              .setTarget(targetId, precondition)
              // limit the number of bytes Cloud Storage will attempt to copy before responding to
              // an individual request.
              // If you see Read Timeout errors, try reducing this value.
              .setMegabytesCopiedPerChunk(2048L) // 2GiB
              .build();
      CopyWriter copyWriter = storage.copy(copyRequest);
      BlobInfo successfulCopyResult = copyWriter.getResult();

      System.out.printf(
          "Copied object gs://%s/%s to %s%n",
          sourceBucketName,
          objectName,
          successfulCopyResult.getBlobId().toGsUtilUriWithGeneration());
    }
  }
}

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 the bucket the original file is in
// const srcBucketName = 'your-source-bucket';

// The ID of the GCS file to copy
// const srcFilename = 'your-file-name';

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

// The ID of the GCS file to create
// const destFileName = 'target-file-name';

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

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

async function copyFile() {
  const copyDestination = storage.bucket(destBucketName).file(destFileName);

  // 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,
    },
  };

  // Copies the file to the other bucket
  await storage
    .bucket(srcBucketName)
    .file(srcFilename)
    .copy(copyDestination, copyOptions);

  console.log(
    `gs://${srcBucketName}/${srcFilename} copied to gs://${destBucketName}/${destFileName}`
  );
}

copyFile().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 an object to a new name and/or bucket.
 *
 * @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 $newBucketName The destination bucket name.
 *        (e.g. 'my-other-bucket')
 * @param string $newObjectName The destination object name.
 *        (e.g. 'my-other-object')
 */
function copy_object(string $bucketName, string $objectName, string $newBucketName, string $newObjectName): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $object = $bucket->object($objectName);
    $object->copy($newBucketName, ['name' => $newObjectName]);
    printf('Copied gs://%s/%s to gs://%s/%s' . PHP_EOL,
        $bucketName, $objectName, $newBucketName, $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_blob(
    bucket_name, blob_name, destination_bucket_name, destination_blob_name,
):
    """Copies a blob from one bucket to another with a new name."""
    # bucket_name = "your-bucket-name"
    # blob_name = "your-object-name"
    # destination_bucket_name = "destination-bucket-name"
    # destination_blob_name = "destination-object-name"

    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.
    # There is also an `if_source_generation_match` parameter, which is not used in this example.
    destination_generation_match_precondition = 0

    blob_copy = source_bucket.copy_blob(
        source_blob, destination_bucket, destination_blob_name, if_generation_match=destination_generation_match_precondition,
    )

    print(
        "Blob {} in bucket {} copied to blob {} in bucket {}.".format(
            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 source_bucket_name:, source_file_name:, 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 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
  bucket  = storage.bucket source_bucket_name, skip_lookup: true
  file    = bucket.file source_file_name

  destination_bucket = storage.bucket destination_bucket_name
  destination_file   = file.copy destination_bucket.name, destination_file_name

  puts "#{file.name} in #{bucket.name} copied to " \
       "#{destination_file.name} in #{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/storage/v1/b/SOURCE_BUCKET_NAME/o/SOURCE_OBJECT_NAME/rewriteTo/b/DESTINATION_BUCKET_NAME/o/NAME_OF_COPY"

   Onde:

   • SOURCE_BUCKET_NAME é o nome do contentor que contém o objeto que quer copiar. Por exemplo, my-bucket.
   • SOURCE_OBJECT_NAME é o nome com codificação URL do objeto que quer copiar. Por exemplo, pets/dog.png, URL codificado como pets%2Fdog.png.
   • DESTINATION_BUCKET_NAME é o nome do contentor onde quer copiar o objeto. Por exemplo, another-bucket.
   • NAME_OF_COPY é o nome codificado em URL que quer dar à cópia do seu objeto. Por exemplo, shiba.png.

   Uma vez que o método rewrite copia os dados em blocos de tamanho limitado, a sua cópia pode exigir vários pedidos, especialmente para objetos grandes.

   Por exemplo, a seguinte resposta a um pedido rewrite indica que tem de fazer pedidos rewrite adicionais:

   {
     "kind": "storage#rewriteResponse",
     "totalBytesRewritten": 1048576,
     "objectSize": 10000000000,
     "done": false,
     "rewriteToken": TOKEN_VALUE
   }

3. Use o rewriteToken num pedido subsequente para continuar a copiar dados:

   curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Length: 0" \
    -d '{"rewriteToken": "TOKEN_VALUE"}' \
    "https://storage.googleapis.com/storage/v1/b/SOURCE_BUCKET_NAME/o/SOURCE_OBJECT_NAME/rewriteTo/b/DESTINATION_BUCKET_NAME/o/NAME_OF_COPY"

   Onde:

   • TOKEN_VALUE é o valor rewriteToken devolvido no pedido anterior.
   • Todos os outros valores correspondem aos usados no pedido anterior.

   Quando o objeto é totalmente copiado, a última resposta tem uma propriedade done definida como true, não existe uma propriedade rewriteToken e os metadados da cópia estão incluídos na propriedade resource.

   {
    "kind": "storage#rewriteResponse",
    "totalBytesRewritten": 10000000000,
    "objectSize": 10000000000,
    "done": true,
    "resource": objects Resource
   }

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: SOURCE_BUCKET_NAME/SOURCE_OBJECT_NAME" \
     "https://storage.googleapis.com/DESTINATION_BUCKET_NAME/NAME_OF_COPY"

   Onde:

   • SOURCE_BUCKET_NAME é o nome do contentor que contém o objeto que quer copiar. Por exemplo, my-bucket.
   • SOURCE_OBJECT_NAME é o nome do objeto que quer copiar. Por exemplo, pets/dog.png.
   • DESTINATION_BUCKET_NAME é o nome do contentor onde quer copiar o objeto. Por exemplo, another-bucket.
   • NAME_OF_COPY é o nome codificado em URL que quer dar à cópia do seu objeto. Por exemplo, shiba.png.

Mova ou mude o nome de objetos copiando-os

Esta secção descreve como mover ou mudar o nome de objetos através de operações de cópia de objetos subjacentes. As ferramentas descritas nesta secção movem e mudam o nome de objetos copiando o objeto original para outro espaço de nomes e, em seguida, eliminando o objeto original.

Nota: se estiver a mover um objeto com mais de 2 GB entre diferentes regiões ou classes de armazenamento, recomendamos que use a CLI gcloud para um desempenho ideal.

Consola

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 que quer mover.

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

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

4. Clique no menu Adicional de objetos () associado ao objeto.

5. Se quiser atribuir um novo nome ao objeto no mesmo contentor, clique em Mudar o nome.

   1. Na janela de sobreposição apresentada, introduza um novo nome para o objeto.

   2. Clique em Mudar o nome.

6. Se quiser mover o objeto para um contentor diferente, clique em Mover.

   1. Na janela de sobreposição apresentada, clique em Procurar.

   2. Selecione o destino do objeto que está a mover.

   3. Clique em Selecionar.

   4. Clique em Mover.

Para saber como obter informações detalhadas sobre erros relativos a operações do Cloud Storage falhadas na Google Cloud consola, consulte a secção Resolução de problemas.

Linha de comandos

Use o comando gcloud storage mv:

gcloud storage mv gs://SOURCE_BUCKET_NAME/SOURCE_OBJECT_NAME gs://DESTINATION_BUCKET_NAME/DESTINATION_OBJECT_NAME

Onde:

• SOURCE_BUCKET_NAME é o nome do contentor que contém o objeto que quer mover ou mudar o nome. Por exemplo, my-bucket.
• SOURCE_OBJECT_NAME é o nome do objeto que quer mover ou mudar o nome. Por exemplo, pets/dog.png.
• DESTINATION_BUCKET_NAME é o nome do contentor para o qual quer mover o objeto. Por exemplo, another-bucket.
• DESTINATION_OBJECT_NAME é o nome que quer que o objeto tenha após a movimentação ou a mudança de nome. Por exemplo, shiba.png.

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

Copying gs://example-bucket/old-file.txt to gs://new-bucket/new-file.txt
Removing gs://example-bucket/old-file.txt...
  Completed files 1/1 | 164.3kiB/164.3kiB 

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& bucket_name,
   std::string const& old_object_name, std::string const& new_object_name) {
  StatusOr<gcs::ObjectMetadata> metadata = client.RewriteObjectBlocking(
      bucket_name, old_object_name, bucket_name, new_object_name);
  if (!metadata) throw std::move(metadata).status();

  google::cloud::Status status =
      client.DeleteObject(bucket_name, old_object_name);
  if (!status.ok()) throw std::runtime_error(status.message());

  std::cout << "Renamed " << old_object_name << " to " << new_object_name
            << " 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 MoveFileSample
{
    public void MoveFile(
        string sourceBucketName = "your-unique-bucket-name",
        string sourceObjectName = "your-object-name",
        string targetBucketName = "target-object-bucket",
        string targetObjectName = "target-object-name")
    {
        var storage = StorageClient.Create();
        storage.CopyObject(sourceBucketName, sourceObjectName, targetBucketName, targetObjectName);
        storage.DeleteObject(sourceBucketName, sourceObjectName);
        Console.WriteLine($"Moved {sourceObjectName} to {targetObjectName}.");
    }
}

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

// moveFile moves an object into another location.
func moveFile(w io.Writer, bucket, object string) error {
	// bucket := "bucket-name"
	// object := "object-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()

	dstName := object + "-rename"
	src := client.Bucket(bucket).Object(object)
	dst := client.Bucket(bucket).Object(dstName)

	// Optional: set a generation-match precondition to avoid potential race
	// conditions and data corruptions. The request to copy the file 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).Run(ctx); err != nil {
		return fmt.Errorf("Object(%q).CopierFrom(%q).Run: %w", dstName, object, err)
	}
	if err := src.Delete(ctx); err != nil {
		return fmt.Errorf("Object(%q).Delete: %w", object, err)
	}
	fmt.Fprintf(w, "Blob %v moved to %v.\n", object, dstName)
	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.Blob;
import com.google.cloud.storage.BlobId;
import com.google.cloud.storage.BlobInfo;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class CopyDeleteObject {
  public static void copyDeleteObject(
      String projectId,
      String sourceBucketName,
      String sourceObjectName,
      String targetBucketName,
      String targetObjectName) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

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

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

    // The ID of the bucket to move the object objectName to
    // String targetBucketName = "target-object-bucket"

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

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    BlobId source = BlobId.of(sourceBucketName, sourceObjectName);
    BlobId target = BlobId.of(targetBucketName, targetObjectName);

    // 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;
    BlobInfo existingTarget = storage.get(targetBucketName, targetObjectName);
    if (existingTarget == 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(existingTarget.getGeneration());
    }

    // Copy source object to target object
    storage.copy(
        Storage.CopyRequest.newBuilder().setSource(source).setTarget(target, precondition).build());
    Blob copiedObject = storage.get(target);
    // Delete the original blob now that we've copied to where we want it, finishing the "move"
    // operation
    storage.get(source).delete();

    System.out.println(
        "Moved object "
            + sourceObjectName
            + " from bucket "
            + sourceBucketName
            + " to "
            + targetObjectName
            + " in bucket "
            + copiedObject.getBucket());
  }
}

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-source-bucket';

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

// The new ID for your GCS file
// const destFileName = 'your-new-file-name';

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

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

async function moveFile() {
  // 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 moveOptions = {
    preconditionOpts: {
      ifGenerationMatch: destinationGenerationMatchPrecondition,
    },
  };

  // Moves the file within the bucket
  await storage
    .bucket(bucketName)
    .file(srcFileName)
    .move(destFileName, moveOptions);

  console.log(
    `gs://${bucketName}/${srcFileName} moved to gs://${bucketName}/${destFileName}`
  );
}

moveFile().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;

/**
 * Move an object to a new name and/or bucket.
 *
 * @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 $newBucketName the destination bucket name.
 *        (e.g. 'my-other-bucket')
 * @param string $newObjectName the destination object name.
 *        (e.g. 'my-other-object')
 */
function move_object(string $bucketName, string $objectName, string $newBucketName, string $newObjectName): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $object = $bucket->object($objectName);
    $object->copy($newBucketName, ['name' => $newObjectName]);
    $object->delete();
    printf('Moved gs://%s/%s to gs://%s/%s' . PHP_EOL,
        $bucketName,
        $objectName,
        $newBucketName,
        $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 move_blob(bucket_name, blob_name, destination_bucket_name, destination_blob_name,):
    """Moves a blob from one bucket to another with a new name."""
    # The ID of your GCS bucket
    # bucket_name = "your-bucket-name"
    # The ID of your GCS object
    # blob_name = "your-object-name"
    # The ID of the bucket to move the object to
    # destination_bucket_name = "destination-bucket-name"
    # The ID of your new GCS object (optional)
    # destination_blob_name = "destination-object-name"

    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 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.
    # There is also an `if_source_generation_match` parameter, which is not used in this example.
    destination_generation_match_precondition = 0

    blob_copy = source_bucket.copy_blob(
        source_blob, destination_bucket, destination_blob_name, if_generation_match=destination_generation_match_precondition,
    )
    source_bucket.delete_blob(blob_name)

    print(
        "Blob {} in bucket {} moved to blob {} in bucket {}.".format(
            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 move_file bucket_name:, file_name:, new_name:
  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"

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

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

  require "google/cloud/storage"

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

  renamed_file = file.copy new_name

  file.delete

  puts "#{file_name} has been renamed to #{renamed_file.name}"
end

APIs REST

API JSON

Para obter instruções da API JSON sobre como mover ou mudar o nome de objetos copiando-os, consulte o artigo Copiar objetos.

API XML

Para ver instruções da API XML sobre como mover ou mudar o nome de objetos copiando-os, consulte o artigo Copiar objetos.

Mude o nome dos objetos de forma atómica

Esta secção descreve como mudar o nome de objetos de forma atómica num contentor. Para mudar o nome de um objeto, pode usar o método Objects: move na API JSON do Cloud Storage.

APIs REST

API JSON

Para mudar o nome de um objeto de forma atómica, faça o seguinte:

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 Objects: move:

   curl -X POST 
   
       -H "Authorization: Bearer $(gcloud auth print-access-token)" 
   
       -H "Content-Length: 0" 
   
       "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/SOURCE_OBJECT_NAME/moveTo/o/DESTINATION_OBJECT_NAME"

   Onde:

   • BUCKET_NAME é o nome do contentor que contém o objeto cujo nome quer mudar. Por exemplo, my-bucket.
   • SOURCE_OBJECT_NAME é o nome codificado por URL do objeto cujo nome quer mudar. Por exemplo, pets/dog.png, URL codificado como pets%2Fdog.png.
   • DESTINATION_OBJECT_NAME é o nome codificado em URL que quer usar. Por exemplo, pets/cat.png, URL codificado como pets%2Fcat.png.

O que se segue?

• Altere a classe de armazenamento de um objeto.
• Edite os metadados de um objeto.
• Torne os objetos e os contentores acessíveis publicamente.
• Saiba mais acerca dos requisitos de nomenclatura de objetos.
• Saiba como usar pré-condições de pedidos para evitar condições de concorrência.