Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

Administrar enriquecimientos de objetos

Después de configurar los enriquecimientos de objetos, Cloud Storage evalúa los objetos aptos de forma asíncrona y adjunta metadatos de enriquecimiento directamente a tus objetos almacenados.

En esta página, se explica cómo inspeccionar los metadatos de contexto básicos, recuperar cargas útiles de datos extendidas, descartar enriquecimientos de objetos y supervisar el progreso del procesamiento en Cloud Monitoring.

Obtén los roles necesarios

Para obtener los permisos que necesitas para ver, recuperar y descartar los enriquecimientos de objetos, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu bucket o proyecto:

Ver metadatos básicos de enriquecimientos de objetos: Visualizador de objetos de almacenamiento (roles/storage.objectViewer)
Recuperar datos extendidos de enriquecimientos de objetos: Usuario de objetos de almacenamiento (roles/storage.objectUser)
Descartar enriquecimientos de objetos durante la reescritura de objetos: Administrador de objetos de almacenamiento (roles/storage.objectAdmin)

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 ver, recuperar y descartar los enriquecimientos de objetos. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para ver, recuperar y descartar los enriquecimientos de objetos:

Ver metadatos de contexto básicos de enriquecimientos de objetos: storage.objects.get
Recuperar datos extendidos de enriquecimientos de objetos: storage.objects.viewFullContext
Descartar enriquecimientos de objetos durante la reescritura de objetos:
- storage.objects.get
- storage.objects.create
- storage.objects.delete
- storage.objects.update

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

Visualiza los enriquecimientos de objetos

Cloud Storage adjunta metadatos de enriquecimiento directamente a tus objetos como contextos de objetos administrados por Google en la propiedad contexts.custom. Cada modelo usa una clave reservada con el prefijo google:annotation: (por ejemplo, google:annotation:label-detector-v1 o google:annotation:face-detector-v1).

Cloud Storage organiza los datos de enriquecimiento en dos niveles:

Metadatos de contexto: Contiene la clave de contexto, el estado de ejecución del modelo (value), las marcas de tiempo y la URL del tipo protobuf. Las operaciones describe y get de objetos estándar muestran estos metadatos.
Datos extendidos (vista previa): Contiene la carga útil de enriquecimiento JSON estructurada completa (hasta 128 KiB). Esta carga útil incluye detalles como las coordenadas del polígono delimitador, las puntuaciones de confianza de clasificación, las expresiones faciales y las calificaciones de seguridad.

Visualiza los metadatos de contexto básicos

Para verificar qué modelos procesaron un objeto y ver los metadatos de contexto básicos, usa la Google Cloud consola o la API de JSON:

Console

En la Google Cloud consola de, ve a la página Buckets de Cloud Storage.

Ir a Buckets
En la lista de buckets, haz clic en el nombre del bucket que contiene el objeto que deseas inspeccionar.

En la tabla Objetos , la columna Contextos personalizados muestra un chip para cada modelo que procesó un objeto (Content Safety, Face Detector, Label Detector, Object Detector o PDF Classification).
Para inspeccionar un objeto individual, haz clic en su nombre.
En la página Detalles del objeto, ve al campo Contextos personalizados. Si el campo tiene varios chips, haz clic en para expandir la fila.
Mantén el puntero sobre un chip de modelo o haz clic en él para ver sus metadatos de contexto básicos:
- Clave de contexto: La clave de modelo reservada, como google:annotation:label-detector-v1.
- Valor de contexto: El estado de ejecución del modelo (SUCCESS o FAILURE).
- Hora de creación y Hora de última modificación: Las marcas de tiempo de cuándo Cloud Storage creó y actualizó por última vez el enriquecimiento.
- Ver el centro de configuración: Abre la página Enriquecimientos de objetos. Cuando ves un chip de la tabla Objetos del bucket, también puedes hacer clic en Filtrar contextos para filtrar los objetos del bucket por ese contexto.

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 enviar una solicitud Objects: get con el projection=full parámetro de consulta a la API de JSON:

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Accept: application/json" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?projection=full"

Aquí:

BUCKET_NAME es el nombre del bucket que contiene el objeto. Por ejemplo, my-bucket.
OBJECT_NAME es el nombre codificado en URL del objeto. Por ejemplo, image.jpg.

La respuesta muestra la estructura contexts.custom:

{
  "kind": "storage#object",
  "id": "my-bucket/image.jpg/1700000000000000",
  "name": "image.jpg",
  "bucket": "my-bucket",
  "contexts": {
    "custom": {
      "google:annotation:label-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"
      }
    }
  }
}

El campo value indica el estado de ejecución del modelo para el objeto, como SUCCESS o FAILURE.

Recupera datos extendidos

Para recuperar los datos de enriquecimiento estructurados completos (como cuadros delimitadores, polígonos delimitadores, etiquetas o rostros detectados), llama al viewFullContext método (vista previa) con la 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 enviar una solicitud viewFullContext a la API de JSON y especificar la clave de contexto del modelo que deseas inspeccionar:

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Accept: application/json" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME/viewFullContext?contextKey=CONTEXT_KEY"

Aquí:

BUCKET_NAME es el nombre del bucket que contiene el objeto. Por ejemplo, my-bucket.
OBJECT_NAME es el nombre codificado en URL del objeto. Por ejemplo, image.jpg.
CONTEXT_KEY es la clave de contexto del modelo. Por ejemplo, google:annotation:label-detector-v1.

La respuesta contiene la estructura extendedData con la carga útil de enriquecimiento completa:

{
  "kind": "storage#objectFullContext",
  "type": "CUSTOM",
  "key": "google:annotation:label-detector-v1",
  "value": "SUCCESS",
  "createTime": "2026-09-29T17:20:00.000Z",
  "updateTime": "2026-09-29T17:20:00.000Z",
  "extendedData": {
    "@type": "type.googleapis.com/google.protobuf.Struct",
    "modelName": "label-detector",
    "modelVersion": "v1",
    "labelAnnotationGroup": {
      "labelAnnotations": [
        {
          "description": "Night",
          "knowledgeGraphId": "/m/01d74z",
          "score": 0.92,
          "topicality": 0.19
        }
      ]
    }
  }
}

Para obtener esquemas y campos JSON detallados para cada modelo, consulta Modelos y esquemas compatibles.

Descarta los enriquecimientos de objetos

Si debes cumplir con las políticas de retención de datos o ya no necesitas metadatos de enriquecimiento, puedes descartarlos de tus objetos.

Debido a que Google administra las claves de contexto que comienzan con el prefijo google:, no puedes modificarlas ni borrarlas con los métodos de actualización de metadatos estándar. En cambio, los descartas durante una operación de reescritura, copia o composición de objetos especificando el parámetro dropContextGroups=custom, que descarta todos los contextos de objetos en el objeto.

Para descartar contextos de objetos (incluidos los enriquecimientos de objetos) cuando reescribes un objeto con la API de JSON, haz lo siguiente:

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 POST solicitud de objeto de reescritura y el dropContextGroups=custom parámetro de consulta:
```
curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Length: 0" \
  "https://storage.googleapis.com/storage/v1/b/SOURCE_BUCKET/o/SOURCE_OBJECT/rewriteTo/b/DESTINATION_BUCKET/o/DESTINATION_OBJECT?dropContextGroups=custom"
```
Aquí:
- SOURCE_BUCKET es el nombre del bucket que contiene el objeto de origen. Por ejemplo, my-source-bucket.
- SOURCE_OBJECT es el nombre codificado en URL del objeto de origen. Por ejemplo, image.jpg.
- DESTINATION_BUCKET es el nombre del bucket de destino (puede coincidir con el bucket de origen). Por ejemplo, my-source-bucket.
- DESTINATION_OBJECT es el nombre codificado en URL del objeto de destino (puede coincidir con el objeto de origen). Por ejemplo, image.jpg.

Para administrar y descartar contextos en miles de millones de objetos, consulta Administra contextos de objetos de forma masiva.

Supervisa las métricas de enriquecimientos de objetos

Puedes hacer un seguimiento del rendimiento del procesamiento de enriquecimiento, los objetos pendientes y los recuentos de ejecución del modelo con Cloud Monitoring. Cloud Storage exporta las siguientes métricas en el storage.googleapis.com espacio de nombres en el gcs_bucket recurso supervisado:

Tipo de métrica (con el prefijo `storage.googleapis.com/`)	Tipo	Descripción y etiquetas
`auto_annotate/operations/pending_objects`	`GAUGE`, `INT64`	Cantidad total de objetos pendientes de enriquecimiento en el bucket. Se toman muestras cada 300 segundos.
`auto_annotate/operations/processed_object_count`	`DELTA`, `INT64`	Cantidad total de objetos procesados por los enriquecimientos de objetos durante el período. Se toman muestras cada 300 segundos.
`auto_annotate/operations/model_count`	`DELTA`, `INT64`	Cantidad total de modelos ejecutados en el bucket durante el período, agrupados por `model_name`, `model_version` y `status` (como `SUCCESS` o `FAILURE`).
`auto_annotate/operations/request_count`	`DELTA`, `INT64`	Cantidad total de llamadas a la API realizadas durante el período, agrupadas por `method` y `response_code`.
`auto_annotate/storage/annotated_objects`	`GAUGE`, `INT64`	Instantánea diaria de la cantidad total de objetos en el bucket para los que se generaron enriquecimientos, agrupados por `type` y `data_locations`.
`auto_annotate/storage/model_outputs`	`GAUGE`, `INT64`	Instantánea diaria de la cantidad total de resultados del modelo almacenados en el bucket, agrupados por `model_name`, `model_version`, `status`, `type` y `data_locations`.

Para obtener más información sobre cómo consultar métricas y configurar alertas, consulta Métricas de Cloud Monitoring para Cloud Storage y Crea gráficos con el Explorador de métricas.