Sobre feeds de mudanças de metadados

Os feeds de mudanças de metadados do Knowledge Catalog (antigo Dataplex Universal Catalog) permitem que você acompanhe as mudanças de metadados em entradas e aspectos na sua organização, projetos ou grupos de entrada quase em tempo real e crie fluxos de trabalho orientados a eventos. Para criar e gerenciar esses feeds, consulte Receber notificações com feeds de alteração de metadados.

Como funcionam os feeds de alteração de metadados

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 o descreve. Quando uma entrada ou um aspecto é criado, atualizado ou excluído, o Knowledge Catalog publica uma mensagem de notificação em um tópico do Pub/Sub que você especifica. Essas notificações, também chamadas de feed de alterações de metadados, contêm informações sobre a mudança. Isso inclui quando a mudança aconteceu, 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 downstream orientados a eventos.

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

Para controlar quais mudanças geram notificações, configure um feed de mudanças de metadados para monitorar recursos específicos. Para fazer isso, especifique um escopo, como toda a organização, projetos específicos ou grupos de entrada específicos. Enquanto o escopo permite definir quais recursos monitorar, você pode usar filtros para refinar ainda mais quando o Knowledge Catalog envia notificações. Por exemplo, talvez você queira receber notificações apenas quando 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ças de metadados com base no tipo de entrada, de aspecto ou de mudança (CREATE, UPDATE ou DELETE).

Por exemplo, uma loja on-line usa o BigQuery para gerenciar o inventário 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ças 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 alteração vai gerar uma notificação do UPDATE que corresponde ao filtro do feed de alterações de metadados. O feed de alterações 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 do feed de alterações de metadados

É possível usar feeds de alterações de metadados para várias finalidades, incluindo:

  • Sincronização de metadados:sincronize continuamente as mudanças de metadados do Knowledge Catalog com um Data Catalog ou índice da Pesquisa externo ou de terceiros.
  • 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:iniciar um job de transformação de dados quando uma nova entrada de tabela é criada ou atualizada.
  • Auditoria:registre todas as alterações de metadados em uma tabela de auditoria para fins de conformidade.

Conceitos básicos e configuração

Um feed de mudanças 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 de metadataFeeds (projects/PROJECT_ID/locations/LOCATION/metadataFeeds/FEED_ID).

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

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

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

  • Escopo: o conjunto de recursos que serão monitorados para detectar mudanças, como toda a organização, projetos específicos ou grupos de entrada específicos. Na API, você especifica 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, de aspecto ou de mudança (CREATE, UPDATE ou DELETE). Na API, você especifica 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 alteração (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, você especifica 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 alterações de metadados configurado para monitorar os projetos PROJECT_ID_1 e PROJECT_ID_2 em busca de 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"
}

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 especificado do Pub/Sub. Os detalhes do evento de alteração são capturados em uma mensagem do Pub/Sub. A mensagem consiste em atributos para filtragem e um payload de dados com detalhes da alteração.

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 de quando a mudança aconteceu.
  • 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 alterações 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 alteração.

Veja 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 alterações de metadados são compatíveis com o VPC Service Controls (VPC-SC).

  • Se um feed de alterações de metadados tiver escopo de organização, somente os projetos dentro do perímetro do VPC Service Controls do feed de alterações de metadados vão gerar notificações.

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

Cotas e limitações

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

Confira as seguintes limitações dos feeds de alterações de metadados:

  • Entrega:os feeds de alteração de metadados enviam notificações "pelo menos uma vez". É preciso lidar com possíveis mensagens duplicadas no assinante.

  • Ordenação:o Knowledge Catalog não garante a ordem de entrega das mensagens.

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

  • Atraso na ativação:uma configuração de feed de alterações 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 alteração e uma lista de tipos ou chaves de aspecto alterados, e não contém os dados alterados reais (o payload do aspecto). Chame 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 alteração de metadados não são compatíveis com aspectos de armazenamento genéricos.

Preços

O Knowledge Catalog oferece feeds de mudanças de metadados sem custo financeiro adicional. No entanto, você vai receber cobranças pelos recursos usados, como entrega de mensagens do Pub/Sub, armazenamento e saída de dados. Para mais informações, consulte os preços do Pub/Sub.

A seguir