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:
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
, saisissezaccounts/ACCOUNT_ID
, en remplaçantACCOUNT_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.
É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 :
- Modifiez le nom de la fonction. Vous pouvez également choisir une autre région.
- Dans le déclencheur HTTP, remplacez Authentication (Authentification) par Allow unauthenticated invocations (Autoriser les appels non authentifiés), puis cliquez sur Save (Enregistrer).
- Notez l'URL du déclencheur. Vous en aurez besoin à l'étape suivante.
- 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 etPUSH_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.
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
etaccounts.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
etentitlements.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.