Contextos de objetos

En este documento, se describe cómo los contextos de objetos te permiten asociar información contextual con tus objetos para ayudarte a administrar y descubrir datos.

Para obtener información sobre cómo adjuntar y administrar contextos de objetos, consulta Usa contextos de objetos.

Descripción general

Los contextos de objetos te permiten asociar pares clave-valor con tus objetos de Cloud Storage para categorizar, hacer un seguimiento y buscar tus datos. Puedes adjuntar contextos cuando creas o actualizas objetos, o permitir que los servicios de Google los adjunten automáticamente.

En el recurso objects, todos los contextos de objetos aparecen en el campo contexts.custom. Dentro de contexts.custom, hay 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 (vista previa): Son contextos que constan de una clave, un valor de cadena, marcas de tiempo y una carga útil JSON estructurada opcional. Los servicios de Google 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: Son marcas de tiempo de solo salida (createTime y updateTime) que indican cuándo se creó y modificó por última vez el contexto.

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

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

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

Agrupa y clasifica objetos

Clasifica y organiza 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 las imágenes de entrenamiento nuevas durante la transferencia asignando el contexto batch_id: 2025_Q4_Model_Run para permitir las pruebas y la recuperación eficientes del modelo.

Haz un seguimiento de los flujos de trabajo

Para optimizar los flujos de trabajo personalizados y evitar operaciones redundantes, incorpora información sobre el 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 objetos pendientes de aprobación de lanzamiento externo.

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

Enriquece 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: Para una imagen satelital, registra los detalles de 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 objetos almacenados, puedes obtener los siguientes beneficios:

  • Detección 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 definición previa.

  • 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 redacción con el dropContextGroups parámetro de consulta (por ejemplo, dropContextGroups=custom) si deseas 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 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 Catálogo de contextos de objetos (object_contexts_catalog_view) en los conjuntos de datos de Storage Insights.

Precios

Para obtener detalles sobre los precios, consulta Precios de Cloud Storage.

¿Qué sigue?