Usa contextos de objetos

Los contextos de objetos son pares clave-valor personalizados que puedes adjuntar a los objetos de Cloud Storage. Puedes usar los contextos de objetos para clasificar datos, hacer un seguimiento de los flujos de trabajo de procesamiento y enriquecer tus objetos con metadatos. Estos contextos persisten cuando copias, redactas o restableces objetos.

En esta página, se describe cómo adjuntar y administrar contextos en objetos de Cloud Storage.

Obtén los roles necesarios

Para obtener los permisos que necesitas para crear y administrar contextos de objetos, pídele a tu administrador que te otorgue los siguientes roles de IAM en el objeto:

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Estos roles predefinidos contienen los permisos necesarios para crear y administrar contextos de objetos. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para crear y administrar contextos de objetos:

  • Crea un objeto con contextos de objeto:
    • storage.objects.create
    • storage.objects.createContext
  • Adjunta, actualiza y borra contextos de objetos:
    • storage.objects.update
    • storage.objects.createContext
    • storage.objects.updateContext
    • storage.objects.deleteContext
  • Contextos de objetos de descarte: storage.objects.dropContexts
  • Visualiza los contextos de objetos:
    • storage.objects.get
    • storage.objects.list
  • Consulta el contexto completo de un objeto, incluidos los datos extendidos (vista previa): storage.objects.viewFullContext

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

Requisitos de nomenclatura para los pares clave-valor

Tanto las claves como los valores de los contextos personalizados deben cumplir con los siguientes requisitos:

  • Debe tener entre 1 y 256 caracteres, inclusive.

  • Debe comenzar con un carácter alfanumérico.

  • Debe ser un carácter UTF-8 válido. Se admiten la mayoría de los caracteres UTF-8, excepto los siguientes:

    • Comilla simple (')

    • Comillas dobles (")

    • Barra invertida (\)

    • Barra diagonal (/)

  • Las claves de contexto que comienzan con el prefijo google: (por ejemplo, google:annotation:face-detector-v1) están reservadas para los contextos generados por Google. No puedes crear contextos nuevos con el prefijo google: ni modificar sus valores. Si intentas hacerlo, Cloud Storage muestra un error INVALID_ARGUMENT. Para quitar contextos con el prefijo google:, debes descartarlos con el parámetro dropContextGroups durante una operación de reescritura.

Adjunta contextos a objetos nuevos

Adjunta contextos a los objetos cuando subas objetos nuevos a los buckets de Cloud Storage. Cada contexto consta de una clave y un valor.

Console

  1. En la consola de Google Cloud , ve a la página Buckets de Cloud Storage.

    Ir a Buckets

  2. Sube el objeto.

  3. Sigue los pasos para adjuntar contextos al objeto.

Línea de comandos

Para adjuntar contextos cuando subas objetos con el comando gcloud storage cp, usa la marca --custom-contexts:

gcloud storage cp OBJECT_LOCATION gs://DESTINATION_BUCKET_NAME --custom-contexts=KEY=VALUE,...

Aquí:

  • OBJECT_LOCATION es la ruta de acceso local a tu objeto. Por ejemplo, Desktop/employees.txt.
  • DESTINATION_BUCKET_NAME es el nombre del bucket al que subes el objeto. Por ejemplo, my-bucket.
  • KEY es la clave de contexto que se adjuntará a un objeto. Por ejemplo, Department Puedes especificar varios pares clave-valor separados por comas.
  • VALUE es el valor que se asociará con la clave de contexto. Por ejemplo, Human resources

Como alternativa, crea un archivo JSON que contenga los contextos que deseas adjuntar a los objetos y usa la marca --custom-contexts-file:

  {
    "KEY": {
      "value": "VALUE"
    },
    ...
  }

Aquí:

  • KEY es la clave de contexto que se adjuntará a un objeto. Por ejemplo, Department Puedes especificar varios pares clave-valor.
  • VALUE es el valor que se asociará con la clave de contexto. Por ejemplo, Human resources

Para adjuntar contextos cuando subes directorios con el comando gcloud storage rsync, usa la marca --custom-contexts o la marca --custom-contexts-file:

gcloud storage rsync DIRECTORY_LOCATION gs://DESTINATION_BUCKET_NAME --recursive --custom-contexts=KEY=VALUE,...

Aquí:

  • DIRECTORY_LOCATION es la ruta de acceso local a tu directorio. Por ejemplo, ~/my_directory
  • DESTINATION_BUCKET_NAME es el nombre del bucket al que subes el directorio. Por ejemplo, my-bucket.
  • KEY es la clave de contexto que se adjuntará a los objetos. Por ejemplo, Department Puedes especificar varios pares clave-valor separados por comas.
  • VALUE es el valor que se asociará con la clave de contexto. Por ejemplo, Human resources

API de JSON

Para adjuntar contextos a objetos cuando subes objetos nuevos, usa cualquiera de los siguientes métodos:

Como parte de los metadatos del objeto en formato JSON, incluye el campo contexts:

  {
    "contexts": {
      "custom": {
        "KEY": {
          "value": "VALUE"
        },
        ...
      }
    }
  }

Aquí:

  • KEY es la clave de contexto que se adjuntará a un objeto. Por ejemplo, Department Puedes especificar varios pares clave-valor en el objeto custom.
  • VALUE es el valor que se asociará con la clave de contexto. Por ejemplo, Human resources

Adjunta o modifica contextos en un objeto existente

Puedes adjuntar contextos nuevos a objetos o actualizar los contextos existentes en los buckets de Cloud Storage.

Solo los servicios de Google, como los trabajos de enriquecimiento de objetos, pueden generar y adjuntar contextos con datos extendidos, que usan el prefijo de clave google: reservado. No puedes adjuntar datos extendidos a contextos definidos por el usuario, ni crear o modificar claves de contexto que comiencen con el prefijo google:. Si intentas crear o modificar claves google:, Cloud Storage devuelve un error INVALID_ARGUMENT.

Si un contexto existente incluye datos extendidos, Cloud Storage conserva ese contexto en el objeto actualizado durante las operaciones de actualización y parche. Si estableces un valor de contexto en null, solo se borrarán los contextos que no tengan datos extendidos. Para ver los datos extendidos, consulta Visualiza el contexto completo del objeto. Para quitar un contexto con datos extendidos, incluidos los contextos con el prefijo google:, debes descartarlo con el parámetro dropContextGroups durante una operación de reescritura.

Console

  1. En la consola de Google Cloud , ve a la página Buckets de Cloud Storage.

    Ir a Buckets

  2. En la lista de buckets, haz clic en el nombre del bucket que contiene el objeto.

  3. Navega al objeto y, luego, haz clic en Abrir el menú ampliado del objeto.

  4. Haz clic en Editar contextos.

  5. En el panel Editar contextos, realiza una de las siguientes acciones:

    • Agrega un nuevo contexto de objeto:

      1. Haz clic en Agregar un contexto personalizado.

      2. En los campos Clave de contexto del objeto y Valor de contexto del objeto, ingresa un nuevo par clave-valor.

      3. Haz clic en Listo.

      4. Opcional: Para agregar contextos de objetos adicionales, haz clic en Agregar un contexto personalizado, repite los pasos anteriores y, luego, haz clic en Guardar.

    • Edita un contexto de objeto:

      1. Haz clic en el contexto del objeto.

      2. Actualiza el campo Clave de contexto del objeto, el campo Valor de contexto del objeto o ambos.

      3. Haz clic en Listo y, luego, en Guardar.

    • Borra un contexto de objeto:

      Haz clic en Borrar y, luego, en Guardar.

Línea de comandos

Usa el comando gcloud storage objects update:

gcloud storage objects update gs://BUCKET_NAME/OBJECT_NAME CUSTOM_CONTEXTS_FLAG

Aquí:

  • BUCKET_NAME es el nombre del bucket que contiene el objeto para el que deseas editar el contexto. Por ejemplo, my-bucket.
  • OBJECT_NAME es el nombre del objeto. Por ejemplo, employees.txt.

  • CUSTOM_CONTEXTS_FLAG es cualquiera de las siguientes marcas:

    • Para reemplazar todos los contextos existentes, usa --custom-contexts=KEY=VALUE,... o --custom-contexts-file=CUSTOM_CONTEXTS_FILE

      Aquí:

      • KEY es la clave de contexto que se adjuntará a un objeto. Por ejemplo, Department Puedes especificar varios pares clave-valor separados por comas.
      • VALUE es el valor que se asociará con la clave de contexto. Por ejemplo, Human resources
      • CUSTOM_CONTEXTS_FILE es la ruta de acceso al archivo JSON o YAML que contiene los contextos que deseas adjuntar al objeto.

    • Para borrar todos los contextos existentes, usa la marca --clear-custom-contexts.

    • Para agregar, modificar o borrar contextos individuales, usa una combinación de --update-custom-contexts=KEY=VALUE,... y --remove-custom-contexts=KEY,....

      Aquí:

      • KEY es la clave de contexto que deseas adjuntar a un objeto o borrar de él. Por ejemplo, Department
      • VALUE es el valor que se asociará con la clave de contexto que deseas adjuntar a un objeto o borrar de él. Por ejemplo, Human resources.

Si se ejecuta de forma correcta, la respuesta se parece al siguiente ejemplo:

Patching gs://my-bucket/employees.txt#1560574162144861...
  Completed 1

Bibliotecas cliente

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 bibliotecas cliente. 


import com.google.cloud.storage.Blob;
import com.google.cloud.storage.BlobId;
import com.google.cloud.storage.BlobInfo;
import com.google.cloud.storage.BlobInfo.ObjectContexts;
import com.google.cloud.storage.BlobInfo.ObjectCustomContextPayload;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import com.google.common.collect.Maps;
import java.util.Map;

public class SetObjectContexts {
  public static void setObjectContexts(
      String projectId, String bucketName, String objectName, String key, String value)
      throws Exception {
    // 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 context key-value you want to add
    // String key = "your-context-key";
    // String value = "your-context-value";

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

      // Recommended: Set a generation-match precondition to avoid potential race
      // conditions and data corruptions. The request to update returns a 412 error if
      // the object's generation number does not match your precondition.
      Storage.BlobTargetOption precondition = Storage.BlobTargetOption.generationMatch();

      // This section demonstrates how to upsert, delete all, and delete a specific context.

      // To upsert a context (if the key already exists, its value is replaced;
      // otherwise, a new key-value pair is added):
      ObjectCustomContextPayload payload =
          ObjectCustomContextPayload.newBuilder().setValue(value).build();
      Map<String, ObjectCustomContextPayload> custom = Maps.newHashMap();
      custom.put(key, payload);
      ObjectContexts contexts = ObjectContexts.newBuilder().setCustom(custom).build();

      /*
       * To delete all existing contexts:
       * ObjectContexts contexts = ObjectContexts.newBuilder().setCustom(null).build();
       */

      /*
       * To delete a specific key from the context:
       * Map<String, ObjectCustomContextPayload> custom = Maps.newHashMap();
       * custom.put(key, null);
       * ObjectContexts contexts = ObjectContexts.newBuilder().setCustom(custom).build();
       */
      BlobInfo pendingUpdate = blob.toBuilder().setContexts(contexts).build();
      storage.update(pendingUpdate, precondition);

      System.out.println(
          "Updated custom contexts for object " + objectName + " in bucket " + bucketName);
    }
  }
}

Rust

use google_cloud_storage::client::StorageControl;
use google_cloud_storage::model::ObjectContexts;
use google_cloud_wkt::FieldMask;

pub async fn sample(client: &StorageControl, bucket_id: &str) -> anyhow::Result<()> {
    const NAME: &str = "object-with-contexts";
    let object = client
        .get_object()
        .set_bucket(format!("projects/_/buckets/{bucket_id}"))
        .set_object(NAME)
        .send()
        .await?;

    let metageneration = object.metageneration;
    let mut custom = object.contexts.clone().unwrap_or_default().custom;
    custom.entry("example".to_string()).or_default().value = "true".into();

    let updated = client
        .update_object()
        .set_if_metageneration_match(metageneration)
        .set_object(object.set_contexts(ObjectContexts::new().set_custom(custom)))
        .set_update_mask(FieldMask::default().set_paths(["contexts.custom.example"]))
        .send()
        .await?;
    println!(
        "successfully set contexts for object {NAME} in bucket {bucket_id}: {:?}",
        updated.contexts
    );
    Ok(())
}

API de JSON

  1. Tener la gcloud CLI instalada e inicializada, lo que te permite generar un token de acceso para el encabezado Authorization.

  2. Crea un archivo JSON que contenga la configuración del objeto, que debe incluir los campos de configuración de contexts para el objeto.

    Para agregar, modificar o reemplazar contextos existentes, usa el siguiente formato:

      {
    "contexts": {
      "custom": {
        "KEY": {
          "value": "VALUE"
        },
        ...
      }
    }
  }

    Aquí:

    • KEY es la clave de contexto que se adjuntará a un objeto. Por ejemplo, Department Puedes especificar varios pares clave-valor en el objeto custom.
    • VALUE es el valor que se asociará con la clave de contexto. Por ejemplo, Human resources.

    Para borrar todos los contextos existentes, usa el siguiente formato:

      {
    "contexts": {
      "custom": null
    }
  }

    Para borrar una clave específica del contexto, usa el siguiente formato:

      {
    "contexts": {
      "custom": {
        "KEY": null,
        ...
      }
    }
  }

    Aquí:

    KEY es la clave de contexto que deseas borrar de un objeto. Por ejemplo, Department Puedes especificar varias claves para borrar del objeto custom.

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

    curl -X PATCH --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"

    Aquí:

    • JSON_FILE_NAME es la ruta de acceso al archivo que incluye la información de los contextos de objetos.
    • BUCKET_NAME es el nombre del bucket que contiene el objeto para el que deseas editar el contexto. Por ejemplo, my-bucket.
    • OBJECT_NAME es el nombre codificado en URL del objeto. Por ejemplo, employees.txt

Como alternativa, puedes reemplazar el contexto de un objeto con una solicitud de objeto PUT. La solicitud de objeto PUT también reemplaza otros metadatos del objeto. Por lo tanto, no recomendamos usar la solicitud de objeto PUT.

Cómo ver los contextos de objetos

Puedes ver los contextos de un objeto enumerando sus metadatos o describiendo un objeto específico.

Console

  1. En la consola de Google Cloud , ve a la página Buckets de Cloud Storage.

    Ir a Buckets

  2. En la lista de buckets, haz clic en el nombre del bucket que contiene el objeto con los contextos que deseas ver.

  3. Navega al objeto y, luego, haz clic en su nombre.

    En la página Detalles del objeto, los pares clave-valor de los contextos adjuntos se enumeran en la sección Contextos del objeto.

Línea de comandos

Usa el comando gcloud storage objects describe:

gcloud storage objects describe gs://BUCKET_NAME/OBJECT_NAME

Aquí:

  • BUCKET_NAME es el nombre del bucket que contiene el objeto. Por ejemplo, my-bucket
  • OBJECT_NAME es el nombre del objeto. Por ejemplo, employees.txt

Si se realiza de forma correcta, la respuesta se verá como el ejemplo siguiente:

bucket: my-bucket
contexts:
  custom:
    Department:
      createTime: '2023-01-01T00:00:00.000000+00:00'
      type: CUSTOM
      updateTime: '2023-01-01T00:00:00.000000+00:00'
      value: Human resources
    google:annotation:face-detector-v1:
      createTime: '2025-09-29T17:20:00.000000+00:00'
      extendedDataTypeUrl: type.googleapis.com/google.protobuf.Struct
      type: CUSTOM
      updateTime: '2025-09-29T17:20:00.000000+00:00'
      value: SUCCESS
name: employees.txt

Bibliotecas cliente

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 bibliotecas cliente. 


import com.google.cloud.storage.Blob;
import com.google.cloud.storage.BlobInfo.ObjectContexts;
import com.google.cloud.storage.BlobInfo.ObjectCustomContextPayload;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import java.util.Map;

public class GetObjectContexts {
  public static void getObjectContexts(String projectId, String bucketName, String objectName)
      throws Exception {
    // 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";

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

      Blob blob = storage.get(bucketName, objectName);
      if (blob == null) {
        System.out.println("The object " + objectName + " was not found in " + bucketName);
        return;
      }
      ObjectContexts objectContexts = blob.getContexts();

      if (objectContexts != null) {
        Map<String, ObjectCustomContextPayload> customContexts = objectContexts.getCustom();
        if (customContexts == null) {
          System.out.println("No custom contexts found for object: " + objectName);
          return;
        }
        // Print blob's object contexts
        System.out.println("\nCustom Contexts:");
        for (Map.Entry<String, ObjectCustomContextPayload> custom : customContexts.entrySet()) {
          System.out.println(custom.getKey() + "=" + custom.getValue());
        }
      }
    }
  }
}

Rust

use google_cloud_storage::client::StorageControl;

pub async fn sample(client: &StorageControl, bucket_id: &str) -> anyhow::Result<()> {
    const NAME: &str = "object-with-contexts";
    let object = client
        .get_object()
        .set_bucket(format!("projects/_/buckets/{bucket_id}"))
        .set_object(NAME)
        .send()
        .await?;
    println!(
        "The contexts field for object {NAME} in bucket {bucket_id} is: {:?}",
        object.contexts
    );
    Ok(())
}

API de JSON

  1. Tener la gcloud CLI instalada e inicializada, lo que te permite generar un token de acceso para el encabezado Authorization.

  2. Usa cURL para llamar a la API de JSON con una solicitud de objeto GET:

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

    Aquí:

    • BUCKET_NAME es el nombre del bucket que contiene el objeto. Por ejemplo, my-bucket
    • OBJECT_NAME es el nombre codificado en URL del objeto. Por ejemplo, employees.txt

    Si se realiza de forma correcta, la respuesta se verá como el ejemplo siguiente:

      {
    "kind": "storage#object",
    "name": "employees.txt",
    "bucket": "my-bucket",
    "contexts": {
      "custom": {
        "Department": {
          "value": "Human resources",
          "createTime": "2023-01-01T00:00:00.000Z",
          "updateTime": "2023-01-01T00:00:00.000Z"
        },
        "google:annotation:face-detector-v1": {
          "value": "SUCCESS",
          "createTime": "2025-09-29T17:20:00.000Z",
          "updateTime": "2025-09-29T17:20:00.000Z",
          "extendedDataTypeUrl": "type.googleapis.com/google.protobuf.Struct"
        }
      }
    }
  }

Ver el contexto completo del objeto

Para ver un solo contexto y sus datos extendidos, usa el método viewFullContext (Preview).

API de JSON

Para recuperar un solo contexto completo (incluidos los datos extendidos) por clave, haz lo siguiente:

  1. Tener la gcloud CLI instalada e inicializada, lo que te permite generar un token de acceso para el encabezado Authorization.

  2. Usa cURL para llamar a la API de JSON con una solicitud GET View Full Context:

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

    Aquí:

    • BUCKET_NAME es el nombre del bucket que contiene el objeto. Por ejemplo, my-bucket
    • OBJECT_NAME es el nombre codificado en URL del objeto. Por ejemplo, employees.txt
    • KEY es la clave de contexto específica que se recuperará. Por ejemplo, google:annotation:face-detector-v1

    Si se realiza de forma correcta, la respuesta se verá como el ejemplo siguiente:

    {
  "kind": "storage#objectFullContext",
  "type": "CUSTOM",
  "key": "google:annotation:face-detector-v1",
  "value": "SUCCESS",
  "createTime": "2025-09-29T17:20:00.000Z",
  "updateTime": "2025-09-29T17:20:00.000Z",
  "extendedData": {
    "@type": "type.googleapis.com/google.protobuf.Struct",
    "value": {
      "modelName": "face-detector",
      "modelVersion": "v1",
      "faceAnnotationGroup": {
        "faceAnnotations": [
          {
            "detectionConfidence": 0.9,
            "landmarkingConfidence": 0.8
          }
        ]
      }
    }
  }
}

Cómo filtrar objetos por contextos

Filtrar objetos por la existencia de claves de contexto de objeto o sus valores específicos Filtrar objetos por contextos ayuda a ubicar y administrar grupos de objetos específicos de manera eficiente. Para obtener más información, consulta Cómo filtrar objetos por contextos.

Administra los contextos de objetos durante las operaciones de objetos

De forma predeterminada, Cloud Storage conserva los contextos de los objetos cuando los copias, reescribes, compones, mueves o restableces.

Cómo copiar objetos

De forma predeterminada, Cloud Storage conserva los contextos de objeto del objeto de origen durante una operación de copia, incluso si anulas otros metadatos. Para modificar los contextos de los objetos durante una operación de copia, completa los siguientes pasos:

Línea de comandos

Los comandos gcloud storage cp, gcloud storage rsync y gcloud storage mv conservan los contextos del objeto fuente de forma predeterminada. Para modificar los contextos durante estas operaciones, usa cualquiera de las siguientes marcas:

  • Es la marca --custom-contexts para establecer contextos nuevos para el objeto de destino.

  • La marca --clear-custom-contexts para evitar que los contextos del objeto de origen se adjunten al objeto de destino.

  • Una combinación de las marcas --update-custom-contexts y --remove-custom-contexts para modificar contextos individuales del objeto de origen antes de adjuntarlos al objeto de destino.

Para establecer contextos nuevos cuando copias un objeto, usa el comando gcloud storage cp:

gcloud storage cp gs://SOURCE_BUCKET_NAME/SOURCE_OBJECT_NAME gs://DESTINATION_BUCKET_NAME/DESTINATION_OBJECT_NAME --custom-contexts=KEY=VALUE,...

Aquí:

  • SOURCE_BUCKET_NAME es el nombre del bucket que contiene el objeto que se copiará. Por ejemplo, my-source-bucket
  • SOURCE_OBJECT_NAME es el nombre del objeto que se copiará. Por ejemplo, employees.txt
  • DESTINATION_BUCKET_NAME es el nombre del bucket en el que se copiará el objeto. Por ejemplo, my-destination-bucket
  • DESTINATION_OBJECT_NAME es el nombre del objeto de destino. Por ejemplo, employees-backup.txt
  • KEY es la clave de contexto que se adjuntará a un objeto. Por ejemplo, Department Puedes especificar varios pares clave-valor separados por comas.
  • VALUE es el valor que se asociará con la clave de contexto. Por ejemplo, Human resources

Para quitar todos los contextos del objeto de origen cuando copias un objeto, usa el comando gcloud storage cp:

gcloud storage cp gs://SOURCE_BUCKET_NAME/SOURCE_OBJECT_NAME gs://DESTINATION_BUCKET_NAME/DESTINATION_OBJECT_NAME --clear-custom-contexts

Aquí:

  • SOURCE_BUCKET_NAME es el nombre del bucket que contiene el objeto que se copiará. Por ejemplo, my-source-bucket
  • SOURCE_OBJECT_NAME es el nombre del objeto que se copiará. Por ejemplo, pets/dog.png
  • DESTINATION_BUCKET_NAME es el nombre del bucket en el que se copiará el objeto. Por ejemplo, my-destination-bucket
  • DESTINATION_OBJECT_NAME es el nombre del objeto de destino. Por ejemplo, pets/cat.png

Para modificar contextos individuales del objeto de origen cuando copias un objeto, usa el comando gcloud storage cp con --update-custom-contexts y --remove-custom-contexts:

gcloud storage cp gs://SOURCE_BUCKET_NAME/SOURCE_OBJECT_NAME gs://DESTINATION_BUCKET_NAME/DESTINATION_OBJECT_NAME --update-custom-contexts=KEY=VALUE,... --remove-custom-contexts=KEY,...

Aquí:

  • SOURCE_BUCKET_NAME es el nombre del bucket que contiene el objeto que se copiará. Por ejemplo, my-source-bucket
  • SOURCE_OBJECT_NAME es el nombre del objeto que se copiará. Por ejemplo, pets/dog.png
  • DESTINATION_BUCKET_NAME es el nombre del bucket en el que se copiará el objeto. Por ejemplo, my-destination-bucket
  • DESTINATION_OBJECT_NAME es el nombre del objeto de destino. Por ejemplo, pets/cat.png
  • KEY es la clave de contexto que se adjuntará a un objeto. Por ejemplo, Department Puedes especificar varios pares clave-valor o claves separados por comas.
  • VALUE es el valor que se asociará con la clave de contexto. Por ejemplo, Human resources

API de JSON

Para anular los contextos cuando copias un objeto, incluye la propiedad contexts.custom en el cuerpo de la solicitud:

  1. Tener la gcloud CLI instalada e inicializada, lo que te permite generar un token de acceso para el encabezado Authorization

  2. Crea un archivo JSON que contenga los contextos que se adjuntarán al objeto de destino:

      {
    "contexts": {
      "custom": {
        "KEY": {
          "value": "VALUE"
        }
      }
    }
  }

    Aquí:

    • KEY es la clave de contexto que se adjuntará a un objeto. Por ejemplo, Department.
    • VALUE es el valor que se asociará con la clave de contexto. Por ejemplo, Human resources.

  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/SOURCE_BUCKET_NAME/o/SOURCE_OBJECT_NAME/copyTo/b/DESTINATION_BUCKET_NAME/o/DESTINATION_OBJECT_NAME"

    Aquí:

    • JSON_FILE_NAME es la ruta de acceso al archivo JSON que incluye la información de los contextos de los objetos.
    • SOURCE_BUCKET_NAME es el nombre del bucket que contiene el objeto que se copiará. Por ejemplo, my-source-bucket.
    • SOURCE_OBJECT_NAME es el nombre codificado como URL del objeto que deseas copiar. Por ejemplo, employees.txt
    • DESTINATION_BUCKET_NAME es el nombre del bucket al que se copiará el objeto. Por ejemplo, my-destination-bucket.
    • DESTINATION_OBJECT_NAME es el nombre codificado en URL del objeto de destino. Por ejemplo, employees-backup.txt

Para descartar los contextos de origen durante una operación de copia, usa el parámetro de consulta dropContextGroups=custom en tu solicitud:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/storage/v1/b/SOURCE_BUCKET_NAME/o/SOURCE_OBJECT_NAME/copyTo/b/DESTINATION_BUCKET_NAME/o/DESTINATION_OBJECT_NAME?dropContextGroups=custom"

Si el cuerpo de la solicitud contiene contextos con el prefijo google:, puedes conservar las claves y los valores existentes del objeto de origen, pero Cloud Storage rechazará las claves google: nuevas o los valores modificados.

Para conservar los contextos, omite la propiedad contexts del cuerpo de la solicitud y excluye el parámetro de consulta dropContextGroups.

Reescribir objetos

De forma predeterminada, Cloud Storage conserva los contextos de objeto del objeto de origen durante una operación de reescritura, incluso si anulas otros metadatos. Para modificar los contextos de objetos durante una operación de reescritura, completa los siguientes pasos:

Línea de comandos

Los comandos gcloud storage cp, gcloud storage rsync y gcloud storage mv realizan reescrituras automáticamente cuando es necesario, por ejemplo, cuando se copian objetos entre diferentes ubicaciones o clases de almacenamiento. gcloud storage cp y gcloud storage rsync generan un objeto de origen y destino, mientras que gcloud storage mv crea el objeto de destino y quita el objeto de origen. Debido a que estas operaciones crean un objeto nuevo, también puedes modificar o adjuntar contextos como parte del mismo comando con cualquiera de las siguientes marcas:

  • La marca --custom-contexts para establecer contextos nuevos para el objeto de destino.

  • La marca --clear-custom-contexts para evitar que los contextos del objeto de origen se adjunten al objeto de destino.

  • Una combinación de las marcas --update-custom-contexts y --remove-custom-contexts para modificar contextos individuales del objeto de origen antes de adjuntarlos al objeto de destino.

Para establecer contextos nuevos cuando copias un objeto, usa el comando gcloud storage cp:

gcloud storage cp gs://SOURCE_BUCKET_NAME/SOURCE_OBJECT_NAME gs://DESTINATION_BUCKET_NAME/DESTINATION_OBJECT_NAME --custom-contexts=KEY=VALUE,...

Aquí:

  • SOURCE_BUCKET_NAME es el nombre del bucket que contiene el objeto que se copiará. Por ejemplo, my-source-bucket
  • SOURCE_OBJECT_NAME es el nombre del objeto que se copiará. Por ejemplo, employees.txt
  • DESTINATION_BUCKET_NAME es el nombre del bucket en el que se copiará el objeto. Por ejemplo, my-destination-bucket
  • DESTINATION_OBJECT_NAME es el nombre del objeto de destino. Por ejemplo, employees-backup.txt
  • KEY es la clave de contexto que se adjuntará a un objeto. Por ejemplo, Department Puedes especificar varios pares clave-valor separados por comas.
  • VALUE es el valor que se asociará con la clave de contexto. Por ejemplo, Human resources

Para quitar todos los contextos del objeto de origen cuando copias un objeto, usa el comando gcloud storage cp:

gcloud storage cp gs://SOURCE_BUCKET_NAME/SOURCE_OBJECT_NAME gs://DESTINATION_BUCKET_NAME/DESTINATION_OBJECT_NAME --clear-custom-contexts

Aquí:

  • SOURCE_BUCKET_NAME es el nombre del bucket que contiene el objeto que se copiará. Por ejemplo, my-source-bucket
  • SOURCE_OBJECT_NAME es el nombre del objeto que se copiará. Por ejemplo, pets/dog.png
  • DESTINATION_BUCKET_NAME es el nombre del bucket en el que se copiará el objeto. Por ejemplo, my-destination-bucket
  • DESTINATION_OBJECT_NAME es el nombre del objeto de destino. Por ejemplo, pets/cat.png

Para modificar contextos individuales del objeto de origen cuando copias un objeto, usa el comando gcloud storage cp con --update-custom-contexts y --remove-custom-contexts:

gcloud storage cp gs://SOURCE_BUCKET_NAME/SOURCE_OBJECT_NAME gs://DESTINATION_BUCKET_NAME/DESTINATION_OBJECT_NAME --update-custom-contexts=KEY=VALUE,... --remove-custom-contexts=KEY,...

Aquí:

  • SOURCE_BUCKET_NAME es el nombre del bucket que contiene el objeto que se copiará. Por ejemplo, my-source-bucket
  • SOURCE_OBJECT_NAME es el nombre del objeto que se copiará. Por ejemplo, pets/dog.png
  • DESTINATION_BUCKET_NAME es el nombre del bucket en el que se copiará el objeto. Por ejemplo, my-destination-bucket
  • DESTINATION_OBJECT_NAME es el nombre del objeto de destino. Por ejemplo, pets/cat.png
  • KEY es la clave de contexto que se adjuntará a un objeto. Por ejemplo, Department Puedes especificar varios pares clave-valor o claves separados por comas.
  • VALUE es el valor que se asociará con la clave de contexto. Por ejemplo, Human resources

API de JSON

Para anular los contextos cuando se reescribe un objeto, incluye la propiedad contexts.custom en el cuerpo de la solicitud:

  1. Tener la gcloud CLI instalada e inicializada, lo que te permite generar un token de acceso para el encabezado Authorization

  2. Crea un archivo JSON que contenga los contextos que se adjuntarán al objeto de destino:

      {
    "contexts": {
      "custom": {
        "KEY": {
          "value": "VALUE"
        }
      }
    }
  }

    Aquí:

    • KEY es la clave de contexto que se adjuntará a un objeto. Por ejemplo: Department.
    • VALUE es el valor que se asociará con la clave de contexto. Por ejemplo: Human resources.

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

    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/SOURCE_BUCKET_NAME/o/SOURCE_OBJECT_NAME/rewriteTo/b/DESTINATION_BUCKET_NAME/o/DESTINATION_OBJECT_NAME"

    Aquí:

    • JSON_FILE_NAME es la ruta de acceso al archivo JSON que incluye la información de los contextos de objetos.
    • SOURCE_BUCKET_NAME es el nombre del bucket que contiene el objeto que se reescribirá. Por ejemplo, my-source-bucket
    • SOURCE_OBJECT_NAME es el nombre codificado en URL del objeto que se volverá a escribir. Por ejemplo, employees.txt
    • DESTINATION_BUCKET_NAME es el nombre del bucket en el que se reescribirá el objeto. Por ejemplo, my-destination-bucket
    • DESTINATION_OBJECT_NAME es el nombre codificado en URL del objeto de destino. Por ejemplo, employees-backup.txt

Para descartar los contextos de origen durante una operación de reescritura, usa el parámetro de consulta dropContextGroups=custom en tu solicitud:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/storage/v1/b/SOURCE_BUCKET_NAME/o/SOURCE_OBJECT_NAME/rewriteTo/b/DESTINATION_BUCKET_NAME/o/DESTINATION_OBJECT_NAME?dropContextGroups=custom"

Si el cuerpo de la solicitud contiene contextos con el prefijo google:, puedes conservar las claves y los valores existentes del objeto de origen, pero Cloud Storage rechazará las claves google: nuevas o los valores modificados.

Para conservar los contextos, omite la propiedad contexts del cuerpo de la solicitud y excluye el parámetro de consulta dropContextGroups.

Redactar objetos

El comando gcloud storage objects compose y el método compose de la API de JSON combinan los contextos de los objetos de origen y los adjuntan a los objetos de destino de forma predeterminada. Cloud Storage resuelve los conflictos priorizando los contextos de los objetos fuente que se procesan más tarde. Para obtener más información sobre el comportamiento del contexto de objetos durante una operación de composición, consulta Contextos de objetos compuestos.

Línea de comandos

Para especificar contextos nuevos para el objeto de destino cuando compones objetos, usa la marca --contexts:

gcloud storage objects compose gs://BUCKET_NAME/SOURCE_OBJECT_1 gs://BUCKET_NAME/SOURCE_OBJECT_2 gs://BUCKET_NAME/DESTINATION_OBJECT_NAME --contexts=KEY=VALUE,...

Aquí:

  • BUCKET_NAME es el nombre del bucket que contiene los objetos de origen y en el que se crea el objeto de destino. Por ejemplo, my-bucket
  • SOURCE_OBJECT_1 y SOURCE_OBJECT_2 son objetos de origen para componer.
  • DESTINATION_OBJECT_NAME es el nombre del objeto de destino que se creará. Por ejemplo, my-composite-object
  • KEY es la clave de contexto que se adjuntará a un objeto. Por ejemplo, Department Puedes especificar varios pares clave-valor separados por comas.
  • VALUE es el valor que se asociará con la clave de contexto. Por ejemplo, Human resources.

Para evitar que los contextos de origen se adjunten a objetos compuestos, usa la marca --clear-custom-contexts:

gcloud storage objects compose gs://BUCKET_NAME/SOURCE_OBJECT_1 gs://BUCKET_NAME/SOURCE_OBJECT_2 gs://BUCKET_NAME/DESTINATION_OBJECT_NAME --clear-custom-contexts

Aquí:

  • BUCKET_NAME es el nombre del bucket que contiene los objetos de origen y en el que se crea el objeto de destino. Por ejemplo, my-bucket
  • SOURCE_OBJECT_1 y SOURCE_OBJECT_2 son los objetos de origen que se deben componer.
  • DESTINATION_OBJECT_NAME es el nombre del objeto de destino que se creará. Por ejemplo, my-composite-object

API de JSON

Para especificar contextos nuevos para el objeto de destino cuando compones objetos, incluye contextos en la propiedad destination del cuerpo de la solicitud.

  1. Tener la gcloud CLI instalada e inicializada, lo que te permite generar un token de acceso para el encabezado Authorization.

  2. Crea un archivo JSON que contenga el cuerpo de la solicitud:

    {
  "sourceObjects": [
    {"name": "SOURCE_OBJECT_1"},
    {"name": "SOURCE_OBJECT_2"}
  ],
  "destination": {
    "contentType": "text/plain",
    "contexts": {
      "custom": {
        "KEY": {
          "value": "VALUE"
        }
      }
    }
  }
}

    Aquí:

    • SOURCE_OBJECT_1 y SOURCE_OBJECT_2 son objetos de origen que se deben componer.
    • KEY es la clave de contexto que se adjuntará a un objeto. Por ejemplo, Department
    • VALUE es el valor que se asociará con la clave de contexto. Por ejemplo, Human resources.

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

    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/DESTINATION_OBJECT_NAME/compose"

    Aquí:

    • JSON_FILE_NAME es la ruta de acceso al archivo JSON que incluye el cuerpo de la solicitud.
    • BUCKET_NAME es el nombre del bucket que contiene los objetos de origen y en el que se crea el objeto de destino. Por ejemplo, my-bucket
    • DESTINATION_OBJECT_NAME es el nombre del objeto de destino que se creará. Por ejemplo, my-composite-object

Para evitar que los contextos de origen se adjunten a objetos compuestos, usa el parámetro de consulta dropContextGroups=custom en tu solicitud:

  1. Tener la gcloud CLI instalada e inicializada, lo que te permite generar un token de acceso para el encabezado Authorization

  2. Crea un archivo JSON que contenga el cuerpo de la solicitud:

    {
  "sourceObjects": [
    {"name": "SOURCE_OBJECT_1"},
    {"name": "SOURCE_OBJECT_2"}
  ],
  "destination": {
    "contentType": "text/plain"
}
}

    Aquí:

    • SOURCE_OBJECT_1 y SOURCE_OBJECT_2 son objetos de origen que se deben componer.

  3. Usa cURL para llamar a la API de JSON con una solicitud de objeto de redacción 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/DESTINATION_OBJECT_NAME/compose?dropContextGroups=custom"

    Aquí:

    • JSON_FILE_NAME es la ruta de acceso al archivo JSON que incluye el cuerpo de la solicitud.
    • BUCKET_NAME es el nombre del bucket que contiene los objetos de origen y en el que se crea el objeto de destino. Por ejemplo, my-bucket
    • DESTINATION_OBJECT_NAME es el nombre del objeto de destino que se creará. Por ejemplo, my-composite-object

Administra contextos de objetos de forma masiva

Para administrar los contextos de millones o miles de millones de objetos con un solo trabajo, usa las operaciones por lotes de Storage. Para crear un trabajo, especifica los objetos de destino proporcionando un archivo de manifiesto o usando prefijos de objetos. Después de especificar los objetos, crea un trabajo de operación por lotes para actualizar los contextos de los objetos.

Analiza contextos de objetos en BigQuery

Si tienes una suscripción activa a Storage Intelligence, puedes consultar y analizar contextos de objetos en BigQuery. Usa la vista del catálogo de contextos de objetos (object_contexts_catalog_view) para consultar claves de contexto, valores y cargas útiles estructuradas de extendedData (como etiquetas de imágenes, rostros detectados y cuadros delimitadores). La vista del catálogo se actualiza cada 24 horas.

Por ejemplo, para encontrar todos los objetos en los que una puntuación de anotación específica supera un umbral, haz lo siguiente:

SELECT
  t.project,
  t.bucket,
  t.name,
  t.generation,
  label
FROM
  `PROJECT_ID.INSIGHTS_DATASET.object_contexts_catalog_view` AS t,
  UNNEST(t.contexts) AS context,
  UNNEST(JSON_QUERY_ARRAY(context.extendedData.labelAnnotationGroup.labelAnnotations)) AS label
WHERE
  context.key = "google:annotation:label-detector-v1"
  AND FLOAT64(label.score) > 0.75;

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto que contiene el conjunto de datos de Storage Insights.
  • INSIGHTS_DATASET: Es el nombre del conjunto de datos de Storage Insights.

Para obtener más información sobre el esquema de vista de catálogo, consulta Esquema de catálogo de contextos de objetos. Para ver más ejemplos de consultas, consulta Analiza contextos de objetos.

¿Qué sigue?