Recevoir des notifications avec des flux de modification des métadonnées

Ce document explique comment configurer les flux de modification des métadonnées Dataplex Universal Catalog pour recevoir des notifications via Pub/Sub lorsque des métadonnées sont créées, mises à jour ou supprimées dans Dataplex Universal Catalog.

Pour en savoir plus sur les flux de modifications des métadonnées, consultez Présentation des flux de modifications des métadonnées.

Avant de commencer

Familiarisez-vous avec Pub/Sub et l'API Dataplex Universal Catalog.

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

  2. Créez un sujet Pub/Sub pour recevoir les notifications. Pour en savoir plus, consultez Créer un sujet.

  3. Installer gcloud. Assurez-vous que l'alias court de gcloud est défini.

  4. Définissez un alias de gcurl. Cela crée un raccourci qui inclut votre jeton d'authentification et définit le type de contenu JSON pour les requêtes API :

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

  5. Définissez la variable DATAPLEX_API :

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

    Remplacez les éléments suivants :

    • PROJECT_ID : ID du projet dans lequel l'API Dataplex est activée
    • LOCATION : emplacement où le job s'exécute (par exemple, us-central1, europe-west3 ou asia-south1)

Rôles et autorisations nécessaires

Pour configurer les flux de modifications des métadonnées, assurez-vous que vous et le compte de service Dataplex Universal Catalog disposez des rôles et autorisations IAM requis.

Rôles et autorisations des utilisateurs

Pour obtenir les autorisations nécessaires pour exporter des métadonnées et accéder aux messages des flux de modifications de métadonnées, demandez à votre administrateur de vous accorder les rôles IAM suivants sur le projet ou l'organisation :

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ces rôles prédéfinis contiennent les autorisations requises pour exporter les métadonnées et accéder aux messages des flux de modifications des métadonnées. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Les autorisations suivantes sont requises pour exporter des métadonnées et accéder aux messages des flux de modifications de métadonnées :

  • Exporter les métadonnées :
    • dataplex.metadataFeeds.create sur le projet
    • dataplex.entryGroups.export sur la ressource définissant le champ d'application du flux (organisation, projet ou groupe d'entrées)
    • resourcemanager.projects.get sur le projet
    • resourcemanager.projects.list sur le projet
  • Accéder aux messages des flux de modification des métadonnées :
    • pubsub.subscriptions.consume sur l'abonnement
    • pubsub.topics.attachSubscription sur le sujet

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

Rôles et autorisations du compte de service Dataplex Universal Catalog

Pour vous assurer que le compte de service Dataplex Universal Catalog dispose des autorisations nécessaires pour publier des messages de flux de modifications de métadonnées, demandez à votre administrateur d'accorder au compte de service Dataplex Universal Catalog le rôle IAM Éditeur Pub/Sub (roles/pubsub.publisher) sur le sujet Pub/Sub.

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ce rôle prédéfini contient l'autorisation pubsub.topics.publish, qui est requise pour publier des messages de flux de modification des métadonnées.

Votre administrateur peut également attribuer au compte de service Dataplex Universal Catalog cette autorisation avec des rôles personnalisés ou d'autres rôles prédéfinis.

Accorder des autorisations au compte de service Dataplex Universal Catalog

L'agent de service Dataplex Universal Catalog est créé lorsque vous activez l'API Dataplex. Vous pouvez identifier l'agent de service par son adresse e-mail :

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

Ici, PROJECT_NUMBER correspond au numéro du projet dans lequel vous avez activé l'API Dataplex.

Le compte de service Dataplex Universal Catalog doit pouvoir publier des messages dans votre sujet Pub/Sub. Pour accorder cette autorisation, attribuez au compte de service le rôle Éditeur Pub/Sub (roles/pubsub.publisher) sur le sujet Pub/Sub :

gcloud

Exécutez la commande 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"

Remplacez les éléments suivants :

  • TOPIC_ID correspond à l'ID de votre sujet Pub/Sub dans lequel les messages du flux de modifications des métadonnées sont publiés.
  • PROJECT_NUMBER : numéro du projet Dataplex Universal Catalog dans lequel se trouve le compte de service.

Console

  1. Dans la console Google Cloud , accédez à la page Sujets de Pub/Sub.

    Accéder aux sujets

  2. Sélectionnez le thème que vous utilisez pour les notifications de flux de métadonnées, puis cliquez sur Afficher le panneau d'informations si nécessaire.

  3. Dans l'onglet Autorisations, cliquez sur Ajouter un compte principal.

  4. Dans le champ Nouveaux comptes principaux, saisissez le compte de service Dataplex Universal Catalog : service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com.

  5. Dans le champ Attribuer des rôles, sélectionnez Diffuseur Pub/Sub.

  6. Cliquez sur Enregistrer.

Créer un flux de modifications des métadonnées

Pour contrôler les modifications qui génèrent des notifications, vous pouvez configurer un flux de modifications de métadonnées afin de surveiller des ressources spécifiques. Pour ce faire, spécifiez un champ d'application, comme l'ensemble de votre organisation, des projets spécifiques ou des groupes d'entrées spécifiques. Alors que le champ d'application vous permet de définir quelles ressources surveiller, vous pouvez utiliser des filtres pour affiner quand Dataplex Universal Catalog envoie des notifications.

Pour en savoir plus, consultez Flux de modifications des métadonnées.

REST

Pour créer un flux de modifications de métadonnées, utilisez la méthode projects.locations.metadataFeeds.create.

Champ d'application de l'organisation

Exécutez la commande suivante pour créer un flux de modifications des métadonnées qui surveille l'ensemble de l'organisation :

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"

Remplacez les éléments suivants :

  • PROJECT_ID_PUBSUB : ID du projet dans lequel se trouve le sujet Pub/Sub (par exemple, example-project)
  • TOPIC_ID : ID du sujet Pub/Sub dans lequel les messages du flux de modifications des métadonnées sont publiés (par exemple, example-topic)
  • FEED_ID : ID du flux de modifications des métadonnées que vous souhaitez créer (par exemple, example-feed)

Champ d'application du projet

Exécutez la commande suivante pour créer un flux de modifications des métadonnées qui surveille des projets spécifiques :

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"

Remplacez les éléments suivants :

  • PROJECT_ID_PUBSUB : ID du projet dans lequel se trouve le sujet Pub/Sub (par exemple, example-project)
  • TOPIC_ID : ID du sujet Pub/Sub dans lequel les messages du flux de modifications des métadonnées sont publiés (par exemple, example-topic)
  • FEED_ID : ID du flux de modifications des métadonnées que vous souhaitez créer (par exemple, example-feed)

Champ d'application du groupe d'entrées

Exécutez la commande suivante pour créer un flux de modifications de métadonnées qui surveille des groupes d'entrées spécifiques :

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"

Remplacez les éléments suivants :

  • PROJECT_ID_PUBSUB : ID du projet dans lequel se trouve le sujet Pub/Sub (par exemple, example-project)
  • LOCATION : emplacement où vous souhaitez créer le flux (par exemple, us-central1)
  • ENTRY_GROUP_ID : ID du groupe d'entrées à surveiller (par exemple, example-entry-group)
  • TOPIC_ID : ID du sujet Pub/Sub dans lequel les messages du flux de modifications des métadonnées sont publiés (par exemple, example-topic)
  • FEED_ID : ID du flux de modifications des métadonnées que vous souhaitez créer (par exemple, example-feed)

Avec des filtres

Exécutez la commande suivante pour créer un flux de modifications de métadonnées avec des filtres (filtrage par type d'entrée) :

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"

Remplacez les éléments suivants :

  • PROJECT_ID_PUBSUB : ID du projet dans lequel se trouve le sujet Pub/Sub (par exemple, example-project)
  • TOPIC_ID : ID du sujet Pub/Sub dans lequel les messages du flux de modifications des métadonnées sont publiés (par exemple, example-topic)
  • FEED_ID : ID du flux de modifications des métadonnées que vous souhaitez créer (par exemple, example-feed)

Réponse :

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

Afficher les flux de modifications des métadonnées

Vous pouvez afficher les détails d'un flux de modifications des métadonnées.

REST

Pour afficher un flux de modifications de métadonnées, utilisez la méthode projects.locations.metadataFeeds.get.

Exécutez la commande suivante :

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

Remplacez les éléments suivants :

  • FEED_ID : ID du flux de modifications des métadonnées que vous souhaitez afficher (par exemple, example-feed)

Lister les flux de modifications de métadonnées

Vous pouvez lister les flux de modifications des métadonnées dans un projet et un emplacement.

REST

Pour lister les flux de modifications des métadonnées, utilisez la méthode projects.locations.metadataFeeds.list.

Exécutez la commande suivante :

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

Mettre à jour un flux de modifications des métadonnées

Vous pouvez modifier le champ d'application ou les filtres d'un flux de modifications de métadonnées existant.

REST

Pour mettre à jour un flux de modifications des métadonnées, utilisez la méthode projects.locations.metadataFeeds.patch.

Exécutez la commande suivante pour mettre à jour le flux de modifications des métadonnées afin de supprimer les filtres de type d'entrée :

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

Remplacez les éléments suivants :

  • FEED_ID : ID du flux de modifications des métadonnées que vous souhaitez mettre à jour, par exemple example-feed

Supprimer un flux de modifications des métadonnées

Vous pouvez supprimer un flux de modifications de métadonnées si vous n'avez plus besoin de recevoir de notifications.

La suppression d'un flux de modifications de métadonnées empêche la publication de nouvelles modifications de métadonnées dans votre sujet Pub/Sub. Toutefois, il ne supprime pas le thème ni l'abonnement associés au flux. Vous devez les supprimer manuellement si vous n'en avez plus besoin.

Avant de supprimer le flux ou l'abonnement, assurez-vous que vos applications abonnées ont traité tous les messages en attente dans l'abonnement Pub/Sub.

REST

Pour supprimer un flux de modifications de métadonnées, utilisez la méthode projects.locations.metadataFeeds.delete.

Exécutez la commande suivante :

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

Remplacez les éléments suivants :

  • FEED_ID : ID du flux de modifications des métadonnées que vous souhaitez supprimer, par exemple example-feed

Consommer les messages de notification

Une fois que vous avez configuré un flux de modification des métadonnées, Dataplex Universal Catalog publie des messages dans le sujet Pub/Sub spécifié lorsque des modifications de métadonnées se produisent. Pour consommer ces messages, créez un abonnement Pub/Sub au sujet.

Par exemple, vous pouvez créer un abonnement par extraction et utiliser la Google Cloud CLI pour afficher les messages :

  1. Créez un abonnement :

    gcloud pubsub subscriptions create SUBSCRIPTION_ID --topic=TOPIC_ID

    Remplacez les éléments suivants :

    • SUBSCRIPTION_ID : ID de l'abonnement que vous souhaitez créer
    • TOPIC_ID : ID du sujet Pub/Sub dans lequel les messages du flux de modifications des métadonnées sont publiés.

  2. Extrayez les messages de l'abonnement :

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

    Remplacez les éléments suivants :

    • SUBSCRIPTION_ID : ID de l'abonnement à partir duquel vous souhaitez extraire les messages.

Pour en savoir plus sur le traitement des messages Pub/Sub, consultez Recevoir des messages à partir d'un abonnement pull. Pour en savoir plus sur le format des messages, consultez Charge utile des données.

Étapes suivantes