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

Este documento descreve como configurar feeds de mudança 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

Conheça o Pub/Sub e a API Dataplex.

  1. 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

  2. Crie um tópico do Pub/Sub para receber notificações. Para mais informações, consulte Criar um tópico.

  3. Instale gcloud. Verifique se o alias curto de gcloud está definido.

  4. 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"'

  5. 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 Knowledge Catalog têm os papéis e as permissões necessários do IAM.

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:

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.

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 os papéis do IAM Publicador do Pub/Sub (roles/pubsub.publisher) e Leitor do Pub/Sub (roles/pubsub.viewer) à 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 as permissões pubsub.topics.publish e pubsub.topics.get, que são necessárias 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 precisa publicar mensagens no tópico do Pub/Sub e recuperar metadados do tópico. Para conceder essas permissões, atribua à conta de serviço o papel de Publicador do Pub/Sub (roles/pubsub.publisher) e o papel de Leitor do Pub/Sub (roles/pubsub.viewer) 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"

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

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 Knowledge Catalog em que a conta de serviço está localizada.

Console

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

    Acessar tópicos

  2. 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.

  3. Na guia Permissões, clique em Adicionar principal.

  4. No campo Novos principais, insira a conta de serviço do Knowledge Catalog: service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com.

  5. No campo Atribuir papéis, selecione Publicador do Pub/Sub.

  6. Clique em Adicionar outro papel e selecione Leitor do Pub/Sub.

  7. 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 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 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 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 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 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 Knowledge 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 por pull e usar a Google Cloud CLI para ver mensagens:

  1. 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.

  2. 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 por pull. Para informações sobre o formato da mensagem, consulte Payload de dados.

A seguir