Notifications Pub/Sub

Assurez-vous d'avoir suivi l'atelier de programmation sur la configuration de l'API pour configurer un projet Google Cloud et créer un compte de service pour appeler l'API Cloud Channel.
Nous vous recommandons d'utiliser la console Ventes partenaires de test pour cet atelier de programmation.
Familiarisez-vous avec les concepts de Pub/Sub.

Présentation

L'API Cloud Channel utilise Pub/Sub pour envoyer des notifications sur divers événements liés aux clients et aux droits d'accès.

Ceci est particulièrement utile pour:

Refléter les modifications apportées directement dans la Partner Sales Console dans vos propres systèmes (par exemple, une personne de votre équipe d'assistance qui résilie un droit d'accès à Google Workspace)
Détecter les événements critiques déclenchés par vos clients indirects Exemple :
- Client Google Workspace acceptant les conditions d'utilisation.
- Un client Google Workspace valide son domaine.
- Un client Google Workspace ajoute des utilisateurs avec un droit d'accès flexible.
- Un client Google Workspace quitte l'entreprise.

La configuration de Pub/Sub s'effectue en trois étapes:

Activez l'API Pub/Sub et préparez votre compte de service.
Créer un sujet Pub/Sub Ce sujet appartient à Channel Services. Vous devez spécifier un compte de service autorisé à créer un abonnement.
Créez un abonnement Pub/Sub. Cet abonnement peut être push à l'aide de webhooks (méthode préférée) ou pull.

Pour un abonnement push, vous hébergez un webhook qui reçoit les événements émis par Channel Services:

Notifications push pour Channel Services

Format des notifications

Voici un exemple de notification Pub/Sub. Les données du message sont transmises sous la forme d'une chaîne JSON encodée en base64.

{
  "message": {
    "attributes": {
      "event_type": "LICENSE_ASSIGNMENT_CHANGED",
      "subscriber_event_type": "ENTITLEMENT_EVENT"
    },
    "data": "eyJlbnRpdGxlbWVudF9ldmVudCI6eyJldmVudF90eXBlIjoiTElDRU5TRV9BU1NJR05NRU5UX0NIQU5HRUQiLCJlbnRpdGxlbWVudCI6ImFjY291bnRzL0MwMTIzNDU2L2N1c3RvbWVycy9TMDEyMzQ1NjcvZW50aXRsZW1lbnRzL1NhYmNkZWYxMjM0NSJ9fQ==",
    "message_id": 1918124788439510,
    "publish_time": "2021-01-14T01:23:45.678Z"
  },
  "subscription": "projects/project/subscriptions/channel-pubsub-test"
}

Voici les mêmes données de message, décodées:

{
  "entitlement_event": {
    "event_type": "LICENSE_ASSIGNMENT_CHANGED",
    "entitlement": "accounts/C0123456/customers/S01234567/entitlements/Sabcdef12345"}
  }
}

Étape 1: Activer l'API Pub/Sub et préparer votre compte de service

Pour exécuter cet atelier de programmation, vous avez besoin des éléments suivants:

Adresse e-mail d'un compte de service sur votre projet. Cette adresse doit ressembler à l'adresse suivante: service-account@project.iam.gserviceaccount.com.
Un accès à un compte super-administrateur de domaine de revendeur (de préférence votre console Ventes partenaires test)
Votre ID de compte. Vous le trouverez dans les paramètres de la Partner Sales Console.

Pour préparer votre compte de service:

Accédez à la section Bibliothèque d'API de la console Google Cloud et activez l'API Pub/Sub.
Attribuez à votre compte de service le rôle IAM Pub/Sub sur le projet. Le fait d'accorder le rôle roles/pubsub.editor (nom de rôle = "Éditeur Pub/Sub") est suffisant pour cet atelier de programmation, mais vous pouvez utiliser des droits plus précis dans votre intégration de production. Vous trouverez tous les détails du rôle IAM sur la page Contrôle des accès Pub/Sub.
Si vous choisissez d'appliquer un rôle personnalisé à la place, vous devez accorder à ce rôle l'autorisation pubsub.subscriptions.create pour créer des abonnements.

Il peut s'écouler un certain temps après que vous avez attribué ces rôles et autorisations à votre compte.

Étape 2: Créez le thème pour votre compte

Pour créer le sujet Pub/Sub, vous devez utiliser la méthode accounts.register. Cette méthode utilise l'adresse e-mail d'un compte de service comme paramètre. Seuls les comptes de service autorisés via cette méthode peuvent s'abonner à votre nouveau sujet.

Accédez à la documentation accounts.register et cliquez sur Essayer.
Dans le champ account, saisissez accounts/ACCOUNT_ID en remplaçant ACCOUNT_ID par votre ID de compte.
Cliquez sur Ajouter des paramètres du corps de la requête, sélectionnez serviceAccount, puis saisissez l'adresse e-mail de votre compte de service.
Cliquez sur Exécuter en vous assurant de vous connecter en tant que super-administrateur de votre domaine de revendeur.

Vous devriez obtenir une réponse 200 semblable à celle-ci:

{
  "topic": "projects/cloud-channel-pubsub/topics/C0123456-notify"
}

Il s'agit du sujet Pub/Sub dans lequel les événements seront publiés.

Étape 3: S'abonner au sujet

Après avoir créé le sujet Pub/Sub, vous devez configurer la manière dont votre application consomme les événements de modification. Deux possibilités s'offrent à vous :

Abonnement push: vous fournissez un rappel HTTP POST. Pub/Sub l'utilisera pour informer votre application des nouveaux événements.
Abonnement pull: votre application effectue régulièrement des appels HTTP pour obtenir les modifications mises en file d'attente.

Dans cet atelier de programmation, nous utiliserons la méthode push pour envoyer tous les événements à une fonction Cloud qui se connectera à Cloud Logging.

Transmettre des notifications Channel Services à une fonction Cloud

Étape 3a: Créer une fonction Cloud

Au cours de cette étape, nous allons créer une fonction Cloud qui enregistrera les messages reçus.

Accédez à la section Cloud Functions de la console Google Cloud. Vous devrez peut-être activer l'API Cloud Functions.
Cliquez sur Créer une fonction.
Sur l'écran Configuration :
1. Modifiez le nom de la fonction. Si vous le souhaitez, sélectionnez une autre région.
2. Dans le déclencheur HTTP, remplacez Authentification par Autoriser les appels non authentifiés, puis cliquez sur Enregistrer.
3. Notez bien l'URL du déclencheur. Vous en aurez besoin à l'étape suivante.
4. Cliquez sur Suivant.

Dans l'écran Code:

Choisissez un environnement d'exécution Node.js
Définissez le point d'entrée sur log.
Dans le fichier index.js, remplacez l'exemple de code par:

exports.log = (req, res) => {
  if (req.body && req.body.message) {
    console.log(req.body);
    const message = req.body.message;
    // data is base64-encoded JSON
    const data = new Buffer.from(message.data, 'base64').toString();
    console.log(data);
  }
  res.status(200).send('OK');
};

Vous pouvez passer à l'étape suivante pendant le déploiement de la fonction Cloud.

Étape 3b: Créez l'abonnement

Seuls les comptes de service enregistrés pour le sujet Channel Services (voir l'étape 2) peuvent créer un abonnement.

Pour ce faire, utilisez du code en appelant l'API Pub/Sub avec les identifiants de votre compte de service. Assurez-vous de ne pas usurper l'identité du super-administrateur de votre domaine revendeur, qui est requis lorsque vous appelez l'API Cloud Channel.

Pour les besoins de cet atelier de programmation, vous utiliserez l'outil gcloud CLI sur Cloud Shell.

Cliquez sur Activer Cloud Shell en haut de la console Google Cloud.
Une fois que le shell est prêt, exécutez la commande suivante. Remplacez les valeurs de SERVICE_ACCOUNT par l'adresse e-mail de votre compte de service, TOPIC par le sujet créé à l'étape 2 et PUSH_ENDPOINT par l'URL de déclencheur de la fonction Cloud créée à l'étape 3a:
```
SERVICE_ACCOUNT=service-account@project.iam.gserviceaccount.com
TOPIC=projects/cloud-channel-pubsub/topics/C0123456-notify
PUSH_ENDPOINT=https://us-central1-project.cloudfunctions.net/pubsub
```

Activez le compte de service dans le shell:

gcloud iam service-accounts keys create sa-keys.json \
    --iam-account=$SERVICE_ACCOUNT
gcloud auth activate-service-account --key-file=sa-keys.json

Créez l'abonnement:

gcloud pubsub subscriptions create channel-pubsub-test \
    --topic=$TOPIC \
    --push-endpoint=$PUSH_ENDPOINT

Vous pouvez vérifier que l'abonnement est configuré en accédant à la section Abonnements Pub/Sub.

Générer des données

Une fois les étapes précédentes effectuées, vous êtes prêt à recevoir des données.

Le moyen le plus simple consiste à créer un client dans la Partner Sales Console et à provisionner un produit. Si vous avez terminé l'atelier de programmation sur le provisionnement des espaces de travail de bout en bout, vous pouvez créer un client avec Google Workspace en exécutant l'exemple de code.

Accédez à votre fonction dans la console Google Cloud et ouvrez l'onglet Journaux. Voici un exemple de ce qui devrait s'afficher.

Exemples de journaux pour les événements Pub/Sub

Effectuer un nettoyage

Supprimer la fonction Cloud
Supprimer l'abonnement

Le sujet sera nettoyé automatiquement s'il ne reste plus d'abonnés.

Étapes suivantes

Dans cet atelier de programmation, vous avez découvert comment Channel Services exploite Pub/Sub pour vous permettre de créer votre intégration de manière réactive et à grande échelle.

Référence d'événement

Consultez la documentation de référence sur RPC pour obtenir la liste des événements générés par Channel Services.

Documentation de référence de l'API

Cet atelier de programmation utilise la console Google Cloud, mais vous pouvez effectuer ces étapes par programmation. Pour ce faire :

Utilisez accounts.register pour créer le sujet.
Utilisez la méthode subscriptions.create de l'API Pub/Sub pour créer l'abonnement Pub/Sub.
Consultez accounts.listSubscribers et accounts.unregister pour connaître les points de terminaison supplémentaires que vous pouvez utiliser dans votre intégration.

Garanties et bonnes pratiques Pub/Sub

Le délai entre un événement et sa notification n'est pas garanti. De même, l'ordre des notifications n'est pas garanti. Enfin, les messages peuvent être distribués plusieurs fois.

Bonnes pratiques concernant les points de terminaison push:

Étant donné que les messages peuvent être retardés, envoyés dans le désordre ou envoyés plusieurs fois, votre point de terminaison doit être idempotent et utiliser customers.get et entitlements.get.
Bien que le délai d'expiration Pub/Sub par défaut pour le transfert soit de 10 secondes (il peut être augmenté via le paramètre ackDeadline de l'abonnement Pub/Sub), il est recommandé d'utiliser une architecture basée sur les messages et de faire en sorte que le point de terminaison réponde aussi rapidement que possible.
Si votre point de terminaison est indisponible ou renvoie des erreurs 5xx, Pub/Sub réessaie. Pour en savoir plus sur la réception de messages en mode push, consultez la documentation Pub/Sub.

Si vous préférez utiliser le mode pull, vous trouverez des informations sur la réception de messages en mode pull dans la documentation Pub/Sub.

Filtrage des événements

Étant donné que les notifications de Channel Services incluent attributes, vous pouvez créer des abonnements plus précis en créant des abonnements Pub/Sub spécifiques avec le filtrage Pub/Sub.

Par exemple, le filtrage avec attributes.event_type = "LICENSE_ASSIGNMENT_CHANGED" vous permet de suivre toutes les modifications de licences Google Workspace.