Receber notificações com feeds de mudanças de metadados

Este documento descreve como configurar feeds de mudanças de metadados do Knowledge Catalog (antigo Dataplex Universal Catalog) para receber notificações pelo Pub/Sub quando os metadados no Knowledge Catalog são criados, atualizados ou excluídos.

Para mais informações sobre feeds de mudanças de metadados, consulte Visão geral dos feeds de mudanças de metadados.

Antes de começar

Familiarize-se com o Pub/Sub e a API Dataplex.

Ative as APIs Dataplex e Pub/Sub.
Funções necessárias para ativar APIs
Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.
Ativar as APIs
Crie um tópico do Pub/Sub para receber notificações. Para mais informações, consulte Criar um tópico.
Instale gcloud. Verifique se o alias abreviado de gcloud está definido.
Defina um alias de gcurl. Isso cria um atalho que inclui seu token de autenticação e define o tipo de conteúdo JSON para solicitações de API:
```
alias gcurl='curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json"'
```
Defina a variável DATAPLEX_API:
```
DATAPLEX_API="dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION"
```
Substitua:
- PROJECT_ID: o ID do projeto em que a API Dataplex está ativada
- LOCATION: o local em que o job é executado, por exemplo, us-central1, europe-west3 ou asia-south1

Papéis e permissões necessárias

Para configurar feeds de mudanças de metadados, verifique se você e a Knowledge Catalog conta de serviço têm os papéis e permissões do IAM necessários.

Funções e permissões do usuário

Para receber as permissões necessárias para exportar metadados e acessar mensagens de feeds de mudanças de metadados, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto ou na organização:

Exportar metadados: exportador de grupo de entrada do Dataplex (roles/dataplex.entryGroupExporter)
Acessar mensagens de feeds de mudanças de metadados: Assinante do Pub/Sub (roles/pubsub.subscriber)

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 exportar metadados e acessar mensagens de feeds de mudanças de metadados. 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 exportar metadados e acessar mensagens de feeds de mudanças de metadados:

Exportar metadados:
- dataplex.metadataFeeds.create no projeto
- dataplex.entryGroups.export no recurso que define o escopo do feed (organização, projeto ou grupo de entrada)
- resourcemanager.projects.get no projeto
- resourcemanager.projects.list no projeto
Acessar mensagens de feeds de mudanças de metadados:
- pubsub.subscriptions.consume na assinatura
- pubsub.topics.attachSubscription no tópico

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

Papéis e permissões da conta de serviço do Knowledge Catalog

Para garantir que a conta de serviço do Knowledge Catalog tenha a permissão necessária para publicar mensagens de feeds de mudanças de metadados, peça ao administrador para conceder o Publicador do Pub/Sub (roles/pubsub.publisher) papel do IAM à conta de serviço do Knowledge Catalog no tópico do Pub/Sub.

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém a pubsub.topics.publish permissão, que é necessária para publicar mensagens de feeds de mudanças de metadados.

O administrador também pode conceder essa permissão à conta de serviço do Knowledge Catalog com papéis personalizados ou outros papéis predefinidos.

Conceder permissões à conta de serviço do Knowledge Catalog

O agente de serviço no Knowledge Catalog é criado quando você ativa a API Dataplex. É possível identificar o agente de serviço pelo ID do e-mail:

service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com

Aqui, PROJECT_NUMBER é o número do projeto em que você ativou a API Dataplex.

A conta de serviço do Knowledge Catalog exige a capacidade de publicar mensagens no tópico do Pub/Sub. Para conceder essa permissão, atribua à conta de serviço o papel de Publicador do Pub/Sub (roles/pubsub.publisher) no tópico do Pub/Sub:

gcloud

Execute o comando gcloud pubsub topics add-iam-policy-binding:

gcloud pubsub topics add-iam-policy-binding TOPIC_ID \
    --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" \
    --role="roles/pubsub.publisher"

Substitua:

TOPIC_ID: o ID do tópico do Pub/Sub em que as mensagens de feed de mudanças de metadados são publicadas.
PROJECT_NUMBER: o número do projeto do Knowledge Catalog em que a conta de serviço está localizada.

Console

No Google Cloud console, acesse a página Tópicos do Pub/Sub.

Acessar tópicos
Selecione o tópico que você está usando para notificações de feed de metadados e, se necessário, clique em Mostrar painel de informações.
Na guia Permissões, clique em Adicionar principal.
No campo Novos principais, insira a conta de serviço do Knowledge Catalog : service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com.
No campo Atribuir papéis, selecione Editor do Pub/Sub.
Clique em Salvar.

Criar um feed de mudanças de metadados

Para controlar quais mudanças geram notificações, é possível configurar 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. Embora o escopo permita definir quais recursos monitorar, é possível usar filtros para refinar ainda mais quando o Knowledge Catalog envia notificações.

Para mais informações, consulte Feed de mudanças de metadados.

REST

Para criar um feed de mudanças de metadados, use o projects.locations.metadataFeeds.create método.

Escopo da organização

Execute o comando a seguir para criar um feed de mudanças de metadados que monitora toda a organização:

gcurl -X POST -d "$(cat <<EOF
{
  "scope": {
    "organizationLevel": true
  },
  "pubsubTopic": "projects/PROJECT_ID_PUBSUB/topics/TOPIC_ID"
}
EOF
)" "https://${DATAPLEX_API}/metadataFeeds?metadataFeedId=FEED_ID"

Substitua:

PROJECT_ID_PUBSUB: o ID do projeto em que o tópico do Pub/Sub está localizado, por exemplo, example-project
TOPIC_ID: o ID do tópico do Pub/Sub em que as mensagens de feed de mudanças de metadados são publicadas, por exemplo, example-topic
FEED_ID: o ID do feed de mudanças de metadados que você quer criar, por exemplo, example-feed

Escopo do projeto

Execute o comando a seguir para criar um feed de mudanças de metadados que monitora projetos específicos:

gcurl -X POST -d "$(cat <<EOF
{
  "scope": {
    "projects": [
      "projects/PROJECT_ID_1",
      "projects/PROJECT_ID_2"
    ]
  },
  "pubsubTopic": "projects/PROJECT_ID_PUBSUB/topics/TOPIC_ID"
}
EOF
)" "https://${DATAPLEX_API}/metadataFeeds?metadataFeedId=FEED_ID"

Substitua:

PROJECT_ID_PUBSUB: o ID do projeto em que o tópico do Pub/Sub está localizado, por exemplo, example-project
TOPIC_ID: o ID do tópico do Pub/Sub em que as mensagens de feed de mudanças de metadados são publicadas, por exemplo, example-topic
FEED_ID: o ID do feed de mudanças de metadados que você quer criar, por exemplo, example-feed

Escopo do grupo de entrada

Execute o comando a seguir para criar um feed de mudanças de metadados que monitora grupos de entrada específicos:

gcurl -X POST -d "$(cat <<EOF
{
  "scope": {
    "entryGroups": [
      "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID_1",
      "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID_2"
    ]
  },
  "pubsubTopic": "projects/PROJECT_ID_PUBSUB/topics/TOPIC_ID"
}
EOF
)" "https://${DATAPLEX_API}/metadataFeeds?metadataFeedId=FEED_ID"

Substitua:

PROJECT_ID_PUBSUB: o ID do projeto em que o tópico do Pub/Sub está localizado, por exemplo, example-project
LOCATION: o local em que você quer criar o feed, por exemplo, us-central1
ENTRY_GROUP_ID: o ID do grupo de entrada a ser monitorado, por exemplo, example-entry-group
TOPIC_ID: o ID do tópico do Pub/Sub em que as mensagens de feed de mudanças de metadados são publicadas, por exemplo, example-topic
FEED_ID: o ID do feed de mudanças de metadados que você quer criar, por exemplo, example-feed

Com filtros

Execute o comando a seguir para criar um feed de mudanças de metadados com filtros (filtragem por tipo de entrada):

gcurl -X POST -d "$(cat <<EOF
{
  "scope": {
    "projects": [
      "projects/PROJECT_ID_1",
      "projects/PROJECT_ID_2"
    ]
  },
  "filter": {
    "entryTypes": [
      "projects/PROJECT_ID/locations/global/entryTypes/bigquery-table"
    ]
  },
  "pubsubTopic": "projects/PROJECT_ID_PUBSUB/topics/TOPIC_ID"
}
EOF
)" "https://${DATAPLEX_API}/metadataFeeds?metadataFeedId=FEED_ID"

Substitua:

PROJECT_ID_PUBSUB: o ID do projeto em que o tópico do Pub/Sub está localizado, por exemplo, example-project
TOPIC_ID: o ID do tópico do Pub/Sub em que as mensagens de feed de mudanças de metadados são publicadas, por exemplo, example-topic
FEED_ID: o ID do feed de mudanças de metadados que você quer criar, por exemplo, example-feed

Resposta:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.dataplex.v1.OperationMetadata",
    "createTime": "2023-10-02T15:01:23Z",
    "target": "projects/PROJECT_ID/locations/LOCATION/metadataFeeds/FEED_ID",
    "verb": "create",
    "apiVersion": "v1"
  },
  "done": false
}

Ver feeds de mudanças de metadados

É possível conferir os detalhes de um feed de mudanças de metadados.

REST

Para conferir um feed de mudanças de metadados, use o projects.locations.metadataFeeds.get método.

Execute o comando a seguir:

gcurl "https://${DATAPLEX_API}/metadataFeeds/FEED_ID"

Substitua:

FEED_ID: o ID do feed de mudanças de metadados que você quer conferir, por exemplo, example-feed

Listar feeds de mudanças de metadados

É possível listar os feeds de mudanças de metadados em um projeto e local.

REST

Para listar feeds de mudanças de metadados, use o projects.locations.metadataFeeds.list método.

Execute o comando a seguir:

gcurl "https://${DATAPLEX_API}/metadataFeeds"

Atualizar um feed de mudanças de metadados

É possível atualizar o escopo ou os filtros de um feed de mudanças de metadados.

REST

Para atualizar um feed de mudanças de metadados, use o projects.locations.metadataFeeds.patch método.

Execute o comando a seguir para atualizar o feed de mudanças de metadados e remover os filtros de tipo de entrada:

gcurl -X PATCH -d "$(cat <<EOF
{
  "filter": {
    "entryTypes": []
  }
}
EOF
)" "https://${DATAPLEX_API}/metadataFeeds/FEED_ID?updateMask=filter"

Substitua:

FEED_ID: o ID do feed de mudanças de metadados que você quer atualizar, por exemplo, example-feed

Excluir um feed de mudanças de metadados

É possível excluir um feed de mudanças de metadados se você não precisar mais receber notificações.

A exclusão de um feed de mudanças de metadados impede que o feed publique novas mudanças de metadados no tópico do Pub/Sub. No entanto, ele não exclui o tópico ou a assinatura associada ao feed. É necessário excluí-los manualmente se eles não forem mais necessários.

Antes de excluir o feed ou a assinatura, verifique se os aplicativos assinantes processaram todas as mensagens pendentes na assinatura do Pub/Sub.

REST

Para excluir um feed de mudanças de metadados, use o projects.locations.metadataFeeds.delete método.

Execute o comando a seguir:

gcurl -X DELETE \
"https://${DATAPLEX_API}/metadataFeeds/FEED_ID"

Substitua:

FEED_ID: o ID do feed de mudanças de metadados que você quer excluir, por exemplo, example-feed

Consumir mensagens de notificação

Depois de configurar um feed de mudanças de metadados, o Knowledge Catalog publica mensagens no tópico do Pub/Sub especificado quando ocorrem mudanças de metadados. Para consumir essas mensagens, crie uma assinatura do Pub/Sub para o tópico.

Por exemplo, é possível criar uma assinatura por pull e usar a Google Cloud CLI para conferir mensagens:

Crie uma assinatura:
```
gcloud pubsub subscriptions create SUBSCRIPTION_ID --topic=TOPIC_ID
```
Substitua:
- SUBSCRIPTION_ID: o ID da assinatura que você quer criar
- TOPIC_ID: o ID do tópico do Pub/Sub em que as mensagens de feed de mudanças de metadados são publicadas.
Extraia mensagens da assinatura:
```
gcloud pubsub subscriptions pull SUBSCRIPTION_ID --auto-ack --limit=10
```
Substitua:
- SUBSCRIPTION_ID: o ID da assinatura da qual você quer extrair mensagens

Para mais informações sobre o processamento de mensagens do Pub/Sub, consulte Receber mensagens de uma assinatura por pull. Para informações sobre o formato da mensagem, consulte Payload de dados.

A seguir

Leia a visão geral dos feeds de mudanças de metadados.
Saiba mais sobre o IAM e o controle de acesso do Knowledge Catalog.
Resolver problemas de feeds de mudanças de metadados.

Receber notificações com feeds de mudanças de metadados Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Papéis e permissões necessárias

Funções e permissões do usuário

Permissões necessárias

Papéis e permissões da conta de serviço do Knowledge Catalog

Conceder permissões à conta de serviço do Knowledge Catalog

gcloud

Console

Criar um feed de mudanças de metadados

REST

Ver feeds de mudanças de metadados

REST

Listar feeds de mudanças de metadados

REST

Atualizar um feed de mudanças de metadados

REST

Excluir um feed de mudanças de metadados

REST

Consumir mensagens de notificação

A seguir

Receber notificações com feeds de mudanças de metadados