Se usó la API de Cloud Translation para traducir esta página.

Usa contextos de objetos

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

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:

Crea objetos con contextos: Creador de objetos de Storage (roles/storage.objectCreator)
Adjuntar, actualizar, ver y borrar contextos de objetos: Usuario de objetos de almacenamiento (roles/storage.objectUser)
Visualiza las claves y los valores de contexto adjuntos a los objetos: Visualizador de objetos de Storage (roles/storage.objectViewer)

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
Ver contextos de objetos:
- storage.objects.get
- storage.objects.list

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

Cómo adjuntar 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.

Línea de comandos

Para adjuntar contextos cuando subas 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,...

Aquí:

OBJECT_LOCATION es la ruta de acceso local a tu objeto. Por ejemplo, Desktop/dog.png.
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 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,...

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:

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

Cómo adjuntar o modificar contextos en un objeto existente

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

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

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, pets/dog.png.
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 --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. Por ejemplo, Human resources

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

Patching gs://my-bucket/pets/dog.png#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);
    }
  }
}

API de JSON

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

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.

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, pets/dog.png se codifica como URL como pets%2Fdog.png.

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.

Cómo ver los contextos de objetos

Puedes ver los contextos de un objeto si enumeras los metadatos del objeto o describes un objeto específico.

Línea de comandos

Usa el comando gcloud alpha storage objects describe:

gcloud alpha 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, pets/dog.png

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

API de JSON

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

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 cuyo contexto deseas ver. Por ejemplo, my-bucket.
OBJECT_NAME es el nombre codificado en URL del objeto cuyo contexto deseas ver. Por ejemplo, pets/dog.png, codificado en URL como pets%2Fdog.png.

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": "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"
        }
      }
    }
  }

Cómo filtrar objetos por contextos

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

Administra contextos de objetos durante las operaciones de objetos

Los contextos de objetos se conservan de forma predeterminada cuando copias, reescribes, redactas, mueves o restableces objetos. También puedes modificar los contextos durante las operaciones de copia, reescritura y composición.

Línea de comandos

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

Son las marcas --custom-contexts o --custom-contexts-file para establecer contextos nuevos para el objeto de destino.
Es la marca --clear-custom-contexts para evitar que los contextos del objeto fuente se adjunten al objeto de destino.
Es 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.

De forma predeterminada, el comando gcloud alpha storage objects compose combina los contextos de los objetos de origen y los adjunta a los objetos de destino. 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 del 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 de JSON

Para modificar los contextos durante una operación de objeto de copia o reescritura, incluye la propiedad contexts.custom en el cuerpo de la solicitud. Si no incluyes esta propiedad, se conservarán los contextos del objeto fuente de forma predeterminada.
Cuando compones objetos, los contextos de los objetos de origen se combinan con el objeto 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 del objeto durante una operación de composición, consulta Contextos de objetos compuestos. También puedes especificar contextos nuevos para el objeto de destino en la propiedad destination.contexts.custom.

¿Qué sigue?

Obtén información sobre las propiedades del contexto del objeto en la documentación de la API de Cloud Storage.

Usa contextos de objetos Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Obtén los roles necesarios

Permisos necesarios

Cómo adjuntar contextos a objetos nuevos

Línea de comandos

API de JSON

Cómo adjuntar o modificar contextos en un objeto existente

Línea de comandos

Bibliotecas cliente

Java

API de JSON

Cómo ver los contextos de objetos

Línea de comandos

Bibliotecas cliente

Java

API de JSON

Cómo filtrar objetos por contextos

Administra contextos de objetos durante las operaciones de objetos

Línea de comandos

API de JSON

¿Qué sigue?

Usa contextos de objetos