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

Este documento descreve como configurar feeds de mudança de metadados do Dataplex Universal Catalog para receber notificações pelo Pub/Sub quando os metadados no Dataplex Universal 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 Universal Catalog.

Enable the Dataplex Universal Catalog and Pub/Sub APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.
Enable the 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 curto 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 conta de serviço do Dataplex Universal Catalog têm os papéis e as permissões do IAM necessários.

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

Para ter 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 papéis do IAM a seguir 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 seguintes permissões 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 entradas)
- 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.

Funções e permissões da conta de serviço do Dataplex Universal Catalog

Para garantir que a conta de serviço do Dataplex Universal Catalog tenha a permissão necessária para publicar mensagens de feeds de mudanças de metadados, peça ao administrador para conceder a ela o papel do IAM de Editor do Pub/Sub (roles/pubsub.publisher) 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 permissão pubsub.topics.publish, 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 catálogo universal do Dataplex com papéis personalizados ou outros papéis predefinidos.

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

O agente de serviço do Dataplex Universal Catalog é criado quando você ativa a API Dataplex. É possível identificar o agente de serviço pelo 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 Dataplex Universal Catalog precisa da capacidade de publicar mensagens no seu tópico do Pub/Sub. Para conceder essa permissão, atribua à conta de serviço o papel de editor 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 seu tópico do Pub/Sub em que as mensagens do feed de mudanças de metadados são publicadas.
PROJECT_NUMBER: o número do projeto do Dataplex Universal Catalog em que a conta de serviço está localizada.

Console

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

Acessar tópicos
Selecione o tema que você está usando para notificações do 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 Dataplex Universal Catalog: service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com.
No campo Atribuir papéis, selecione Publicador do Pub/Sub.
Clique em Salvar.

Criar um feed 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 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 Dataplex Universal 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 método projects.locations.metadataFeeds.create.

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 do 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 do 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 entradas 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 entradas a ser monitorado, por exemplo, example-entry-group
TOPIC_ID: o ID do tópico do Pub/Sub em que as mensagens do 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 do 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

Você pode conferir os detalhes de um feed de mudanças de metadados.

REST

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

Execute este comando:

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

Substitua:

FEED_ID: o ID do feed de mudanças de metadados que você quer ver, 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 método projects.locations.metadataFeeds.list.

Execute este comando:

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 método projects.locations.metadataFeeds.patch.

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 ele publique novas mudanças de metadados no seu tópico do Pub/Sub. No entanto, isso não exclui o tema nem a assinatura associada ao feed. É necessário excluí-los manualmente se não forem mais necessários.

Antes de excluir o feed ou a inscrição, verifique se os aplicativos inscritos processaram todas as mensagens pendentes na inscrição do Pub/Sub.

REST

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

Execute este comando:

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 Dataplex Universal Catalog publica mensagens no tópico especificado do Pub/Sub quando ocorrem mudanças nos metadados. Para consumir essas mensagens, crie uma assinatura do Pub/Sub para o tópico.

Por exemplo, é possível criar uma assinatura de extração e usar a Google Cloud CLI para ver 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 do feed de mudanças de metadados são publicadas.
Receber mensagens da assinatura:
```
gcloud pubsub subscriptions pull SUBSCRIPTION_ID --auto-ack --limit=10
```
Substitua:
- SUBSCRIPTION_ID: o ID da assinatura de que você quer extrair mensagens

Para mais informações sobre como processar mensagens do Pub/Sub, consulte Receber mensagens de uma assinatura de 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 Dataplex Universal Catalog.
Resolver problemas com 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

Funções e permissões da conta de serviço do Dataplex Universal Catalog

Conceder permissões à conta de serviço do Dataplex Universal 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