Usar contextos de objetos

Línea de comandos

Para adjuntar contextos al subir objetos con el comando gcloud alpha storage cp, usa la marca --custom-contexts:

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

Donde:

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

También puedes crear un archivo JSON que contenga los contextos que quieras adjuntar a los objetos y usar la marca --custom-contexts-file:

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

Donde:

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

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

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

Donde:

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

API JSON

Para adjuntar contextos a objetos al subir objetos nuevos, utilice cualquiera de los siguientes métodos:

• Subidas multiparte

• Subidas reanudables

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

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

Donde:

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

Línea de comandos

Usa el comando gcloud alpha storage objects update:

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

Donde:

• BUCKET_NAME es el nombre del segmento que contiene el objeto cuyo contexto quieres editar. Por ejemplo, my-bucket.
• OBJECT_NAME es el nombre del objeto. Por ejemplo, pets/dog.png.

• CUSTOM_CONTEXTS_FLAG es cualquiera de las siguientes marcas:

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

    Donde:

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

  • Para eliminar todos los contextos, usa --clear-custom-contexts.

  • Para añadir, modificar o eliminar contextos concretos, usa una combinación de --update-custom-contexts=KEY=VALUE,... y --remove-custom-contexts=KEY,....

    Donde:

    • KEY es la clave de contexto que quieres adjuntar a un objeto o eliminar de él. Por ejemplo, Department.
    • VALUE es el valor que se va a asociar a la clave de contexto que quieras adjuntar a un objeto. Por ejemplo, Human resources.

Si la acción se realiza correctamente, la respuesta se parecerá al siguiente ejemplo:

Patching gs://my-bucket/pets/dog.png#1560574162144861...
  Completed 1

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

API JSON

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

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

   Para añadir, modificar o sobrescribir contextos, usa el siguiente formato:

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

   Donde:

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

   Para eliminar todos los contextos, usa el siguiente formato:

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

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

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

   Donde:

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

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

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

   Donde:

   • JSON_FILE_NAME es la ruta al archivo que incluye la información de los contextos de objeto.
   • BUCKET_NAME es el nombre del contenedor que contiene el objeto cuyo contexto quieres editar. Por ejemplo, my-bucket.
   • OBJECT_NAME es el nombre codificado como URL del objeto. Por ejemplo, pets/dog.png se codifica como URL pets%2Fdog.png.

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

Línea de comandos

Usa el comando gcloud alpha storage objects describe:

gcloud alpha storage objects describe gs://BUCKET_NAME/OBJECT_NAME

Donde:

• BUCKET_NAME es el nombre del segmento que contiene el objeto cuyo contexto quieres ver. Por ejemplo, my-bucket.
• OBJECT_NAME es el nombre del objeto cuyo contexto quieres ver. Por ejemplo, pets/dog.png

Si la solicitud se hace correctamente, la respuesta será similar a la del siguiente ejemplo:

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: HR
  DataClassification:
    createTime: '2023-01-01T00:00:00.000000+00:00'
    type: CUSTOM
    updateTime: '2023-01-01T00:00:00.000000+00:00'
    value: Confidential
name: employees.txt

Bibliotecas de 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());
        }
      }
    }
  }
}

API JSON

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

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

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

   Donde:

   • BUCKET_NAME es el nombre del contenedor que contiene el objeto cuyo contexto quieres ver. Por ejemplo, my-bucket.
   • OBJECT_NAME es el nombre codificado en URL del objeto cuyo contexto quieres ver. Por ejemplo, pets/dog.png, codificado como URL pets%2Fdog.png.

   Si la solicitud se hace correctamente, la respuesta será similar a la del siguiente ejemplo:

     {
       "kind": "storage#object",
       "name": "employees.txt",
       "bucket": "my-bucket",
       "contexts": {
         "custom": {
           "Department": {
             "value": "HR",
             "createTime": "2023-01-01T00:00:00.000Z",
             "updateTime": "2023-01-01T00:00:00.000Z"
           },
           "DataClassification": {
             "value": "Confidential",
             "createTime": "2023-01-01T00:00:00.000Z",
             "updateTime": "2023-01-01T00:00:00.000Z"
           }
         }
       }
     }
     

Línea de comandos

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

• Las marcas --custom-contexts o --custom-contexts-file para definir nuevos contextos 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.

El comando gcloud alpha storage objects compose combina contextos de los objetos de origen y los adjunta a los objetos de destino de forma predeterminada. Cloud Storage resuelve los conflictos dando prioridad a los contextos de los objetos de origen procesados más tarde. Para obtener más información sobre el comportamiento del contexto de objeto durante una operación de composición, consulta Contextos de objetos compuestos. También puedes especificar contextos nuevos para el objeto de destino con las marcas --custom-contexts o --custom-contexts-file.

API JSON

• Para modificar los contextos durante una operación de copia o reescritura de un objeto, incluye la propiedad contexts.custom en el cuerpo de la solicitud. Si no incluye esta propiedad, los contextos del objeto de origen se conservarán de forma predeterminada.

• Cuando compone objetos, los contextos de los objetos de origen se combinan en el objeto de destino de forma predeterminada. Cloud Storage resuelve los conflictos dando prioridad a los contextos de los objetos de origen que se procesan más tarde. Para obtener más información sobre el comportamiento del contexto de objeto durante una operación de composición, consulta Contextos de objeto compuesto. También puede especificar nuevos contextos para el objeto de destino en la propiedad destination.contexts.custom.