Contextos de objetos

Neste documento, descrevemos como os contextos de objeto permitem associar informações contextuais aos seus objetos para ajudar você a gerenciar e descobrir dados.

Para saber como anexar e gerenciar contextos de objetos, consulte Usar contextos de objetos.

Visão geral

Com os contextos de objeto, é possível associar pares de chave-valor aos objetos do Cloud Storage para categorizar, rastrear e pesquisar seus dados. É possível anexar contextos ao criar ou atualizar objetos ou permitir que os serviços do Google os anexem automaticamente.

No recurso objects, todos os contextos de objeto aparecem no campo contexts.custom. No contexts.custom, há dois tipos de contextos:

  • Contextos personalizados sem dados estendidos: contextos que consistem em uma chave, um valor de string e carimbos de data/hora. É possível usar esses contextos para organizar, filtrar e rastrear objetos nos buckets de armazenamento.

  • Contextos personalizados com dados estendidos (pré-lançamento): contextos que consistem em uma chave, um valor de string, carimbos de data/hora e um payload JSON estruturado opcional. Os serviços do Google anexam esses contextos durante a análise automatizada, como a rotulagem de machine learning.

Componentes de contexto

Cada entrada de contexto consiste nos seguintes componentes:

  • Chave: um identificador exclusivo para o contexto no objeto (até 256 bytes). As chaves que começam com google: (por exemplo, google:annotation:face-detector-v1) são reservadas para contextos gerados pelo Google. Não é possível criar ou atualizar contextos com o prefixo google:. Para remover contextos com o prefixo google:, é necessário descartá-los usando o parâmetro dropContextGroups durante uma operação de reescrita.

  • Valor: um valor de string associado à chave (até 256 bytes) para controlar fluxos de trabalho e filtrar listagens de objetos.

  • Carimbos de data/hora: carimbos de data/hora somente de saída (createTime e updateTime) que indicam quando o contexto foi criado e modificado pela última vez.

  • Dados estendidos (pré-lançamento): um payload JSON estruturado opcional (até 128 KiB) que contém informações detalhadas, como rótulos de machine learning ou anotações automatizadas.

As solicitações padrão get e list retornam chaves de contexto, valores e carimbos de data/hora. Se um contexto tiver dados estendidos, as solicitações padrão vão incluir um campo extendedDataTypeUrl (type.googleapis.com/google.protobuf.Struct). Para recuperar o payload completo de dados estendidos, use o método viewFullContext (pré-lançamento).

Por exemplo, um objeto com contextos personalizados, com e sem dados estendidos, tem a seguinte representação 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"
      }
    }
  }
}

Neste exemplo:

  • customer_id e payment_status são contextos personalizados sem dados estendidos.
  • google:annotation:face-detector-v1 é um contexto personalizado gerado pelo Google com dados estendidos.

Todos os contextos podem ser recuperados e usados para filtrar listagens de objetos por chaves e valores.

Casos de uso para contextos de objetos

Os contextos de objeto permitem classificar, rastrear e enriquecer seus dados. As seções a seguir descrevem os cenários de uso de contextos de objeto para gerenciar diferentes tipos de informações.

Agrupar e classificar objetos

Classificar e organizar objetos em buckets e projetos. Use contextos para marcar dados por atributos, como origem do conjunto de dados, propriedade ou centro de custo.

  • Exemplo 1: atribuir o contexto data_classification: PII a objetos que contêm informações de identificação pessoal (PII) para que as políticas de compliance possam processá-los.

  • Exemplo 2: agrupar novas imagens de treinamento durante a ingestão atribuindo o contexto batch_id: 2025_Q4_Model_Run para permitir testes e recuperação eficientes de modelos.

Monitorar fluxos de trabalho

Para otimizar fluxos de trabalho personalizados e evitar operações redundantes, incorpore informações de estado do fluxo de trabalho diretamente nos objetos para acompanhar a jornada deles em um pipeline de processamento.

  • Exemplo 1: use processing_status: awaiting_review para indicar objetos com aprovação de lançamento externo pendente.

  • Exemplo 2: use processed_by: analytics_pipeline para impedir que o serviço personalizado de tratamento de dados verifique novamente os arquivos que já concluíram uma etapa.

Enriquecer objetos com contexto específico do aplicativo

Anexe informações específicas sobre um aplicativo ou processo de negócios para fornecer mais contexto e linhagem de dados para cada objeto.

  • Exemplo 1: para uma imagem de satélite, registre detalhes de captura, como capture_angle: 45deg_NW, ou acompanhe o histórico do arquivo com lineage: ingested_from_s3.

  • Exemplo 2: incorporar detalhes sobre o conteúdo de um arquivo, como document_type: service_manual e vehicle_model: f250.

Benefícios dos contextos de objeto

Os contextos de objeto ampliam os recursos dos objetos do Cloud Storage. Ao associar pares de chave-valor personalizados diretamente a objetos armazenados, você pode alcançar os seguintes benefícios:

  • Descoberta de dados: filtre as listagens de objetos para limitar as entradas das cargas de trabalho apenas aos objetos de interesse.

  • Interoperabilidade: suporte à interoperabilidade com tags de objeto de outros provedores de nuvem e simplificação de migrações, já que os contextos de objeto aceitam valores de string sem predefinição.

  • Persistência de dados: preserve os dados de contexto durante o ciclo de vida do objeto. Quando você copia, reescreve, compõe, move ou restaura objetos, os contextos são transferidos automaticamente. Também é possível descartar contextos seletivamente durante operações de cópia, regravação e composição usando o parâmetro de consulta dropContextGroups (por exemplo, dropContextGroups=custom) se você quiser evitar que eles sejam transferidos para o objeto de destino.

  • Controle de modificação de contexto: defina quem pode adicionar, alterar ou remover contextos usando as permissões do Identity and Access Management (IAM) para manter uma trilha de auditoria.

  • Operações em lote: gerencie contextos de objetos em massa em bilhões de objetos usando operações em lote do Storage.

  • Análise em massa com o BigQuery: consulte e analise contextos de objetos e dados estendidos (como rótulos, detecções faciais e caixas delimitadoras) nos buckets de armazenamento usando a visualização do catálogo de contextos de objetos (object_contexts_catalog_view) em conjuntos de dados do Storage Insights.

Preços

Para mais detalhes, consulte Preços do Cloud Storage.

A seguir