Ricevere notifiche con i feed di modifica dei metadati

Questo documento descrive come configurare i feed di modifica dei metadati di Knowledge Catalog (in precedenza Dataplex Universal Catalog) per ricevere notifiche tramite Pub/Sub quando i metadati all'interno di Knowledge Catalog vengono creati, aggiornati o eliminati.

Per ulteriori informazioni sui feed di modifiche ai metadati, vedi Panoramica dei feed di modifiche ai metadati.

Prima di iniziare

Familiarizza con Pub/Sub e l'API Dataplex.

  1. Abilitare le API Dataplex e Pub/Sub.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo dei servizi (roles/serviceusage.serviceUsageAdmin), che include l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.

    Abilita le API

  2. Crea un argomento Pub/Sub per ricevere le notifiche. Per ulteriori informazioni, vedi Creare un argomento.

  3. Installa gcloud. Assicurati che l'alias breve di gcloud sia impostato.

  4. Imposta un alias di gcurl. In questo modo viene creato un collegamento che include il token di autenticazione e imposta il tipo di contenuti JSON per le richieste API:

    alias gcurl='curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json"'

  5. Imposta la variabile DATAPLEX_API:

    DATAPLEX_API="dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION"

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID progetto in cui è abilitata l'API Dataplex
    • LOCATION: la località in cui viene eseguito il job, ad esempio us-central1, europe-west3 o asia-south1

Ruoli e autorizzazioni richiesti

Per configurare i feed delle modifiche ai metadati, assicurati che tu e il service account Knowledge Catalog disponiate dei ruoli e delle autorizzazioni IAM richiesti.

Ruoli utente e autorizzazioni

Per ottenere le autorizzazioni necessarie per esportare i metadati e accedere ai messaggi dei feed delle modifiche ai metadati, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto o nell'organizzazione:

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questi ruoli predefiniti contengono le autorizzazioni necessarie per esportare i metadati e accedere ai messaggi dei feed delle modifiche ai metadati. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per esportare i metadati e accedere ai messaggi dei feed delle modifiche ai metadati sono necessarie le seguenti autorizzazioni:

  • Esporta metadati:
    • dataplex.metadataFeeds.create sul progetto
    • dataplex.entryGroups.export sulla risorsa che definisce l'ambito del feed (organizzazione, progetto o gruppo di voci)
    • resourcemanager.projects.get sul progetto
    • resourcemanager.projects.list sul progetto
  • Accedi ai messaggi dei feed di modifica dei metadati:
    • pubsub.subscriptions.consume sull'abbonamento
    • pubsub.topics.attachSubscription sull'argomento

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Ruoli e autorizzazioni del account di servizio di Knowledge Catalog

Per assicurarti che il account di servizio Knowledge Catalog disponga dell'autorizzazione necessaria per pubblicare messaggi dei feed delle modifiche ai metadati, chiedi all'amministratore di concedere al account di servizio Knowledge Catalog il ruolo IAM Publisher Pub/Sub (roles/pubsub.publisher) e Visualizzatore Pub/Sub (roles/pubsub.viewer) nell'argomento Pub/Sub.

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene le autorizzazioni pubsub.topics.publish e pubsub.topics.get necessarie per pubblicare i messaggi dei feed delle modifiche ai metadati.

L'amministratore potrebbe anche essere in grado di concedere al account di servizio Knowledge Catalog questa autorizzazione tramite ruoli personalizzati o altri ruoli predefiniti.

Concedi le autorizzazioni al account di servizio di Knowledge Catalog

Il service agent in Knowledge Catalog viene creato quando abiliti l'API Dataplex. Puoi identificare l'agente di servizio in base al suo ID email:

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

In questo caso, PROJECT_NUMBER è il numero di progetto del progetto in cui hai abilitato l'API Dataplex.

Il account di servizio Knowledge Catalog richiede la possibilità di pubblicare messaggi nell'argomento Pub/Sub e recuperare i metadati dell'argomento. Per concedere queste autorizzazioni, assegna al account di servizio il ruolo Pub/Sub Publisher (roles/pubsub.publisher) e il ruolo Pub/Sub Viewer (roles/pubsub.viewer) nell'argomento Pub/Sub:

gcloud

Esegui il 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"

Sostituisci quanto segue:

  • TOPIC_ID: l'ID dell'argomento Pub/Sub a cui vengono pubblicati i messaggi del feed delle modifiche ai metadati.
  • PROJECT_NUMBER: il numero di progetto del progetto Knowledge Catalog in cui si trova il account di servizio.

Console

  1. Nella console Google Cloud , vai alla pagina Argomenti di Pub/Sub.

    Vai agli argomenti

  2. Seleziona l'argomento che utilizzi per le notifiche del feed di metadati e, se necessario, fai clic su Mostra riquadro informazioni.

  3. Nella scheda Autorizzazioni, fai clic su Aggiungi entità.

  4. Nel campo Nuove entità, inserisci l'account di servizio Knowledge Catalog: service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com.

  5. Nel campo Assegna i ruoli, seleziona Pub/Sub Publisher.

  6. Fai clic su Aggiungi un altro ruolo e seleziona Visualizzatore Pub/Sub.

  7. Fai clic su Salva.

Crea un feed di modifiche ai metadati

Per controllare quali modifiche generano notifiche, puoi configurare un feed delle modifiche ai metadati per monitorare risorse specifiche. Per farlo, specifica un ambito, ad esempio l'intera organizzazione, progetti specifici o gruppi di voci specifici. L'ambito consente di definire quali risorse monitorare, mentre i filtri possono essere utilizzati per perfezionare ulteriormente quando Knowledge Catalog invia le notifiche.

Per saperne di più, consulta Feed delle modifiche ai metadati.

REST

Per creare un feed delle modifiche ai metadati, utilizza il metodo projects.locations.metadataFeeds.create.

Ambito dell'organizzazione

Esegui questo comando per creare un feed delle modifiche ai metadati che monitora l'intera organizzazione:

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"

Sostituisci quanto segue:

  • PROJECT_ID_PUBSUB: l'ID progetto in cui si trova l'argomento Pub/Sub, ad esempio example-project
  • TOPIC_ID: l'ID argomento Pub/Sub a cui vengono pubblicati i messaggi del feed delle modifiche ai metadati, ad esempio example-topic
  • FEED_ID: l'ID del feed delle modifiche ai metadati che vuoi creare, ad esempio example-feed

Ambito del progetto

Esegui questo comando per creare un feed delle modifiche ai metadati che monitora progetti specifici:

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"

Sostituisci quanto segue:

  • PROJECT_ID_PUBSUB: l'ID progetto in cui si trova l'argomento Pub/Sub, ad esempio example-project
  • TOPIC_ID: l'ID argomento Pub/Sub a cui vengono pubblicati i messaggi del feed delle modifiche ai metadati, ad esempio example-topic
  • FEED_ID: l'ID del feed delle modifiche ai metadati che vuoi creare, ad esempio example-feed

Ambito del gruppo di voci

Esegui questo comando per creare un feed delle modifiche ai metadati che monitora gruppi di voci specifici:

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"

Sostituisci quanto segue:

  • PROJECT_ID_PUBSUB: l'ID progetto in cui si trova l'argomento Pub/Sub, ad esempio example-project
  • LOCATION: la località in cui vuoi creare il feed, ad esempio us-central1
  • ENTRY_GROUP_ID: l'ID del gruppo di voci da monitorare, ad esempio example-entry-group
  • TOPIC_ID: l'ID argomento Pub/Sub a cui vengono pubblicati i messaggi del feed delle modifiche ai metadati, ad esempio example-topic
  • FEED_ID: l'ID del feed delle modifiche ai metadati che vuoi creare, ad esempio example-feed

Con filtri

Esegui il comando seguente per creare un feed delle modifiche ai metadati con filtri (filtraggio per tipo di voce):

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"

Sostituisci quanto segue:

  • PROJECT_ID_PUBSUB: l'ID progetto in cui si trova l'argomento Pub/Sub, ad esempio example-project
  • TOPIC_ID: l'ID argomento Pub/Sub a cui vengono pubblicati i messaggi del feed delle modifiche ai metadati, ad esempio example-topic
  • FEED_ID: l'ID del feed delle modifiche ai metadati che vuoi creare, ad esempio example-feed

Risposta:

{
  "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
}

Visualizzare i feed delle modifiche ai metadati

Puoi visualizzare i dettagli di un feed di modifiche ai metadati.

REST

Per visualizzare un feed delle modifiche ai metadati, utilizza il metodo projects.locations.metadataFeeds.get.

Esegui questo comando:

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

Sostituisci quanto segue:

  • FEED_ID: l'ID del feed delle modifiche ai metadati che vuoi visualizzare, ad esempio example-feed

Elenca i feed di modifiche ai metadati

Puoi elencare i feed di modifica dei metadati in un progetto e una località.

REST

Per elencare i feed delle modifiche ai metadati, utilizza il metodo projects.locations.metadataFeeds.list.

Esegui questo comando:

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

Aggiornare un feed delle modifiche ai metadati

Puoi aggiornare l'ambito o i filtri di un feed di modifiche ai metadati esistente.

REST

Per aggiornare un feed di modifiche ai metadati, utilizza il metodo projects.locations.metadataFeeds.patch.

Esegui questo comando per aggiornare il feed delle modifiche ai metadati in modo da rimuovere i filtri del tipo di voce:

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

Sostituisci quanto segue:

  • FEED_ID: l'ID del feed delle modifiche ai metadati che vuoi aggiornare, ad esempio example-feed

Eliminare un feed delle modifiche ai metadati

Puoi eliminare un feed delle modifiche ai metadati se non hai più bisogno di ricevere notifiche.

L'eliminazione di un feed di modifiche ai metadati impedisce la pubblicazione di nuove modifiche ai metadati nell'argomento Pub/Sub. Tuttavia, non elimina l'argomento o l'abbonamento associato al feed. Devi eliminarli manualmente se non ti servono più.

Prima di eliminare il feed o l'abbonamento, assicurati che le applicazioni abbonate abbiano elaborato tutti i messaggi in sospeso nell'abbonamento Pub/Sub.

REST

Per eliminare un feed delle modifiche ai metadati, utilizza il metodo projects.locations.metadataFeeds.delete.

Esegui questo comando:

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

Sostituisci quanto segue:

  • FEED_ID: l'ID del feed delle modifiche ai metadati che vuoi eliminare, ad esempio example-feed

Utilizzare i messaggi di notifica

Dopo aver configurato un feed delle modifiche ai metadati, Knowledge Catalog pubblica messaggi nell'argomento Pub/Sub specificato quando si verificano modifiche ai metadati. Per utilizzare questi messaggi, crea una sottoscrizione Pub/Sub all'argomento.

Ad esempio, puoi creare una sottoscrizione pull e utilizzare Google Cloud CLI per visualizzare i messaggi:

  1. Crea un abbonamento:

    gcloud pubsub subscriptions create SUBSCRIPTION_ID --topic=TOPIC_ID

    Sostituisci quanto segue:

    • SUBSCRIPTION_ID: l'ID abbonamento che vuoi creare
    • TOPIC_ID: l'ID argomento Pub/Sub a cui vengono pubblicati i messaggi del feed delle modifiche ai metadati.

  2. Esegui il pull dei messaggi dalla sottoscrizione:

    gcloud pubsub subscriptions pull SUBSCRIPTION_ID --auto-ack --limit=10

    Sostituisci quanto segue:

    • SUBSCRIPTION_ID: l'ID sottoscrizione da cui vuoi estrarre i messaggi

Per ulteriori informazioni sull'elaborazione dei messaggi Pub/Sub, consulta la pagina Ricevere messaggi da una sottoscrizione pull. Per informazioni sul formato del messaggio, consulta Payload di dati.

Passaggi successivi