Contextos de objetos

Los contextos de objetos te permiten asociar pares clave-valor personalizados con tus objetos de Cloud Storage para que puedas categorizar, hacer un seguimiento y buscar tus datos.

Para conocer los pasos para adjuntar y administrar contextos de objetos, consulta Usa contextos de objetos.

Cómo funcionan los contextos de objetos

Puedes adjuntar contextos cuando creas o actualizas objetos, o puedes permitir que los servicios deGoogle Cloud los adjunten automáticamente.

En el recurso objects, todos los contextos de objetos aparecen en el campo contexts.custom. En contexts.custom, existen dos tipos de contextos:

  • Contextos personalizados sin datos extendidos: Son contextos que constan de una clave, un valor de cadena y marcas de tiempo. Puedes usar estos contextos para organizar, filtrar y hacer un seguimiento de los objetos en tus buckets de almacenamiento.

  • Contextos personalizados con datos extendidos (versión preliminar): Son contextos que constan de una clave, un valor de cadena, marcas de tiempo y una carga útil de JSON estructurada opcional. Los servicios deGoogle Cloud adjuntan estos contextos durante el análisis automatizado, como el etiquetado de aprendizaje automático.

Componentes de contexto

Cada entrada de contexto consta de los siguientes componentes:

  • Clave: Es un identificador único para el contexto del objeto (hasta 256 bytes). Las claves que comienzan con google: (por ejemplo, google:annotation:face-detector-v1) están reservadas para los contextos generados por Google. No puedes crear ni actualizar contextos con el prefijo google:. Para quitar contextos con el prefijo google:, debes descartarlos con el parámetro dropContextGroups durante una operación de reescritura.

  • Valor: Es un valor de cadena asociado con la clave (hasta 256 bytes) para controlar los flujos de trabajo y filtrar las listas de objetos.

  • Marcas de tiempo: Marcas de tiempo de solo salida (createTime y updateTime) que indican cuándo se creó y modificó por última vez el contexto.

  • Datos extendidos (versión preliminar): Es una carga útil de JSON estructurada opcional (hasta 128 KiB) que contiene información detallada, como etiquetas de aprendizaje automático o anotaciones automatizadas.

Las solicitudes estándar get y list devuelven claves de contexto, valores y marcas de tiempo. Si un contexto tiene datos extendidos, las solicitudes estándar incluyen un campo extendedDataTypeUrl (type.googleapis.com/google.protobuf.Struct). Para recuperar la carga útil completa de los datos extendidos, usa el método viewFullContext (versión preliminar).

Por ejemplo, un objeto con contextos personalizados, con y sin datos extendidos, tiene la siguiente representación JSON:

{
  "contexts": {
    "custom": {
      "customer_id": {
        "value": "cust-78901",
        "createTime": "2026-01-01T00:00:00.000Z",
        "updateTime": "2026-01-01T00:00:00.000Z"
      },
      "payment_status": {
        "value": "unpaid",
        "createTime": "2026-01-01T00:00:00.000Z",
        "updateTime": "2026-01-01T00:00:00.000Z"
      },
      "google:annotation:face-detector-v1": {
        "value": "SUCCESS",
        "createTime": "2026-09-29T17:20:00.000Z",
        "updateTime": "2026-09-29T17:20:00.000Z",
        "extendedDataTypeUrl": "type.googleapis.com/google.protobuf.Struct"
      }
    }
  }
}

En este ejemplo:

  • customer_id y payment_status son contextos personalizados sin datos extendidos.
  • google:annotation:face-detector-v1 es un contexto personalizado generado por Google con datos extendidos.

Todos los contextos se pueden recuperar y usar para filtrar las listas de objetos por sus claves y valores.

Casos de uso de los contextos de objetos

Los contextos de objetos te permiten clasificar, hacer un seguimiento y enriquecer tus datos. En las siguientes secciones, se describen las situaciones en las que se usan contextos de objetos para administrar diferentes tipos de información.

Agrupar y clasificar objetos

Clasificar y organizar objetos en buckets y proyectos Usa contextos para etiquetar datos por atributos, como el origen del conjunto de datos, la propiedad o el centro de costos.

  • Ejemplo 1: Asigna el contexto data_classification: PII a los objetos que contienen información de identificación personal (PII) para que las políticas de cumplimiento puedan controlarlos.

  • Ejemplo 2: Agrupa imágenes de entrenamiento nuevas durante la transferencia asignando el contexto batch_id: 2025_Q4_Model_Run para habilitar pruebas y recuperaciones eficientes del modelo.

Realiza un seguimiento de los flujos de trabajo

Para optimizar los flujos de trabajo personalizados y evitar operaciones redundantes, incorpora información del estado del flujo de trabajo directamente en los objetos para hacer un seguimiento de su recorrido a través de una canalización de procesamiento.

  • Ejemplo 1: Usa processing_status: awaiting_review para indicar los objetos que están pendientes de aprobación de lanzamiento externo.

  • Ejemplo 2: Usa processed_by: analytics_pipeline para evitar que tu servicio personalizado de procesamiento de datos vuelva a analizar los archivos que ya completaron una etapa.

Enriquece los objetos con contexto específico de la aplicación

Adjunta información específica sobre una aplicación o un proceso empresarial para proporcionar contexto adicional y linaje de datos para cada objeto.

  • Ejemplo 1: En el caso de una imagen satelital, registra los detalles de la captura, como capture_angle: 45deg_NW, o haz un seguimiento del historial del archivo con lineage: ingested_from_s3.

  • Ejemplo 2: Incorpora detalles sobre el contenido de un archivo, como document_type: service_manual y vehicle_model: f250.

Beneficios de los contextos de objetos

Los contextos de objetos extienden las capacidades de tus objetos de Cloud Storage. Si asocias pares clave-valor personalizados directamente con los objetos almacenados, puedes obtener los siguientes beneficios:

  • Descubrimiento de datos: Filtra las listas de objetos para limitar las entradas de tus cargas de trabajo solo a los objetos de interés.

  • Interoperabilidad: Admite la interoperabilidad con etiquetas de objetos de otros proveedores de servicios en la nube y ayuda a simplificar las migraciones, ya que los contextos de objetos aceptan valores de cadena sin predefinición.

  • Persistencia de datos: Conserva los datos de contexto durante el ciclo de vida del objeto. Cuando copias, reescribes, redactas, mueves o restableces objetos, los contextos se transfieren automáticamente. También puedes descartar contextos de forma selectiva durante las operaciones de copia, reescritura y composición con el parámetro de consulta dropContextGroups (por ejemplo, dropContextGroups=custom) si quieres evitar que se transfieran al objeto de destino.

  • Control de modificación de contexto: Define quién puede agregar, cambiar o quitar contextos con los permisos de Identity and Access Management (IAM) para mantener un registro de auditoría.

  • Operaciones por lotes: Administra contextos de objetos de forma masiva en miles de millones de objetos con las operaciones por lotes de almacenamiento.

  • Análisis masivo con BigQuery: Consulta y analiza contextos de objetos y datos extendidos (como etiquetas, detecciones de rostros y cuadros delimitadores) en tus buckets de almacenamiento con la vista del catálogo de contextos de objetos (object_contexts_catalog_view) en los conjuntos de datos de Storage Insights.

Precios

Para obtener más información, consulta los Precios de Cloud Storage.

¿Qué sigue?