Cambiar las clases de almacenamiento de los objetos

En esta página, se describe cómo cambiar la clase de almacenamiento de los objetos dentro de un bucket mediante la reescritura del objeto.

• Para aprender a cambiar las clases de almacenamiento de objetos sin reescribir un objeto, consulta la función Administración del ciclo de vida de los objetos.
• Para obtener información sobre cómo Cloud Storage puede administrar automáticamente las clases de almacenamiento de tu objeto, consulta la función Clase automática.

Roles obligatorios

Para obtener los permisos necesarios para cambiar la clase de almacenamiento de un objeto a través de la reescritura del objeto, pídele a tu administrador que te otorgue el rol de usuario de objetos de almacenamiento (roles/storage.objectUser) en el bucket.

Este rol contiene los permisos necesarios para cambiar la clase de almacenamiento de un objeto. Para ver los permisos exactos que son necesarios, expande la sección Permisos necesarios:

Permisos necesarios

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

También puedes obtener estos permisos con otros roles predefinidos o roles personalizados.

Para obtener instrucciones para otorgar roles a los buckets, consulta Usa IAM con buckets.

Cambia la clase de almacenamiento de un objeto

Completa los siguientes pasos para cambiar la clase de almacenamiento de un objeto:

Console

Las clases de almacenamiento de objetos individuales no se pueden configurar a través de la consola de Google Cloud. En su lugar, usa Google Cloud CLI.

Línea de comandos

Usa el comando gcloud storage objects update con la marca --storage-class. Por ejemplo:

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

Aquí:

• BUCKET_NAME es el nombre del bucket que contiene el objeto cuya clase deseas cambiar. Por ejemplo, my-bucket.
• OBJECT_NAME es el nombre del objeto al que le quieres cambiar la clase. Por ejemplo, pets/dog.png
• STORAGE_CLASS es la clase de almacenamiento nueva del objeto. Por ejemplo, nearline.

Bibliotecas cliente

C++

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage C++.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo 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#

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage C#.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo 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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Go.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo 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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Java.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo 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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Node.js.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo 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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage PHP.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo 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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Python.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo 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

Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Ruby.

Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo 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

API de REST

API de JSON

Precaución: Las LCA del objeto original que deseas conservar deben incluirse en el recurso de objeto que proporcionas en el cuerpo de la solicitud.

1. Tener la gcloud CLI instalada e inicializadaa fin de generar un token de acceso para el encabezado Authorization.

   Como alternativa, puedes crear un token de acceso con OAuth 2.0 Playground y, luego, incluirlo en el encabezado Authorization.

2. Crea un archivo JSON que contenga la siguiente información:

   {
     "storageClass": "STORAGE_CLASS"
   }

   Aquí:

   • STORAGE_CLASS es la clase de almacenamiento nueva del objeto. Por ejemplo, nearline.

3. Usa cURL para llamar a la API de JSON con una solicitud de objeto POST:

   curl -X POST --data-binary @JSON_FILE_NAME \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME/rewriteTo/b/BUCKET_NAME/o/OBJECT_NAME"

   Aquí:

   • JSON_FILE_NAME es la ruta de acceso del archivo JSON que creaste en el paso 2.
   • BUCKET_NAME es el nombre del bucket que contiene el objeto original. Por ejemplo, my-bucket.
   • OBJECT_NAME es el nombre codificado en URL del objeto. Por ejemplo, pets/dog.png, codificado en URL como pets%2Fdog.png.

API de XML

Precaución: Los metadatos del objeto original que deseas conservar, como los metadatos personalizados, deben incluirse en los encabezados que proporciones en la solicitud. Además, todas las LCA del objeto que difieran de las LCA del objeto predeterminado del depósito que las contiene deben volver a aplicarse después de que se suba el objeto.

1. Tener la gcloud CLI instalada e inicializadaa fin de generar un token de acceso para el encabezado Authorization.

   Como alternativa, puedes crear un token de acceso con OAuth 2.0 Playground y, luego, incluirlo en el encabezado Authorization.

2. Usa cURL para llamar a la API de XML con una solicitud de objeto PUT:

   curl -X PUT --data-binary @OBJECT \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: OBJECT_CONTENT_TYPE" \
     -H "x-goog-storage-class: STORAGE_CLASS" \
     "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"

   Aquí:

   • OBJECT es la ruta de acceso local al objeto del que quieres cambiar la clase de almacenamiento (debes volver a subir el objeto cuando cambies la clase de almacenamiento con la API de XML). Por ejemplo, Desktop/dog.png
   • OBJECT_CONTENT_TYPE es el tipo de contenido del objeto. Por ejemplo, image/png.
   • STORAGE_CLASS es la clase de almacenamiento nueva del objeto. Por ejemplo, nearline.
   • BUCKET_NAME es el nombre del bucket que contiene el objeto que reescribes. Por ejemplo, my-bucket.
   • OBJECT_NAME es el nombre codificado en URL del objeto que deseas volver a escribir. Por ejemplo, pets/dog.png, codificado en URL como pets%2Fdog.png.

Nota: En esta guía, se explica cómo volver a escribir los datos, que es una operación de clase A y que puede generar cargos adicionales según la antigüedad, la ubicación y la clase de almacenamiento de los datos. Para obtener más información, consulta los Precios de Cloud Storage. Además, ten en cuenta que si habilitaste el Control de versiones de objetos para tu bucket, el objeto original permanecerá en él hasta que se borre de forma explícita.

¿Qué sigue?

• Obtén información sobre las clases de almacenamiento disponibles.
• Cambia las clases de almacenamiento de los objetos con la administración del ciclo de vida de los objetos.
• Explora otras características del ciclo de vida de los datos de Cloud Storage.
• Obtén información sobre los metadatos de los objetos.
• Aprende a usar condiciones previas de solicitud para evitar las condiciones de carrera.