Alterar classes de armazenamento de objetos

Nesta página, você aprenderá a alterar a classe de armazenamento de objetos de um bucket por meio da reescrita do objeto.

Permissões necessárias

Console

As classes de armazenamento de objetos individuais não podem ser definidas no Console do Google Cloud. Em vez disso, use o Google Cloud CLI.

Linha de comando

Para concluir este guia usando um utilitário de linha de comando, você precisa ter as permissões de IAM adequadas. Se o objeto que você quer acessar existir em um projeto que você não criou, talvez seja necessário que o proprietário do projeto conceda a você um papel que contenha as permissões necessárias.

Para uma lista de permissões necessárias para ações específicas, consulte Permissões do IAM para comandos gcloud storage.

Para ver a lista de papéis relevantes, consulte Papéis do Cloud Storage. Como alternativa, é possível criar um papel personalizado que tenha permissões mais limitadas.

Bibliotecas de cliente

Para concluir este guia usando as bibliotecas de cliente do Cloud Storage, é preciso ter as permissões de IAM adequadas. Se o objeto que você quer acessar existir em um projeto que você não criou, talvez seja necessário que o proprietário do projeto conceda a você um papel que contenha as permissões necessárias.

A menos que indicado de outra forma, as solicitações da biblioteca de cliente são feitas por meio da API JSON e exigem permissões conforme listado em Permissões do IAM para métodos JSON. Para conferir quais métodos da API JSON são invocados ao fazer solicitações usando uma biblioteca de cliente, registre as solicitações brutas.

Para conferir a lista de papéis do IAM relevantes, consulte Papéis do Cloud Storage. Como alternativa, é possível criar um papel personalizado que tenha permissões mais limitadas.

APIs REST

API JSON

Para concluir este guia usando a API JSON, é preciso ter as permissões do IAM adequadas. Se o objeto que você quer acessar existir em um projeto que você não criou, talvez seja necessário que o proprietário do projeto conceda a você um papel que contenha as permissões necessárias.

Para uma lista de permissões necessárias para ações específicas, consulte Permissões do IAM para métodos JSON.

Para ver a lista de papéis relevantes, consulte Papéis do Cloud Storage. Como alternativa, é possível criar um papel personalizado que tenha permissões mais limitadas.

Alterar a classe de armazenamento de um objeto

Conclua as seguintes etapas para alterar a classe de armazenamento de um objeto:

Console

As classes de armazenamento de objetos individuais não podem ser definidas no Console do Google Cloud. Em vez disso, use o Google Cloud CLI.

Linha de comando

Use o comando gcloud storage objects update com a flag --storage-class. Exemplo:

gcloud storage objects update gs://BUCKET_NAME/OBJECT_NAME --storage-class=STORAGE_CLASS

Em que:

  • BUCKET_NAME é o nome do bucket que contém o objeto com a classe que você quer alterar. Por exemplo, my-bucket.
  • OBJECT_NAME é o nome do objeto da classe que você quer alterar. Por exemplo, pets/dog.png.
  • STORAGE_CLASS é a nova classe de armazenamento do objeto. Por exemplo, nearline.

Bibliotecas de cliente

C++

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

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

namespace gcs = ::google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& object_name, std::string const& storage_class) {
  StatusOr<gcs::ObjectMetadata> object_metadata =
      client.RewriteObjectBlocking(
          bucket_name, object_name, bucket_name, object_name,
          gcs::WithObjectMetadata(
              gcs::ObjectMetadata().set_storage_class(storage_class)));
  if (!object_metadata) throw std::move(object_metadata).status();

  std::cout << "Changed storage class of object " << object_metadata->name()
            << " in bucket " << object_metadata->bucket() << " to "
            << object_metadata->storage_class() << "\n";
}

C#

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

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


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

public class ChangeFileStorageClassSample
{
    public Google.Apis.Storage.v1.Data.Object ChangeFileStorageClass(
        string bucketName = "your-bucket-name",
        string objectName = "your-object-name",
        string storageClass = StorageClasses.Standard)
    {
        var storage = StorageClient.Create();

        // Changing storage class requires a rewrite operation, which can only be done
        // by the underlying service
        var obj = new Google.Apis.Storage.v1.Data.Object { StorageClass = storageClass };
        storage.Service.Objects.Rewrite(obj, bucketName, objectName, bucketName, objectName).Execute();

        var file = storage.GetObject(bucketName, objectName);
        Console.WriteLine($"Object {objectName} in bucket {bucketName} had" +
            $" its storage class set to {storageClass}.");

        return file;
    }
}

Go

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

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

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

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

// changeObjectStorageClass changes the storage class of a single object.
func changeObjectStorageClass(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()

	o := client.Bucket(bucket).Object(object)

	// 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.
	attrs, err := o.Attrs(ctx)
	if err != nil {
		return fmt.Errorf("object.Attrs: %w", err)
	}
	o = o.If(storage.Conditions{GenerationMatch: attrs.Generation})

	// See the StorageClass documentation for other valid storage classes:
	// https://cloud.google.com/storage/docs/storage-classes
	newStorageClass := "COLDLINE"
	// You can't change an object's storage class directly, the only way is
	// to rewrite the object with the desired storage class.
	copier := o.CopierFrom(o)
	copier.StorageClass = newStorageClass
	if _, err := copier.Run(ctx); err != nil {
		return fmt.Errorf("copier.Run: %w", err)
	}
	fmt.Fprintf(w, "Object %v in bucket %v had its storage class set to %v\n", object, bucket, newStorageClass)
	return nil
}

Java

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

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

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.StorageClass;
import com.google.cloud.storage.StorageOptions;

public class ChangeObjectStorageClass {
  public static void changeObjectStorageClass(
      String projectId, String bucketName, String objectName) {
    // 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";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    BlobId blobId = BlobId.of(bucketName, objectName);
    Blob sourceBlob = storage.get(blobId);
    if (sourceBlob == null) {
      System.out.println("The object " + objectName + " wasn't found in " + bucketName);
      return;
    }

    // See the StorageClass documentation for other valid storage classes:
    // https://googleapis.dev/java/google-cloud-clients/latest/com/google/cloud/storage/StorageClass.html
    StorageClass storageClass = StorageClass.COLDLINE;

    // You can't change an object's storage class directly, the only way is to rewrite the object
    // with the desired storage class

    BlobInfo targetBlob = BlobInfo.newBuilder(blobId).setStorageClass(storageClass).build();

    // Optional: set a generation-match precondition to avoid potential race
    // conditions and data corruptions. The request to upload returns a 412 error if
    // the object's generation number does not match your precondition.
    Storage.BlobSourceOption precondition =
        Storage.BlobSourceOption.generationMatch(sourceBlob.getGeneration());

    Storage.CopyRequest request =
        Storage.CopyRequest.newBuilder()
            .setSource(blobId)
            .setSourceOptions(precondition) // delete this line to run without preconditions
            .setTarget(targetBlob)
            .build();
    Blob updatedBlob = storage.copy(request).getResult();

    System.out.println(
        "Object "
            + objectName
            + " in bucket "
            + bucketName
            + " had its storage class set to "
            + updatedBlob.getStorageClass().name());
  }
}

Node.js

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

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

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

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

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

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

// The name of a storage class
// See the StorageClass documentation for other valid storage classes:
// https://googleapis.dev/java/google-cloud-clients/latest/com/google/cloud/storage/StorageClass.html
// const storageClass = 'coldline';

async function fileChangeStorageClass() {
  // 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 setStorageClassOptions = {
    ifGenerationMatch: generationMatchPrecondition,
  };

  await storage
    .bucket(bucketName)
    .file(fileName)
    .setStorageClass(storageClass, setStorageClassOptions);

  console.log(`${fileName} has been set to ${storageClass}`);
}

fileChangeStorageClass().catch(console.error);

PHP

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

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

use Google\Cloud\Storage\StorageClient;

/**
 * Change the storage class of the given file.
 *
 * @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 $storageClass The storage class of the new object.
 *        (e.g. 'COLDLINE')
 */
function change_file_storage_class(string $bucketName, string $objectName, string $storageClass): void
{
    $storage = new StorageClient();
    $bucket = $storage->bucket($bucketName);
    $object = $bucket->object($objectName);

    // Storage class cannot be changed directly. But we can rewrite the object
    // using the new storage class.

    $newObject = $object->rewrite($bucket, [
        'storageClass' => $storageClass,
    ]);

    printf(
        'Object %s in bucket %s had its storage class set to %s',
        $objectName,
        $bucketName,
        $newObject->info()['storageClass']
    );
}

Python

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

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

from google.cloud import storage

def change_file_storage_class(bucket_name, blob_name):
    """Change the default storage class of the blob"""
    # bucket_name = "your-bucket-name"
    # blob_name = "your-object-name"

    storage_client = storage.Client()

    bucket = storage_client.bucket(bucket_name)
    blob = bucket.blob(blob_name)
    generation_match_precondition = None

    # 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.
    blob.reload()  # Fetch blob metadata to use in generation_match_precondition.
    generation_match_precondition = blob.generation

    blob.update_storage_class("NEARLINE", if_generation_match=generation_match_precondition)

    print(
        "Blob {} in bucket {} had its storage class set to {}".format(
            blob_name,
            bucket_name,
            blob.storage_class
        )
    )
    return blob

Ruby

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

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

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

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

  require "google/cloud/storage"

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

  file = bucket.file file_name

  file.storage_class = "NEARLINE"

  puts "File #{file_name} in bucket #{bucket_name} had its storage class set to #{file.storage_class}"
end

APIs REST

API JSON

  1. Receba um token de acesso de autorização do OAuth 2.0 Playground. Configure o Playground para usar suas credenciais do OAuth. Para ver instruções, consulte Autenticação de APIs.
  2. Crie um arquivo JSON com as informações a seguir:

    {
      "storageClass": "STORAGE_CLASS"
    }

    Em que:

  3. Use cURL (em inglês) para chamar a API JSON com uma solicitação de objeto POST:

    curl -X POST --data-binary @JSON_FILE_NAME \
      -H "Authorization: Bearer OAUTH2_TOKEN" \
      -H "Content-Type: application/json" \
      "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME/rewriteTo/b/BUCKET_NAME/o/OBJECT_NAME"

    Em que:

    • JSON_FILE_NAME é o caminho para o arquivo JSON criado na Etapa 2.
    • OAUTH2_TOKEN é o token de acesso gerado na Etapa 1.
    • BUCKET_NAME é o nome do bucket que contém o objeto original. Por exemplo, my-bucket.
    • OBJECT_NAME é o nome codificado por URL do objeto. Por exemplo, pets/dog.png, codificado em URL como pets%2Fdog.png.

API XML

  1. Receba um token de acesso de autorização do OAuth 2.0 Playground. Configure o Playground para usar suas credenciais do OAuth. Para ver instruções, consulte Autenticação de APIs.
  2. Use cURL (em inglês) para chamar a API XML com uma solicitação de objeto PUT:

    curl -X PUT --data-binary @OBJECT \
      -H "Authorization: Bearer OAUTH2_TOKEN" \
      -H "Content-Type: OBJECT_CONTENT_TYPE" \
      -H "x-goog-storage-class: STORAGE_CLASS" \
      "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"

    Em que:

    • OBJECT é o caminho local para o objeto da classe de armazenamento que você quer alterar. É necessário fazer novamente o upload do objeto ao alterar a classe de armazenamento com a API XML. Por exemplo, Desktop/dog.png.
    • OAUTH2_TOKEN é o token de acesso gerado na etapa 1;
    • OBJECT_CONTENT_TYPE é o tipo de conteúdo do objeto. Por exemplo, image/png.
    • STORAGE_CLASS é a nova classe de armazenamento do objeto. Por exemplo, nearline.
    • BUCKET_NAME é o nome do bucket que contém o objeto que você está reescrevendo. Por exemplo, my-bucket.
    • OBJECT_NAME é o nome codificado por URL do objeto que você está reescrevendo. Por exemplo, pets/dog.png, codificado em URL como pets%2Fdog.png.

A seguir