Contextos de objetos

Este documento descreve como os contextos de objeto permitem associar informações contextuais aos objetos para ajudar a gerenciar e descobrir dados.

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

Visão geral

Os contextos de objeto permitem associar pares de chave-valor aos objetos do Cloud Storage para categorizar, rastrear e pesquisar 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. Em 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évia): 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:, descarte-os 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 listas 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évia): 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 get e list padrão 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 extendedDataTypeUrl campo (type.googleapis.com/google.protobuf.Struct). Para recuperar o payload de dados estendidos completo, use o viewFullContext método (prévia).

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 listas de objetos pelas chaves e valores.

Casos de uso de contextos de objeto

Os contextos de objeto permitem classificar, rastrear e enriquecer os 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

Classifique e organize objetos em buckets e projetos. Use contextos para marcar dados por atributos, como origem do conjunto de dados, propriedade ou centro de custos.

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

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

Rastrear fluxos de trabalho

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

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

  • Exemplo 2: use processed_by: analytics_pipeline para impedir que o serviço de processamento de dados personalizados 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 contexto adicional 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 rastreie o histórico do arquivo com lineage: ingested_from_s3.

  • Exemplo 2: incorpore 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 estendem os recursos dos objetos do Cloud Storage. Ao associar pares de chave-valor personalizados diretamente aos objetos armazenados, é possível alcançar os seguintes benefícios:

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

  • Interoperabilidade: ofereça suporte à interoperabilidade com tags de objeto de outros provedores de nuvem e simplifique as migrações, já que os contextos de objeto aceitam valores de string sem pré-definição.

  • Persistência de dados: preserve os dados de contexto durante todo o ciclo de vida do objeto. Ao copiar, reescrever, compor, mover ou restaurar objetos, os contextos são transferidos automaticamente. Também é possível descartar contextos seletivamente durante operações de cópia, reescrita e composição usando o dropContextGroups parâmetro de consulta (por exemplo, dropContextGroups=custom) se você quiser impedir 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 objeto 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 objeto 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 objeto (object_contexts_catalog_view) em conjuntos de dados do Storage Insights.

Preços

Para detalhes de preços, consulte Preços do Cloud Storage.

A seguir