Ricevere notifiche con i feed di modifica dei metadati

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

Per saperne di più sui feed di modifiche dei metadati, consulta la panoramica dei feed di modifiche dei metadati.

Prima di iniziare

Acquisisci familiarità con Pub/Sub e l'API Dataplex.

  1. Abilita l'API Dataplex e le API Pub/Sub.

    Ruoli richiesti per abilitare le API

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

    Abilita le API

  2. Crea un argomento Pub/Sub per ricevere le notifiche. Per saperne di più, consulta Creare un argomento.

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

  4. Imposta un alias di gcurl. In questo modo viene creato un collegamento che include il token di autenticazione e viene impostato 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 di modifiche dei metadati, assicurati che tu e il Knowledge Catalog service account 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 di modifiche dei metadati, chiedi all'amministratore di concederti i seguenti ruoli IAM sul progetto o sull'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 di modifiche dei 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 di modifiche dei 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 modifiche dei metadati:
    • pubsub.subscriptions.consume sulla sottoscrizione
    • 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 di Knowledge Catalog disponga dell'autorizzazione necessaria per pubblicare i messaggi dei feed di modifiche dei metadati, chiedi all'amministratore di concedere il ruolo IAM Pub/Sub Publisher (roles/pubsub.publisher) al account di servizio di Knowledge Catalog sull'argomento Pub/Sub.

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

Questo ruolo predefinito contiene l' pubsub.topics.publish autorizzazione, necessaria per pubblicare i messaggi dei feed di modifiche dei metadati.

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

Concedi le autorizzazioni al account di servizio di Knowledge Catalog

L'agente di servizio 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

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

Il account di servizio di Knowledge Catalog deve essere in grado di pubblicare messaggi nell'argomento Pub/Sub. Per concedere questa autorizzazione, assegna al account di servizio il ruolo Pub/Sub Publisher (roles/pubsub.publisher) sull'argomento Pub/Sub:

gcloud

Esegui il gcloud pubsub topics add-iam-policy-binding comando:

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

Sostituisci quanto segue:

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

Console

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

    Vai agli argomenti

  2. Seleziona l'argomento che utilizzi per le notifiche dei 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 il account di servizio di Knowledge Catalog : service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com.

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

  6. Fai clic su Salva.

Crea un feed di modifiche dei metadati

Per controllare quali modifiche generano notifiche, puoi configurare un feed di modifiche dei metadati in modo che monitori risorse specifiche. Per farlo, devi specificare un ambito, ad esempio l'intera organizzazione, progetti specifici o gruppi di voci specifici. Mentre l'ambito ti consente di definire quali risorse monitorare, puoi utilizzare i filtri per perfezionare ulteriormente quando Knowledge Catalog invia le notifiche.

Per saperne di più, consulta Feed di modifiche dei metadati.

REST

Per creare un feed di modifiche dei metadati, utilizza il projects.locations.metadataFeeds.create metodo.

Ambito dell'organizzazione

Esegui il comando seguente per creare un feed di modifiche dei 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 dell'argomento Pub/Sub in cui vengono pubblicati i messaggi dei feed di modifiche dei metadati, ad esempio example-topic
  • FEED_ID: l'ID del feed di modifiche dei metadati che vuoi creare, ad esempio example-feed

Ambito del progetto

Esegui il comando seguente per creare un feed di modifiche dei 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 dell'argomento Pub/Sub in cui vengono pubblicati i messaggi dei feed di modifiche dei metadati, ad esempio example-topic
  • FEED_ID: l'ID del feed di modifiche dei metadati che vuoi creare, ad esempio example-feed

Ambito del gruppo di voci

Esegui il comando seguente per creare un feed di modifiche dei 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 dell'argomento Pub/Sub in cui vengono pubblicati i messaggi dei feed di modifiche dei metadati, ad esempio example-topic
  • FEED_ID: l'ID del feed di modifiche dei metadati che vuoi creare, ad esempio example-feed

Con i filtri

Esegui il comando seguente per creare un feed di modifiche dei 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 dell'argomento Pub/Sub in cui vengono pubblicati i messaggi dei feed di modifiche dei metadati, ad esempio example-topic
  • FEED_ID: l'ID del feed di modifiche dei 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
}

Visualizza i feed di modifiche dei metadati

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

REST

Per visualizzare un feed di modifiche dei metadati, utilizza il projects.locations.metadataFeeds.get metodo.

Esegui questo comando:

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

Sostituisci quanto segue:

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

Elenca i feed di modifiche dei metadati

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

REST

Per elencare i feed di modifiche dei metadati, utilizza il projects.locations.metadataFeeds.list metodo.

Esegui questo comando:

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

Aggiorna un feed di modifiche dei metadati

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

REST

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

Esegui il comando seguente per aggiornare il feed di modifiche dei 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 di modifiche dei metadati che vuoi aggiornare, ad esempio example-feed

Elimina un feed di modifiche dei metadati

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

L'eliminazione di un feed di modifiche dei metadati impedisce al feed di pubblicare nuove modifiche dei metadati nell'argomento Pub/Sub. Tuttavia, non elimina l'argomento o la sottoscrizione associata al feed. Se non sono più necessari, devi eliminarli manualmente.

Prima di eliminare il feed o la sottoscrizione, assicurati che le applicazioni dei sottoscrittori abbiano elaborato tutti i messaggi in sospeso nella sottoscrizione Pub/Sub.

REST

Per eliminare un feed di modifiche dei metadati, utilizza il projects.locations.metadataFeeds.delete metodo.

Esegui questo comando:

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

Sostituisci quanto segue:

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

Consuma i messaggi di notifica

Dopo aver configurato un feed di modifiche dei 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 per l'argomento.

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

  1. Crea una sottoscrizione:

    gcloud pubsub subscriptions create SUBSCRIPTION_ID --topic=TOPIC_ID

    Sostituisci quanto segue:

    • SUBSCRIPTION_ID: l'ID della sottoscrizione che vuoi creare
    • TOPIC_ID: l'ID dell'argomento Pub/Sub in cui vengono pubblicati i messaggi dei feed di modifiche dei 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 della sottoscrizione da cui vuoi eseguire il pull dei messaggi

Per saperne di più sull'elaborazione dei messaggi Pub/Sub, consulta Ricevere messaggi da una sottoscrizione pull. Per informazioni su il formato dei messaggi, consulta Payload dei dati.

Passaggi successivi