Algumas ou todas as informações nesta página podem não se aplicar ao Cloud de Confiance da S3NS. Consulte Diferenças do Google Cloud para saber mais.

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 que você configura as otimizações de objetos, o Cloud Storage avalia os objetos qualificados de forma assíncrona e anexa metadados de otimização 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 enriquecimentos de objetos, peça ao administrador para conceder a você os seguintes papéis do IAM no bucket ou projeto:

Acessar 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 enriquecimentos 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 enriquecimentos de objetos. Para acessar as permissões exatas 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 enriquecimentos de objetos:

Ver os metadados de contexto básicos de enriquecimento de objetos: storage.objects.get
Recuperar dados estendidos de enriquecimento de objetos: storage.objects.viewFullContext
Descartar enriquecimentos de objetos durante a reescrita de objetos:
- storage.objects.get
- storage.objects.create
- storage.objects.delete
- storage.objects.update

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

Ver enriquecimentos de objetos

O Cloud Storage anexa metadados de enriquecimento diretamente aos objetos como contextos de objeto 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 dois níveis:

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 de protobuf. As operações padrão de objeto describe e get retornam esses metadados.
Dados estendidos (pré-lançamento): contém o payload de enriquecimento JSON estruturado completo (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.

Ver metadados de contexto básico

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

Console

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

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

Na tabela Objetos, a coluna Contextos personalizados exibe um ícone para cada modelo que processou um objeto (Segurança de conteúdo, Detector de rosto, Detector de rótulos, Detector de objetos ou Classificação de PDF).
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 ícones, clique em para abrir a linha.
Mantenha o ponteiro sobre um ícone de modelo ou clique nele para ver os metadados de contexto básico:
- 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).
- Horário de criação e Horário da última modificação: os carimbos de data/hora de quando o Cloud Storage criou e atualizou o enriquecimento pela última vez.
- Ver hub de configuração: abre a página Enriquecimentos de objetos. Ao visualizar um ícone na tabela Objetos do bucket, você também pode clicar em Filtrar contextos para filtrar objetos no bucket por esse contexto.

API JSON

Ter 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 parâmetro de consulta projection=full para a API JSON:

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Accept: application/json" \
  "https://storage.s3nsapis.fr/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 rostos detectados), chame o método viewFullContext (pré-lançamento) usando a API JSON.

Ter 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 viewFullContext à 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.s3nsapis.fr/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 JSON detalhados e campos para cada modelo, consulte Modelos e esquemas compatíveis.

Descartar enriquecimentos de objetos

Se você precisar obedecer às políticas de retenção de dados ou não precisar mais de metadados de enriquecimento, descarte-os dos seus 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 padrão de atualização de metadados. Em vez disso, descarte-os 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 objeto no objeto.

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

Ter 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 solicitação de objeto de reescrita POST e o parâmetro de consulta dropContextGroups=custom:
```
curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Length: 0" \
  "https://storage.s3nsapis.fr/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 capacidade de processamento de enriquecimento, os objetos pendentes e as contagens de execução de modelos usando o Cloud Monitoring. O Cloud Storage exporta as seguintes métricas no namespace storage.googleapis.com no recurso monitorado gcs_bucket:

Tipo de métrica (com o prefixo `storage.googleapis.com/`)	Tipo	Descrição e rótulos
`auto_annotate/operations/pending_objects`	`GAUGE`, `INT64`	Número total de objetos com enriquecimento pendente 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 o período. Amostras coletadas a cada 300 segundos.
`auto_annotate/operations/model_count`	`DELTA`, `INT64`	Número total de modelos executados no bucket durante o período, 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 o período, 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.