Cette page a été traduite par l'API Cloud Translation.

Notifications Pub/Sub

Assurez-vous de suivre le atelier de programmation de 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 votre Partner Sales Console de test pour cet atelier de programmation.
Se familiariser avec Pub/Sub concepts.

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.

Cela est particulièrement utile pour :

Reflétez les modifications apportées directement dans la Partner Sales Console dans vos propres systèmes (par exemple, un membre de votre équipe d'assistance annule un droit d'accès Google Workspace).
Détectez les événements critiques déclenchés par vos clients revendeurs. Pour Exemple:
- Un client Google Workspace acceptant les conditions d'utilisation.
- Client Google Workspace validant son domaine
- Un client Google Workspace ajoute des utilisateurs avec un droit d'accès modulable.
- Un client Google Workspace migre.

La configuration de Pub/Sub comprend les trois étapes suivantes:

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

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

Notifications push pour Channel Services

Format des notifications

Vous trouverez ci-dessous un exemple de notification Pub/Sub. Les données du message sont transmis sous forme de 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"
}

Il s'agit des 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: Activez l'API Pub/Sub et préparez votre compte de service

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

Adresse e-mail d'un compte de service de votre projet. Cette adresse se présente comme suit : service-account@project.iam.gserviceaccount.com.
Un accès à un compte super-administrateur de domaine de revendeur (de préférence, test Partner Sales Console).
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, puis activer l'API Pub/Sub.
Attribuez à votre compte de service le rôle IAM Pub/Sub sur le projet. Accorder le rôle roles/pubsub.editor (nom de rôle = "Éditeur Pub/Sub") suffit pour cet atelier de programmation, mais vous pouvez utiliser des droits plus précis votre intégration de production. Vous trouverez tous les détails des rôles IAM sur la Page Contrôle des accès Pub/Sub.
Si vous choisissez d'appliquer un rôle personnalisé, vous devez accorder à ce rôle l'autorisation pubsub.subscriptions.create pour créer des abonnements.

L'application de ces rôles et autorisations à votre compte peut prendre un certain temps.

É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 une adresse e-mail de compte de service comme paramètre. Seuls les comptes de service autorisés par cette méthode peuvent s'abonner à votre nouveau thème.

Accédez à la documentation accounts.register, puis cliquez sur Essayer.
Dans le champ account, saisissez accounts/ACCOUNT_ID en remplaçant ACCOUNT_ID à l'aide de 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 revendeur. domaine.

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 utilise 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 périodiquement des appels HTTP pour obtenir les modifications mises en file d'attente.

Dans cet atelier de programmation, nous utiliserons Push et enverrons tous les événements à une fonction Cloud Run qui les consignera dans Cloud Logging.

Envoyer des notifications Channel Services à une fonction Cloud Run

Étape 3a : Créer une fonction Cloud Run

Au cours de cette étape, vous allez créer une fonction Cloud Run qui consigne les messages reçus.

Accédez au la section Fonctions Cloud Run de console Google Cloud. Vous devrez peut-être activer l'API des fonctions Cloud Run.
Cliquez sur Créer une fonction.
Sur l'écran Configuration:
1. Modifiez le nom de la fonction. Vous pouvez également choisir une autre région.
2. Dans le déclencheur HTTP, remplacez Authentification par Allow unauthenticated invocations (Autoriser les appels non authentifiés), puis cliquez sur Save (Enregistrer).
3. Notez bien l'URL du déclencheur. Vous en aurez besoin à l'étape suivante.
4. Cliquez sur Suivant.

Sur 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 Run.

Étape 3b: Créez l'abonnement

Uniquement les comptes de service enregistrés pour le sujet Channel Services (voir é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. Veillez à ne pas usurper l'identité de votre domaine Super-administrateur, qui est requis lors de l'appel de 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 du déclencheur de la fonction Cloud Run 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

Pour vérifier que l'abonnement est configuré, accédez à la section Abonnements Pub/Sub.

Générer des données

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

La méthode la plus simple consiste à créer un client dans votre Partner Sales Console de provisionner un produit. Si vous avez terminé l'atelier de programmation de provisionnement Workspace de bout en bout, vous pouvez créer un client avec un compte Google Workspace en exécutant l'exemple de code.

Accédez à votre fonction dans la console Google Cloud, puis ouvrez l'onglet Journaux. Voici un exemple de ce que vous devriez voir.

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

Effectuer un nettoyage

Supprimer la fonction Cloud Run
Supprimer l'abonnement

Le sujet sera nettoyé automatiquement s'il ne contient abonnés restants.

Étapes suivantes

Cet atelier de programmation vous a expliqué 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

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

Document de référence sur les API

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

Utilisez accounts.register pour créer le sujet.
Utilisez subscriptions.create de l'API Pub/Sub pour créer l'abonnement Pub/Sub.
Consultez accounts.listSubscribers et accounts.unregister pour découvrir d'autres points de terminaison 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 de transfert :

É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 avant expiration de Pub/Sub par défaut pour le push soit de 10 secondes Vous pouvez augmenter ce nombre à l'aide du paramètre ackDeadline), il est recommandé d'utiliser une architecture de messages et de le point de terminaison répond le plus rapidement possible.
Si votre point de terminaison est en panne ou renvoie des erreurs 5xx, Pub/Sub réessayera. Pour en savoir plus sur la réception de messages via un envoi, consultez la documentation Pub/Sub.

Si vous préférez utiliser le mode pull, vous trouverez des informations sur la manière de recevoir des messages via le mode pull dans la documentation Pub/Sub.

Filtrage des événements

Étant donné que les notifications des services de canaux incluent attributes, vous pouvez créer des abonnements 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 apportées aux sièges Google Workspace.