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.
Familiarisez-vous avec les concepts 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.

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. Exemple :
- 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 qui transfère son compte

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. Vous devez spécifier 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.

Pour un abonnement push, vous hébergez un webhook qui reçoit les événements émis par les services de chaîne:

Notifications push pour Channel Services

Format des notifications

Vous trouverez ci-dessous un exemple de notification Pub/Sub. Les données du message sont transmises 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.
Accès à un compte super-administrateur de domaine de revendeur (de préférence votre console Ventes partenaires de 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 au compte de service le rôle IAM Pub/Sub sur le projet. Accorder roles/pubsub.editor (nom du 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 en production. Vous trouverez des informations complètes sur les 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.

Un délai peut s'écouler après l'application de ces rôles et autorisations à votre compte.

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

Pour créer le sujet Pub/Sub, vous devez utiliser la méthode accounts.register. Cette méthode prend 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 par votre ID de compte.
Cliquez sur Add request body parameters (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 Execute (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 sur 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 façon 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 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.

Transmettre 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 à la section Fonctions Cloud Run de la console Google Cloud. Vous devrez peut-être activer l'API Cloud Run Functions.
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 Authentication (Authentification) par Allow unauthenticated invocations (Autoriser les appels non authentifiés), puis cliquez sur Save (Enregistrer).
3. Notez l'URL du déclencheur. Vous en aurez besoin à l'étape suivante.
4. Cliquez sur Suivant.

Sur l'écran Code:

Choisir un environnement d'exécution Node.js
Remplacez le Point d'entrée par 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éer l'abonnement

Seuls 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. Assurez-vous de ne pas usurper l'identité du super-administrateur de votre domaine de revendeur, ce qui est obligatoire lorsque vous appelez l'API Cloud Channel.

Pour cet atelier de programmation, vous allez utiliser l'outil gcloud CLI sur Cloud Shell.

Cliquez sur Activer Cloud Shell en haut de la console Google Cloud.
Une fois l'interface système prête, 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 que vous avez terminé les étapes précédentes, vous pouvez 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é le 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 automatiquement nettoyé lorsqu'il n'aura plus d'abonnés.

É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 de l'événement

Pour obtenir la liste des événements générés par Channel Services, consultez la documentation de référence sur les RPC.

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 d'expiration par défaut de Pub/Sub pour le push 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 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 pull, vous trouverez des informations sur la manière de recevoir des messages via le 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 de sièges Google Workspace.