Sobre feeds de mudanças de metadados

Este documento oferece uma visão geral dos feeds de mudança de metadados do Knowledge Catalog (antigo Dataplex Universal Catalog). Esses feeds de mudança de metadados permitem rastrear mudanças de metadados na instância do Knowledge Catalog quase em tempo real e criar fluxos de trabalho orientados a eventos com base nessas mudanças.

Como os feeds de mudança de metadados funcionam

No Knowledge Catalog, uma entrada representa um recurso de dados, como uma tabela do BigQuery, e um aspecto é um conjunto de campos de metadados relacionados anexados a uma entrada que a descreve. Quando uma entrada ou aspecto é criado, atualizado ou excluído, o Knowledge Catalog publica uma mensagem de notificação em um tópico do Pub/Sub especificado. Essas notificações, também chamadas de feed de mudança de metadados, contêm informações sobre a mudança. Isso inclui quando a mudança ocorreu, qual recurso mudou e o tipo de mudança. Para mais informações sobre entradas e aspectos, consulte Sobre o gerenciamento de metadados no Knowledge Catalog.

O diagrama de arquitetura a seguir mostra como o Knowledge Catalog captura mudanças de metadados (criar, atualizar, excluir) e as envia para o Pub/Sub para fluxos de trabalho orientados a eventos downstream.

Mudanças de metadados do Dataplex publicadas no Pub/Sub e consumidas por fluxos de trabalho de assinantes downstream.
Figura 1. Visão geral dos feeds de mudança de metadados

Para controlar quais mudanças geram notificações, é possível configurar um feed de mudança de metadados para monitorar recursos específicos. Para isso, especifique um escopo, como toda a organização, projetos específicos ou grupos de entradas específicos. Embora o escopo permita definir quais recursos monitorar, é possível usar filtros para refinar ainda mais quando o Knowledge Catalog envia notificações. Por exemplo, talvez você queira receber notificações apenas quando as tabelas do tipo bigquery-table forem atualizadas, mas não quando forem criadas ou excluídas. Para fazer isso, aplique um ou mais filtros ao feed de mudança de metadados com base no tipo de entrada, no tipo de aspecto ou no tipo de mudança (CREATE, UPDATE ou DELETE).

Por exemplo, uma empresa de varejo on-line usa o BigQuery para gerenciar o estoque de produtos em um projeto dedicado. Para monitorar apenas as mudanças de esquema nas tabelas de inventário, eles criam um feed de mudança de metadados com o projeto como escopo e aplicam filtros para entry_type=bigquery-table e change_type=UPDATE. Se o esquema de uma tabela crítica, como product_stock, for atualizado, essa mudança vai gerar uma notificação UPDATE que corresponde ao filtro do feed de mudança de metadados. Em seguida, o feed de mudança de metadados envia uma notificação para um tópico do Pub/Sub. Um fluxo de trabalho automatizado inscrito nesse tópico do Pub/Sub pode pausar imediatamente os pipelines de relatórios downstream e alertar a equipe de gerenciamento de inventário para evitar decisões com base em dados inconsistentes.

Casos de uso de feed de mudança de metadados

É possível usar feeds de mudança de metadados para várias finalidades, incluindo:

  • Sincronização de metadados:sincronize continuamente as mudanças de metadados do Knowledge Catalog com um catálogo de dados externo ou de terceiros ou um índice de pesquisa.
  • Aplicação de políticas:aplique ou atualize automaticamente as políticas de segurança quando um aspecto de classificação de dados mudar em uma entrada.
  • Automação da qualidade de dados:acione uma verificação de qualidade de dados ou alerte o proprietário dos dados quando o esquema de uma tabela mudar.
  • Acionamento de ETL/ELT:inicie um job de transformação de dados quando uma nova entrada de tabela for criada ou atualizada.
  • Auditoria:registre todas as mudanças de metadados em uma tabela de auditoria para fins de conformidade.

Principais conceitos e configuração

Um feed de mudança de metadados é um recurso do Knowledge Catalog que monitora mudanças de metadados (criar, atualizar, excluir) para entradas e aspectos e envia notificações para um tópico do Pub/Sub. Na API, esse recurso é chamado metadataFeeds (projects/PROJECT_ID/locations/LOCATION/metadataFeeds/FEED_ID).

Para configurar um feed de mudança de metadados, defina o escopo, os filtros e o destino. Quando ocorre uma mudança de metadados que corresponde ao escopo e aos filtros do feed de mudança de metadados, o Knowledge Catalog publica uma mensagem de notificação no tópico do Pub/Sub de destino.

Configuração do feed de mudança de metadados

Para configurar um feed de mudança de metadados, defina o seguinte:

  • Escopo: o conjunto de recursos a serem monitorados para mudanças, como sua organização inteira, projetos específicos ou grupos de entradas específicos. Na API, especifique o nome do recurso. O exemplo a seguir mostra o formato do nome do recurso para um grupo de entradas: projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID.

  • Filtros: critérios para filtrar quais mudanças geram notificações com base no tipo de entrada, no tipo de aspecto ou no tipo de mudança (CREATE, UPDATE, ou DELETE). Na API, especifique o nome do recurso. O exemplo a seguir mostra o formato do nome do recurso para um tipo de entrada: projects/PROJECT_ID/locations/global/entryTypes/ENTRY_TYPE. Se você não especificar nenhum filtro, todos os tipos de mudança (CREATE, UPDATE e DELETE) no escopo do feed vão gerar notificações.

  • Destino: o tópico do Pub/Sub em que o Knowledge Catalog publica mensagens de notificação. Na API, especifique o nome do tópico. O exemplo a seguir mostra o formato do nome do recurso para um tópico do Pub/Sub: projects/PROJECT_ID/topics/TOPIC_ID.

O exemplo a seguir mostra um feed de mudança de metadados configurado para monitorar projetos PROJECT_ID_1 e PROJECT_ID_2 para eventos CREATE, enviando notificações para TOPIC_ID:

{
  "scope": {
    "projects": [
      "projects/PROJECT_ID_1",
      "projects/PROJECT_ID_2"
    ]
  },
  "filter": {
    "changeTypes": [
      "CREATE"
    ]
  },
  "pubsubTopic": "projects/PROJECT_ID_PUBSUB/topics/TOPIC_ID"
}

Para instruções sobre como criar e gerenciar feeds de mudança de metadados, consulte Receber notificações com feeds de mudança de metadados.

Formato da mensagem de notificação

Quando uma mudança de metadados aciona uma notificação, o Knowledge Catalog publica uma mensagem no tópico do Pub/Sub especificado. O detalhe do evento de mudança é capturado em uma mensagem do Pub/Sub. A mensagem consiste em atributos para filtragem e um payload de dados com detalhes da mudança.

Para mais informações sobre como consumir essas mensagens, consulte Consumir mensagens de notificação.

Atributos

Os atributos permitem filtrar mensagens no tópico. É possível filtrar mensagens na assinatura usando filtros de assinatura do Pub/Sub.

Os seguintes campos são fornecidos nos atributos:

  • timestamp: o carimbo de data/hora em que a mudança ocorreu.
  • entry_name: o nome do recurso da entrada, no formato projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID/entries/ENTRY_ID.
  • feed_name: o nome do recurso do feed de mudança de metadados, no formato projects/PROJECT_ID/locations/LOCATION/metadataChangeFeeds/FEED_ID.
  • entry_type: o nome do recurso do tipo de entrada, no formato projects/PROJECT_NUMBER/locations/LOCATION/entryTypes/ENTRY_TYPE_ID. Para mais informações, consulte Tipos de entrada.
  • entry_change_type: o tipo de mudança: CREATED, UPDATED ou DELETED.

O exemplo a seguir mostra os atributos de um evento de criação de entrada:

{
  "feed_name": "projects/PROJECT_ID/locations/LOCATION/metadataFeeds/FEED_ID",
  "entry_change_type": "CREATE",
  "timestamp": "2026-02-03T23:12:03.054469Z",
  "entry_type": "projects/PROJECT_NUMBER/locations/global/entryTypes/ENTRY_TYPE_ID"
}

Payload de dados

O payload de dados da mensagem do Pub/Sub é uma string JSON que contém detalhes sobre a mudança.

Confira a seguir um exemplo de payload de dados:

{
  "entryName": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID/entries/ENTRY_ID",
  "fullyQualifiedName": "bigquery:PROJECT_ID.DATASET_ID.TABLE_ID",
  "updatedAspects": [
    "projects/PROJECT_NUMBER/locations/global/aspectTypes/updated-aspect-type"
  ],
  "createdAspects": [
    "projects/PROJECT_NUMBER/locations/global/aspectTypes/created-aspect-type"
  ],
  "deletedAspects": [
    "projects/PROJECT_NUMBER/locations/global/aspectTypes/deleted-aspect-type"
  ]
}

Considerações sobre o VPC Service Controls

Os feeds de mudança de metadados são compatíveis com o VPC Service Controls (VPC-SC).

  • Se um feed de mudança de metadados tiver escopo da organização, apenas os projetos no perímetro do VPC Service Controls do feed de mudança de metadados vão gerar notificações.

  • Se um feed de mudança de metadados tiver escopo de projeto ou grupo de entradas, todos os projetos ou grupos de entradas especificados precisarão residir no mesmo perímetro do VPC Service Controls que o feed de mudança de metadados. Caso contrário, a criação do feed de mudança de metadados falhará.

Cotas e limitações

Para informações sobre cotas relacionadas a feeds de mudança de metadados, consulte Cotas e limites do Knowledge Catalog.

Confira as seguintes limitações para feeds de mudança de metadados:

  • Entrega:os feeds de mudança de metadados entregam notificações com base em "pelo menos uma vez". É necessário processar possíveis mensagens duplicadas no assinante.

  • Ordenação:o Knowledge Catalog não garante a ordem de entrega da mensagem.

  • Latência:as notificações de feed de mudança de metadados são quase em tempo real.

  • Atraso na ativação:uma configuração de feed de mudança de metadados recém-criada ou atualizada pode levar até 10 minutos para ser ativada devido ao armazenamento em cache no back-end.

  • Payload:a mensagem de notificação inicial contém apenas assinaturas de mudança. Por exemplo, nome da entrada, tipo de entrada, tipo de mudança e uma lista de tipos ou chaves de aspectos alterados, e não contém os dados reais alterados (o payload do aspecto). É necessário chamar a API Dataplex (GetEntry) para recuperar o estado atual da entrada ou do aspecto, se necessário.

  • Aspectos de armazenamento genéricos:os feeds de mudança de metadados não oferecem suporte a aspectos de armazenamento genéricos.

Preços

Não há cobranças diretas para feeds de mudança de metadados do Knowledge Catalog. No entanto, você incorre em custos pelos recursos usados, como entrega de mensagens do Pub/Sub, armazenamento e saída de dados. Consulte os preços do Pub/Sub.

A seguir