Usa contextos de objetos

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 vincular 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 tu 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 subas objetos nuevos, usa cualquiera de los siguientes métodos:

• Cargas multiparte

• Cargas reanudables

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

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 more_vert 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.

   • Sigue estos pasos para editar 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.

   • Para borrar un contexto de objeto, haz lo siguiente:

     Haz clic en delete 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

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);
    }
  }
}

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

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

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 cuyos contextos 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 cuyo contexto deseas ver. Por ejemplo, my-bucket
• OBJECT_NAME es el nombre del objeto cuyo contexto deseas ver. Por ejemplo, employees.txt

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

bucket: my-bucket
contexts:
  Department:
    createTime: '2023-01-01T00:00:00.000000+00:00'
    type: CUSTOM
    updateTime: '2023-01-01T00:00:00.000000+00:00'
    value: Human resources
name: employees.txt

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 =