O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Gerenciar enriquecimentos de objetos

Depois de configurar o enriquecimento de objetos, o Cloud Storage avalia os objetos qualificados de forma assíncrona e anexa os metadados de enriquecimento diretamente aos objetos armazenados.

Nesta página, explicamos como inspecionar metadados de contexto básicos, recuperar payloads de dados estendidos, descartar enriquecimentos de objetos e monitorar o progresso do processamento no Cloud Monitoring.

Ter os papéis necessários

Para receber as permissões necessárias para visualizar, recuperar e descartar o enriquecimento de objetos, peça que o administrador conceda a você os seguintes papéis do IAM no bucket ou projeto:

Visualizar metadados básicos de enriquecimento de objetos: Leitor de objetos do Storage (roles/storage.objectViewer)
Recuperar dados estendidos de enriquecimento de objetos: Usuário de objetos do Storage (roles/storage.objectUser)
Descartar o enriquecimento de objetos durante a regravação de objetos: Administrador de objetos do Storage (roles/storage.objectAdmin)

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para visualizar, recuperar e descartar o enriquecimento de objetos. Para acessar as permissões exatas que são necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para visualizar, recuperar e descartar o enriquecimento de objetos:

Visualizar metadados de contexto básicos de enriquecimento de objetos: storage.objects.get
Recuperar dados estendidos de enriquecimento de objetos: storage.objects.viewFullContext
Descartar o enriquecimento de objetos durante a regravação de objetos:
- storage.objects.get
- storage.objects.create
- storage.objects.delete
- storage.objects.update

Essas permissões também podem ser concedidas com papéis personalizados ou outros papéis predefinidos.

Visualizar o enriquecimento de objetos

O Cloud Storage anexa metadados de enriquecimento diretamente aos objetos como contextos de objetos gerenciados pelo Google na propriedade contexts.custom. Cada modelo usa uma chave reservada com o prefixo google:annotation: (por exemplo, google:annotation:label-detector-v1 ou google:annotation:face-detector-v1).

O Cloud Storage organiza os dados de enriquecimento em duas camadas:

Metadados de contexto: contém a chave de contexto, o status de execução do modelo (value), os carimbos de data/hora e o URL do tipo protobuf. As operações describe e get de objetos padrão retornam esses metadados.
Dados estendidos (prévia): contém o payload JSON estruturado completo de enriquecimento (até 128 KiB). Esse payload inclui detalhes como coordenadas de polígonos delimitadores, pontuações de confiança de classificação, expressões faciais e classificações de segurança.

Visualizar metadados de contexto básicos

Para verificar quais modelos processaram um objeto e visualizar metadados de contexto básicos, use o Google Cloud console ou a API JSON:

Console

No Google Cloud console do, acesse a página Buckets do Cloud Storage.

Acessar buckets
Na lista de buckets, clique no nome daquele que contém o objeto que você quer inspecionar.

Na tabela Objetos , a coluna Contextos personalizados mostra um chip para cada modelo que processou um objeto (Content Safety, Face Detector, Label Detector, Object Detector ou PDF Classification).
Para inspecionar um objeto individual, clique no nome dele.
Na página Detalhes do objeto, acesse o campo Contextos personalizados. Se o campo tiver vários chips, clique em para expandir a linha.
Mantenha o ponteiro sobre um chip de modelo ou clique nele para visualizar os metadados de contexto básicos:
- Chave de contexto: a chave de modelo reservada, como google:annotation:label-detector-v1.
- Valor de contexto: o status de execução do modelo (SUCCESS ou FAILURE).
- Hora de criação e Hora da última modificação: os carimbos de data/hora de quando o Cloud Storage criou e atualizou o enriquecimento pela última vez.
- Visualizar hub de configuração: abre a página Enriquecimento de objetos. Ao visualizar um chip na tabela Objetos do bucket, também é possível clicar em Filtrar contextos para filtrar objetos no bucket por esse contexto.

API JSON

Tenha a CLI gcloud instalada e inicializada, o que permite gerar um token de acesso para o cabeçalho Authorization.

Use cURL para enviar uma solicitação Objects: get com o projection=full parâmetro de consulta para a API 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"

Em que:

BUCKET_NAME é o nome do bucket que contém o objeto. Por exemplo, my-bucket.
OBJECT_NAME é o nome codificado por URL do objeto. Por exemplo, image.jpg.

A resposta retorna a estrutura 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"
      }
    }
  }
}

O campo value indica o status de execução do modelo para o objeto, como SUCCESS ou FAILURE.

Recuperar dados estendidos

Para recuperar os dados de enriquecimento estruturados completos (como caixas delimitadoras, polígonos delimitadores, rótulos ou faces detectadas), chame o viewFullContext método (prévia) usando a API JSON.

Tenha a CLI gcloud instalada e inicializada, o que permite gerar um token de acesso para o cabeçalho Authorization.

Use cURL para enviar uma soliceração viewFullContext request para a API JSON, especificando a chave de contexto do modelo que você quer inspecionar:

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"

Em que:

BUCKET_NAME é o nome do bucket que contém o objeto. Por exemplo, my-bucket.
OBJECT_NAME é o nome codificado por URL do objeto. Por exemplo, image.jpg.
CONTEXT_KEY é a chave de contexto do modelo. Por exemplo, google:annotation:label-detector-v1.

A resposta contém a estrutura extendedData com o payload de enriquecimento completo:

{
  "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 ver esquemas e campos JSON detalhados para cada modelo, consulte Modelos e esquemas compatíveis.

Descartar o enriquecimento de objetos

Se você precisar obedecer às políticas de retenção de dados ou não precisar mais de metadados de enriquecimento, poderá descartá-los dos objetos.

Como o Google gerencia as chaves de contexto que começam com o prefixo google:, não é possível modificá-las ou excluí-las usando métodos de atualização de metadados padrão. Em vez disso, você as descarta durante uma operação de regravação, cópia ou composição de objetos, especificando o parâmetro dropContextGroups=custom, que descarta todos os contextos de objetos.

Para descartar contextos de objetos (incluindo o enriquecimento de objetos) ao regravar um objeto usando a API JSON, faça o seguinte:

Tenha a CLI gcloud instalada e inicializada, o que permite gerar um token de acesso para o cabeçalho Authorization.
Use cURL para chamar a API JSON com uma POST solicitação de objeto de regravação e o 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"
```
Em que:
- SOURCE_BUCKET é o nome do bucket que contém o objeto de origem. Por exemplo, my-source-bucket.
- SOURCE_OBJECT é o nome codificado por URL do objeto de origem. Por exemplo, image.jpg.
- DESTINATION_BUCKET é o nome do bucket de destino (pode corresponder ao bucket de origem). Por exemplo, my-source-bucket.
- DESTINATION_OBJECT é o nome codificado por URL do objeto de destino (pode corresponder ao objeto de origem). Por exemplo, image.jpg.

Para gerenciar e descartar contextos em bilhões de objetos, consulte Gerenciar contextos de objetos em massa.

Monitorar métricas de enriquecimento de objetos

É possível acompanhar a taxa de transferência de processamento de enriquecimento, objetos pendentes e contagens de execução de modelos usando Cloud Monitoring. O Cloud Storage exporta as seguintes métricas no storage.googleapis.com namespace no gcs_bucket recurso monitorado:

Tipo de métrica (com o prefixo `storage.googleapis.com/`)	Tipo e tipo	Descrição e rótulos
`auto_annotate/operations/pending_objects`	`GAUGE`, `INT64`	Número total de objetos pendentes de enriquecimento no bucket. Amostras coletadas a cada 300 segundos.
`auto_annotate/operations/processed_object_count`	`DELTA`, `INT64`	Número total de objetos processados pelo enriquecimento de objetos durante a janela de tempo. Amostras coletadas a cada 300 segundos.
`auto_annotate/operations/model_count`	`DELTA`, `INT64`	Número total de modelos executados no bucket durante a janela de tempo, agrupados por `model_name`, `model_version` e `status` (como `SUCCESS` ou `FAILURE`).
`auto_annotate/operations/request_count`	`DELTA`, `INT64`	Número total de chamadas de API feitas durante a janela de tempo, agrupadas por `method` e `response_code`.
`auto_annotate/storage/annotated_objects`	`GAUGE`, `INT64`	Snapshot diário do número total de objetos no bucket que têm enriquecimentos gerados para eles, agrupados por `type` e `data_locations`.
`auto_annotate/storage/model_outputs`	`GAUGE`, `INT64`	Snapshot diário do número total de saídas do modelo armazenadas no bucket, agrupadas por `model_name`, `model_version`, `status`, `type` e `data_locations`.

Para mais informações sobre como consultar métricas e configurar alertas, consulte Métricas do Cloud Monitoring para o Cloud Storage e Criar gráficos com o Metrics Explorer.