Créer un abonnement Google Workspace

Cette page explique comment utiliser l'API Google Workspace Events pour créer un abonnement à une ressource Google Workspace. Un abonnement Google Workspace permet à votre application de recevoir des informations sur les événements Google Workspace, qui représentent les modifications apportées à une ressource Google Workspace. Pour en savoir plus sur les ressources et les types d'événements compatibles avec l'API Google Workspace Events, consultez la présentation de l'API Google Workspace Events.

Cette page comprend les étapes suivantes pour créer un abonnement Google Workspace :

  1. configurer votre environnement ;
  2. Créer un sujet Google Cloud Pub/Sub et s'y abonner Utilisez ce document comme point de terminaison pour recevoir des événements Google Workspace.
  3. Appelez la méthode create de l'API Google Workspace Events sur la ressource Subscription.
  4. Testez votre abonnement Google Workspace pour vérifier que votre sujet Pub/Sub reçoit les événements auxquels vous vous êtes abonné.
  5. Vous pouvez éventuellement configurer la manière de transmettre les événements à un point de terminaison pour votre application, afin qu'elle puisse traiter l'événement et, si nécessaire, prendre des mesures.

Prérequis

Apps Script

  • Pour utiliser les commandes Google Cloud CLI de ce guide, procédez comme suit :
    1. Installez Google Cloud CLI.
    2. Pour initialiser la CLI gcloud, exécutez le code suivant :
      3.   gcloud init
  • Un projet Apps Script :
    • Utilisez votre projet Google Cloud au lieu de celui créé automatiquement par défaut par Apps Script.
    • Pour tous les champs d'application que vous avez ajoutés pour configurer l'écran de consentement OAuth, vous devez également les ajouter au fichier appsscript.json de votre projet Apps Script. Par exemple, si vous avez spécifié le champ d'application chat.messages, ajoutez ce qui suit : 
      • "oauthScopes": [
  "https://www.googleapis.com/auth/chat.messages"
]
    • Activez le service avancé Google Workspace Events.

Python

  • Python 3.6 ou version ultérieure
  • L'outil de gestion de paquets pip
  • Les dernières bibliothèques clientes Google pour Python. Pour les installer ou les mettre à jour, exécutez la commande suivante dans votre interface de ligne de commande : 
      pip3 install --upgrade google-api-python-client google-auth-oauthlib
  • Pour utiliser les commandes Google Cloud CLI de ce guide, procédez comme suit :
    1. Installez Google Cloud CLI.
    2. Pour initialiser la CLI gcloud, exécutez le code suivant :
      3.   gcloud init

Configurer votre environnement

La section suivante explique comment configurer votre environnement avant de créer un abonnement Google Workspace.

Activer l'API Google Workspace Events et l'API Google Cloud Pub/Sub

Avant d'utiliser les API Google, vous devez les activer dans un projet Google Cloud. Vous pouvez activer une ou plusieurs API dans un même projet Google Cloud.

Console Google Cloud

Dans la console Google Cloud, ouvrez le projet Google Cloud de votre application, puis activez l'API Google Workspace Events et l'API Pub/Sub :

Activer les API

gcloud

  1. Dans votre répertoire de travail, connectez-vous à votre compte Google :

    gcloud auth login

  2. Définissez votre projet sur le projet Cloud de votre application :

    gcloud config set project PROJECT_ID

    Remplacez PROJECT_ID par l'ID de projet du projet Cloud de votre application.

  3. Activez l'API Google Workspace Events et l'API Google Cloud Pub/Sub :

    gcloud services enable pubsub.googleapis.com workspaceevents.googleapis.com

Créer un ID client OAuth

Choisissez votre type d'application pour obtenir des instructions spécifiques sur la création d'un ID client OAuth :

Application Web

  1. Dans la console Google Cloud, accédez à Menu  > Google Auth Platform > Clients.

    Accéder à la page "Clients"

  2. Cliquez sur Créer un client.
  3. Cliquez sur Type d'application > Application Web.
  4. Dans le champ Nom, saisissez un nom pour les identifiants. Ce nom n'apparaît que dans la console Google Cloud.
  5. Ajoutez les URI autorisés associés à votre application :
    • Applications côté client (JavaScript) : sous Origines JavaScript autorisées, cliquez sur Ajouter un URI. Saisissez ensuite un URI à utiliser pour les requêtes du navigateur. Cela permet d'identifier les domaines à partir desquels votre application peut envoyer des requêtes API au serveur OAuth 2.0.
    • Applications côté serveur (Java, Python, etc.) : sous URI de redirection autorisés, cliquez sur Ajouter un URI. Saisissez ensuite un URI de point de terminaison vers lequel le serveur OAuth 2.0 peut envoyer des réponses.
  6. Facultatif : Si votre application est un agent IA qui effectue des actions pour le compte des utilisateurs, sélectionnez Utiliser ce client pour un agent basé sur l'IA. Si votre application est compatible à la fois avec les workflows d'agent IA et les fonctionnalités d'utilisateur standard, créez des clients OAuth distincts pour chacun. Vous ne pouvez pas modifier ce paramètre après avoir créé le client.
  7. Cliquez sur Créer.

    L'identifiant que vous venez de créer s'affiche sous ID client OAuth 2.0.

    Notez que les codes secrets du client ne sont pas utilisés pour les applications Web.

Android

  1. Dans la console Google Cloud, accédez à Menu  > Google Auth Platform > Clients.

    Accéder à la page "Clients"

  2. Cliquez sur Créer un client.
  3. Cliquez sur Type d'application > Android.
  4. Dans le champ Nom, saisissez un nom pour les identifiants. Ce nom n'apparaît que dans la console Google Cloud.
  5. Dans le champ Nom du package, saisissez le nom du package de votre fichier AndroidManifest.xml.
  6. Dans le champ Empreinte du certificat SHA-1, saisissez l'empreinte du certificat SHA-1 générée.
  7. Facultatif : Si votre application est un agent IA qui effectue des actions pour le compte des utilisateurs, sélectionnez Utiliser ce client pour un agent basé sur l'IA. Si votre application est compatible à la fois avec les workflows d'agent IA et les fonctionnalités d'utilisateur standard, créez des clients OAuth distincts pour chacun. Vous ne pouvez pas modifier ce paramètre après avoir créé le client.
  8. Cliquez sur Créer.

    Les identifiants que vous venez de créer s'affichent sous "ID client OAuth 2.0".

iOS

  1. Dans la console Google Cloud, accédez à Menu  > Google Auth Platform > Clients.

    Accéder à la page "Clients"

  2. Cliquez sur Créer un client.
  3. Cliquez sur Type d'application > iOS.
  4. Dans le champ Nom, saisissez un nom pour les identifiants. Ce nom n'apparaît que dans la console Google Cloud.
  5. Dans le champ ID du bundle, saisissez l'identifiant du bundle tel qu'il apparaît dans le fichier Info.plist de l'application.
  6. Facultatif : si votre application est disponible sur l'App Store d'Apple, saisissez l'ID de l'App Store.
  7. Facultatif : Dans le champ ID d'équipe, saisissez la chaîne unique de 10 caractères générée par Apple et attribuée à votre équipe.
  8. Facultatif : Si votre application est un agent IA qui effectue des actions pour le compte des utilisateurs, sélectionnez Utiliser ce client pour un agent basé sur l'IA. Si votre application est compatible à la fois avec les workflows d'agent IA et les fonctionnalités d'utilisateur standard, créez des clients OAuth distincts pour chacun. Vous ne pouvez pas modifier ce paramètre après avoir créé le client.
  9. Cliquez sur Créer.

    Les identifiants que vous venez de créer s'affichent sous "ID client OAuth 2.0".

Application Chrome

  1. Dans la console Google Cloud, accédez à Menu  > Google Auth Platform > Clients.

    Accéder à la page "Clients"

  2. Cliquez sur Créer un client.
  3. Cliquez sur Type d'application > Extension Chrome.
  4. Dans le champ Nom, saisissez un nom pour l'identifiant. Ce nom n'apparaît que dans la console Google Cloud.
  5. Dans le champ ID de l'article, saisissez la chaîne d'ID unique de 32 caractères de votre application. Vous trouverez cette valeur d'ID dans l'URL de votre application sur le Chrome Web Store et dans le tableau de bord du développeur Chrome Web Store.
  6. Facultatif : Si votre application est un agent IA qui effectue des actions pour le compte des utilisateurs, sélectionnez Utiliser ce client pour un agent basé sur l'IA. Si votre application est compatible à la fois avec les workflows d'agent IA et les fonctionnalités d'utilisateur standard, créez des clients OAuth distincts pour chacun. Vous ne pouvez pas modifier ce paramètre après avoir créé le client.
  7. Cliquez sur Créer.

    Les identifiants que vous venez de créer s'affichent sous "ID client OAuth 2.0".

Application de bureau

  1. Dans la console Google Cloud, accédez à Menu  > Google Auth Platform > Clients.

    Accéder à la page "Clients"

  2. Cliquez sur Créer un client.
  3. Cliquez sur Type d'application > Application de bureau.
  4. Dans le champ Nom, saisissez un nom pour les identifiants. Ce nom n'apparaît que dans la console Google Cloud.
  5. Facultatif : Si votre application est un agent IA qui effectue des actions pour le compte des utilisateurs, sélectionnez Utiliser ce client pour un agent basé sur l'IA. Si votre application est compatible à la fois avec les workflows d'agent IA et les fonctionnalités d'utilisateur standard, créez des clients OAuth distincts pour chacun. Vous ne pouvez pas modifier ce paramètre après avoir créé le client.
  6. Cliquez sur Créer.

    Les identifiants que vous venez de créer s'affichent sous "ID client OAuth 2.0".

Téléviseurs et appareils à saisie limitée

  1. Dans la console Google Cloud, accédez à Menu  > Google Auth Platform > Clients.

    Accéder à la page "Clients"

  2. Cliquez sur Créer un client.
  3. Cliquez sur Type d'application > Téléviseurs et appareils à saisie limitée.
  4. Dans le champ Nom, saisissez un nom pour les identifiants. Ce nom n'apparaît que dans la console Google Cloud.
  5. Facultatif : Si votre application est un agent IA qui effectue des actions pour le compte des utilisateurs, sélectionnez Utiliser ce client pour un agent basé sur l'IA. Si votre application est compatible à la fois avec les workflows d'agent IA et les fonctionnalités d'utilisateur standard, créez des clients OAuth distincts pour chacun. Vous ne pouvez pas modifier ce paramètre après avoir créé le client.
  6. Cliquez sur Créer.

    Les identifiants que vous venez de créer s'affichent sous "ID client OAuth 2.0".

Plate-forme Windows universelle (UWP)

  1. Dans la console Google APIs, accédez à Menu  > > Clients.

    Accéder à la page "Clients"

  2. Cliquez sur Créer un client.
  3. Cliquez sur Type d'application > Plate-forme Windows universelle (UWP).
  4. Dans le champ "Nom", saisissez un nom pour les identifiants. Ce nom n'apparaît que dans la console Google APIs.
  5. Dans le champ "ID du Store", saisissez l'ID unique à 12 caractères de votre application sur le Microsoft Store. Vous trouverez cet ID dans l'URL de votre application sur le Microsoft Store et dans l'Centre des partenaires.
  6. Facultatif : Si votre application est un agent IA qui effectue des actions pour le compte des utilisateurs, sélectionnez Utiliser ce client pour un agent basé sur l'IA. Si votre application est compatible à la fois avec les workflows d'agent IA et les fonctionnalités d'utilisateur standard, créez des clients OAuth distincts pour chacun. Vous ne pouvez pas modifier ce paramètre après avoir créé le client.
  7. Cliquez sur Créer.

    Les identifiants que vous venez de créer s'affichent sous "ID client OAuth 2.0".

Télécharger le fichier JSON du code secret du client

Le fichier de code secret du client est une représentation JSON des identifiants d'ID client OAuth que votre application peut référencer lorsqu'elle fournit des identifiants.

  1. Dans la console Google APIs, accédez à Menu  > API et services > Identifiants.

    Accéder à "Identifiants"

  2. Sous ID client OAuth 2.0, cliquez sur l'ID client que vous avez créé.

  3. Cliquez sur Télécharger au format JSON.

  4. Enregistrez le fichier sous le nom credentials.json.

Créer un sujet Pub/Sub et s'y abonner

Dans cette section, vous allez créer un sujet Pub/Sub et un abonnement à ce sujet. Votre sujet Pub/Sub sert de point de terminaison de notification où votre abonnement Google Workspace reçoit des événements.

Pour en savoir plus sur la création et la gestion des sujets Pub/Sub, consultez la documentation Pub/Sub.

Pour créer un sujet Pub/Sub et vous y abonner :

Console Google APIs

  1. Dans la console Google APIs, accédez à la page Pub/Sub :

    Accéder à Google Cloud Pub/Sub

    Assurez-vous que le projet Cloud de votre application est sélectionné.

  2. Cliquez sur Créer un sujet et procédez comme suit :

    1. Saisissez un nom pour votre sujet, par exemple workspace-events-topic.
    2. Laissez l'option Ajouter un abonnement par défaut sélectionnée. Pub/Sub attribue à cet abonnement par défaut un nom semblable à celui de votre sujet, par exemple workspace-events-topic-sub.
    3. Facultatif : mettez à jour ou configurez des propriétés supplémentaires pour votre sujet.

  3. Cliquez sur Créer. Le nom complet de votre sujet est au format projects/PROJECT_ID/topics/TOPIC_ID. Vous utiliserez ce nom complet lors d'une prochaine étape.

  4. Accordez l'accès pour publier des messages Pub/Sub dans votre sujet :

    1. Sur la page de votre sujet, accédez au panneau latéral et ouvrez l'onglet Autorisations.
    2. Cliquez sur Ajouter un compte principal.
    3. Dans le champ Ajouter des comptes principaux, ajoutez le compte de service de l'application Google Workspace qui envoie des événements à votre abonnement :
      1. Pour les événements Chat, chat-api-push@system.gserviceaccount.com.
      2. Pour les événements Drive, drive-api-event-push@system.gserviceaccount.com.
      3. Pour les événements Meet, meet-api-event-push@system.gserviceaccount.com.
    4. Dans le menu Attribuer des rôles, sélectionnez Pub/Sub Publisher.
    5. Cliquez sur Enregistrer. La mise à jour des autorisations de votre sujet peut prendre quelques minutes.

gcloud

  1. Dans votre projet Cloud, créez un sujet en exécutant la commande suivante :

    gcloud pubsub topics create TOPIC_ID

    Remplacez TOPIC_ID par un identifiant unique pour votre sujet, par exemple workspace-events-topic.

    Le résultat affiche le nom complet du sujet, au format projects/PROJECT_ID/topics/TOPIC_ID. Notez le nom et assurez-vous que la valeur de PROJECT_ID est l'ID du projet cloud de votre application. Utilisez le nom du sujet à l'étape suivante et pour créer l'abonnement Google Workspace ultérieurement.

  2. Accordez l'accès pour publier des messages dans votre sujet :

    gcloud pubsub topics add-iam-policy-binding TOPIC_NAME --member='serviceAccount:GOOGLE_WORKSPACE_APPLICATION' --role='roles/pubsub.publisher'

    Remplacez les éléments suivants :

    • TOPIC_NAME : nom complet du sujet, qui est le résultat de l'étape précédente. Format : projects/PROJECT_ID/topics/TOPIC_ID.

    • GOOGLE_WORKSPACE_APPLICATION : application Google Workspace qui doit envoyer des événements à votre abonnement :

      • Pour recevoir des événements de Chat, utilisez l'un des comptes de service suivants :
      • Pour recevoir des événements de Drive, utilisez drive-api-event-push@system.gserviceaccount.com.
      • Pour recevoir des événements de Meet, utilisez meet-api-event-push@system.gserviceaccount.com.

    La mise à jour des autorisations de votre sujet peut prendre quelques minutes.

  3. Créez un abonnement Pub/Sub pour le sujet :

     gcloud pubsub subscriptions create SUBSCRIPTION_NAME --topic=TOPIC_NAME

    Remplacez les éléments suivants :

    • SUBSCRIPTION_NAME : nom de votre abonnement, par exemple workspace-events-subscription.
    • TOPIC_NAME : nom du sujet que vous avez créé à l'étape précédente.

S'abonner à une ressource Google Workspace

Dans cette section, vous allez vous abonner à la ressource Google Workspace dont vous souhaitez surveiller les événements.

Choisir et identifier la ressource cible

Dans un abonnement Google Workspace, la ressource cible est la ressource Google Workspace que vous surveillez pour détecter les événements. La ressource cible est représentée dans le champ targetResource de l'abonnement, au format du nom complet de la ressource. Par exemple, pour un abonnement qui surveille un espace Chat (spaces/AAAABBBBBBB), la valeur de targetResource est //chat.googleapis.com/spaces/AAAABBBBBBB.

Identifier une ressource cible pour Chat

Ressource cible Format Limites
Espace

//chat.googleapis.com/spaces/SPACE

où SPACE est l'ID dans le nom de ressource de la ressource space de l'API Chat. Vous pouvez obtenir l'ID à partir de l'URL de l'espace ou à l'aide de la méthode spaces.list().

 L'utilisateur Chat ou l'application Chat qui autorise l'abonnement doit être membre de l'espace via son compte Google Workspace ou son compte Google. Formats acceptés :
Tous les espaces d'un utilisateur

//chat.googleapis.com/spaces/-

 L'abonnement ne reçoit que les événements des espaces dont l'utilisateur est membre via son compte Google Workspace ou son compte Google. Seule l'authentification des utilisateurs est acceptée.
Utilisateur

//cloudidentity.googleapis.com/users/USER

où USER est l'ID dans le nom de ressource de la ressource user de l'API Chat. Pour en savoir plus, consultez Identifier et spécifier des utilisateurs Google Chat.

L'abonnement ne reçoit que les événements concernant l'utilisateur qui l'a autorisé. Un utilisateur ne peut pas autoriser un abonnement pour le compte d'autres utilisateurs. Seule l'authentification des utilisateurs est acceptée.
Client ( Preview développeur)

//admin.googleapis.com/customers/CUSTOMER

où CUSTOMER est l'ID client. Vous pouvez également utiliser l'alias my_customer pour le domaine personnalisé de l'application Chat.

L'abonnement reçoit des événements pour tous les espaces et utilisateurs gérés par le domaine du client. Seule l'authentification de l'application avec l'approbation de l'administrateur est acceptée.

Identifier une ressource cible pour Drive

Ressource cible Format Limites (le cas échéant)
Fichier //drive.googleapis.com/files/FILE

où FILE est l'ID du nom de ressource de la ressource files de l'API Drive. Vous pouvez obtenir l'ID à partir de l'URL du fichier ou à l'aide de la méthode files.list.

L'utilisateur qui autorise l'abonnement doit disposer d'une autorisation sur le fichier de l'abonnement correspondant à l'événement d'abonnement.
Drive partagé //drive.googleapis.com/drives/DRIVE

où DRIVE est l'ID du nom de ressource de la ressource drives de l'API Drive. Vous pouvez obtenir l'ID à partir de l'URL du lecteur ou à l'aide de la méthode drives.list.

L'abonnement ne reçoit que les événements concernant les éléments du Drive partagé dont l'utilisateur est membre via son compte Google Workspace ou son compte Google.

Identifier une ressource cible pour Meet

Ressource cible Format Limites (le cas échéant)
Espace de réunion //meet.googleapis.com/spaces/SPACE

où SPACE est l'ID dans le nom de ressource de la ressource spaces de l'API REST Meet. Pour en savoir plus, consultez Comment Meet identifie un espace de réunion.
Utilisateur //cloudidentity.googleapis.com/users/USER

où USER est l'ID du champ signedinUser.user de la ressource participants de l'API REST Meet. Pour en savoir plus, consultez Utiliser des participants.

L'abonnement reçoit des événements concernant tous les espaces de réunion dont l'utilisateur est propriétaire. En général, le propriétaire de l'espace de réunion est également l'organisateur de l'événement Google Agenda associé à l'espace de réunion.

Créer un abonnement Google Workspace

Pour créer un abonnement, utilisez la méthode subscriptions.create de l'API Google Workspace Events afin de créer une ressource Subscription. Spécifiez les champs suivants :

  • targetResource : un compte Google Workspace que vous avez identifié dans la section précédente, au format de son nom de ressource complet.
  • eventTypes : tableau d'un ou de plusieurs types d'événements que vous souhaitez recevoir concernant la ressource. Par exemple, si votre application n'a besoin d'être informée que des nouveaux messages publiés dans un espace Chat, elle peut simplement s'abonner aux événements concernant les messages créés.
  • notificationEndpoint : point de terminaison de notification où votre abonnement Google Workspace envoie des événements. Utilisez le sujet Pub/Sub que vous avez créé dans la section précédente.
  • payloadOptions : options permettant de spécifier la quantité de données de ressources à inclure dans la charge utile de l'événement. Cette configuration affecte le délai d'expiration de votre abonnement. Pour en savoir plus, consultez Données d'événement.

Pour créer un abonnement Google Workspace :

Apps Script

  1. Dans votre projet Apps Script, créez un fichier de script nommé createSubscription et ajoutez le code suivant :

    function createSubscription() {
  // The Google Workspace resource to monitor for events.
  const targetResource = 'TARGET_RESOURCE';

  // The types of events to receive.
  const eventTypes = [EVENT_TYPES];

  // The endpoint to deliver events to, such as a Google Cloud Pub/Sub topic.
  const pubsubTopic = 'TOPIC_NAME';

  // Whether to include resource data or not.
  const resourceData = RESOURCE_DATA;

  // Call the Workspace Events API using the advanced service.
  const response = WorkspaceEvents.Subscriptions.create({
    targetResource: targetResource,
    eventTypes: eventTypes,
    notificationEndpoint: {
      pubsubTopic: pubsubTopic,
    },
    payloadOptions: {
      includeResource: resourceData
    }
  });
  console.log(response);
}

    Remplacez les éléments suivants :

    • TARGET_RESOURCE : ressource Google Workspace à laquelle vous vous abonnez, au format de son nom complet. Par exemple, pour vous abonner à un espace Chat avec l'ID d'espace AAAABBBB, utilisez //chat.googleapis.com/spaces/AAAABBBB.
    • EVENT_TYPES : un ou plusieurs types d'événements auxquels vous souhaitez vous abonner dans la ressource cible. À formater sous forme de tableau de chaînes, par exemple 'google.workspace.chat.message.v1.created'.
    • TOPIC_NAME : nom complet du sujet Pub/Sub que vous avez créé dans votre projet Cloud. Format : projects/PROJECT_ID/topics/TOPIC_ID.

    • RESOURCE_DATA : valeur booléenne qui spécifie si l'abonnement inclut des données de ressources dans la charge utile :

      • True : inclut toutes les données de ressources. Pour limiter les champs inclus, ajoutez le champ fieldMask et spécifiez au moins un champ pour la ressource modifiée. Seuls les abonnements aux ressources Chat permettent d'inclure des données de ressources.
      • False : exclut les données de ressources.

  2. Pour créer l'abonnement Google Workspace, exécutez la fonction createSubscription dans votre projet Apps Script.

Python

  1. Dans votre répertoire de travail, créez un fichier nommé create_subscription.py et ajoutez le code suivant :

    """Create subscription."""

from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build

# Specify required scopes.
SCOPES = [SCOPES]

# Authenticate with Google Workspace and get user authentication.
flow = InstalledAppFlow.from_client_secrets_file('credentials.json', SCOPES)
CREDENTIALS = flow.run_local_server()

# The Google Workspace resource to monitor for events.
TARGET_RESOURCE = 'TARGET_RESOURCE'

# The types of events to receive.
EVENT_TYPES = [EVENT_TYPES]

# The endpoint to deliver events to, such as a Google Cloud Pub/Sub topic.
TOPIC = 'TOPIC_NAME'

# Call the Workspace Events API using the service endpoint.
service = build(
    'workspaceevents',
    'v1',
    credentials=CREDENTIALS,
)

BODY = {
    'target_resource': TARGET_RESOURCE,
    'event_types': EVENT_TYPES,
    'notification_endpoint': {'pubsub_topic': TOPIC},
    'payload_options': {'include_resource': RESOURCE_DATA},
}
response = service.subscriptions().create(body=BODY).execute()
print(response)

    Remplacez les éléments suivants :

    • SCOPES : un ou plusieurs champs d'application OAuth compatibles avec chaque type d'événement de l'abonnement. Présentés sous la forme d'un tableau de chaînes. Pour lister plusieurs champs d'application, séparez-les par une virgule. Par exemple, 'https://www.googleapis.com/auth/chat.spaces.readonly', 'https://www.googleapis.com/auth/chat.memberships.readonly'.
    • TARGET_RESOURCE : ressource Google Workspace à laquelle vous vous abonnez, au format de son nom de ressource complet. Par exemple, pour vous abonner à un espace Chat avec l'ID d'espace AAAABBBB, utilisez //chat.googleapis.com/spaces/AAAABBBB.
    • EVENT_TYPES : un ou plusieurs types d'événements auxquels vous souhaitez vous abonner dans la ressource cible. À formater sous forme de tableau de chaînes, par exemple 'google.workspace.chat.message.v1.created'.
    • TOPIC_NAME : nom complet du sujet Pub/Sub que vous avez créé dans votre projet Cloud. Format : projects/PROJECT_ID/topics/TOPIC_ID.

    • RESOURCE_DATA : valeur booléenne qui spécifie si l'abonnement inclut des données de ressources dans la charge utile :

      • True : inclut toutes les données de ressources. Pour limiter les champs inclus, ajoutez le champ fieldMask et spécifiez au moins un champ pour la ressource modifiée. Seuls les abonnements aux ressources Chat permettent d'inclure des données de ressources.
      • False : exclut les données de ressources.

  2. Pour créer l'abonnement Google Workspace, exécutez la commande suivante dans votre terminal :

    python3 create_subscription.py

L'API Google Workspace Events renvoie une opération de longue durée terminée qui contient l'instance de la ressource Subscription que vous avez créée.

Tester votre abonnement Google Workspace

Pour vérifier que vous recevez des événements Google Workspace, vous pouvez déclencher un événement et extraire des messages vers l'abonnement Pub/Sub.

Pour tester votre abonnement Google Workspace :

Console Google APIs

  1. Déclenchez un ou plusieurs types d'événements dans la ressource cible de votre abonnement Google Workspace. Par exemple, si vous vous êtes abonné aux nouveaux messages d'un espace Chat, publiez un message dans cet espace.

  2. Dans la console Google APIs, accédez à la page Pub/Sub :

    Accéder à Pub/Sub

    Assurez-vous que le projet Cloud de votre application est sélectionné.

  3. Dans le menu Pub/Sub, cliquez sur Abonnements.

  4. Dans le tableau, recherchez l'abonnement Pub/Sub correspondant à votre sujet, puis cliquez sur le nom de l'abonnement.

  5. Cliquez sur l'onglet Messages.

  6. Cliquez sur Extraire. La génération d'un message Pub/Sub par un événement peut prendre quelques minutes.

gcloud

  1. Déclenchez un ou plusieurs types d'événements dans la ressource cible de votre abonnement Google Workspace. Par exemple, si vous vous êtes abonné aux nouveaux messages dans un espace Chat, publiez un message dans l'espace.

  2. Exécutez la commande suivante :

    gcloud pubsub subscriptions pull PUBSUB_SUBSCRIPTION_NAME --format=json --limit=MESSAGE_COUNT --auto-ack

    Remplacez les éléments suivants :

    • PUBSUB_SUBSCRIPTION_NAME : nom complet de votre abonnement Pub/Sub, au format projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID.
    • MESSAGE_COUNT : nombre maximal de messages Pub/Sub que vous souhaitez extraire.

    La génération d'un message Pub/Sub par un événement peut prendre quelques minutes.

Pour chaque événement Google Workspace que vous avez déclenché, un message contenant l'événement est envoyé à votre abonnement Pub/Sub. Pour en savoir plus, consultez Recevoir des événements sous forme de messages Google Cloud Pub/Sub.

Configurer la manière dont votre application reçoit les événements

L'abonnement Pub/Sub que vous avez créé est basé sur l'extraction. Après avoir testé votre abonnement Pub/Sub, vous pouvez modifier le type de diffusion pour changer la façon dont votre application reçoit les événements. Par exemple, vous pouvez configurer l'abonnement Pub/Sub sur un type de distribution push, afin que votre application puisse recevoir des événements directement sur un point de terminaison d'application.

Pour en savoir plus sur la configuration d'un abonnement Pub/Sub, consultez la documentation Pub/Sub.

S'abonner aux événements d'un espace Chat en tant qu'application Google Chat

Vous pouvez vous abonner aux événements Chat en tant qu'application Chat depuis un espace dont l'application Chat est membre. Les applications Chat ne peuvent pas s'abonner aux événements utilisateur.

Écrire un script qui appelle l'API Google Workspace Events

Voici comment créer un abonnement aux événements d'un espace Chat avec l'authentification de l'application et l'approbation de l'administrateur :

  1. Si nécessaire, créez une application Chat.

  2. S'abonner à une ressource Chat, mais :

    1. Au lieu de l'authentification des utilisateurs, authentifiez-vous en tant qu'application Chat avec l'approbation unique de l'administrateur.

    2. Spécifiez les habilitations d'autorisation qui permettent à l'application Chat de s'abonner aux événements Chat. Ces champs d'application d'autorisation commencent toujours par chat.app et incluent les éléments suivants :

      • https://www.googleapis.com/auth/chat.app.memberships : s'abonner aux événements des membres d'un espace Chat.
      • https://www.googleapis.com/auth/chat.app.memberships.readonly : s'abonner aux événements des membres d'un espace Chat.
      • https://www.googleapis.com/auth/chat.app.messages.readonly : s'abonner aux événements de message et de réaction dans un espace Chat.
      • https://www.googleapis.com/auth/chat.app.spaces : s'abonner aux événements d'un espace Chat.
      • https://www.googleapis.com/auth/chat.app.spaces.readonly : s'abonner aux événements d'un espace Chat.

L'exemple de code suivant s'abonne aux événements de message dans un espace Chat spécifié :

Python 

  """Create subscription."""

  from google.oauth2 import service_account
  from apiclient.discovery import build

  # Specify required scopes.
  SCOPES = ['https://www.googleapis.com/auth/chat.app.messages.readonly']

  # Specify service account details.
  CREDENTIALS = (
      service_account.Credentials.from_service_account_file('credentials.json')
      .with_scopes(SCOPES)
  )

  # The Google Workspace resource to monitor for events.
  TARGET_RESOURCE = '//chat.googleapis.com/spaces/SPACE_ID'

  # The types of events to receive.
  EVENT_TYPES = [
                  'google.workspace.chat.message.v1.created',
                  'google.workspace.chat.message.v1.updated',
                  'google.workspace.chat.message.v1.deleted',
                ]

  # The endpoint to deliver events to, such as a Google Cloud Pub/Sub topic.
  TOPIC = 'TOPIC_NAME'

  # Call the Workspace Events API using the service endpoint.
  service = build(
      'workspaceevents',
      'v1',
      credentials=CREDENTIALS,
  )

  BODY = {
      'target_resource': TARGET_RESOURCE,
      'event_types': EVENT_TYPES,
      'notification_endpoint': {'pubsub_topic': TOPIC},
      'payload_options': {'include_resource': RESOURCE_DATA},
  }
  response = service.subscriptions().create(body=BODY).execute()
  print(response)

Remplacez les éléments suivants :

  • SPACE_ID : nom de l'espace, que vous pouvez obtenir à l'aide de la méthode spaces.list de l'API Chat ou à partir de l'URL d'un espace.
  • TOPIC_NAME : nom complet du sujet Pub/Sub que vous avez créé dans votre projet Cloud. Format : projects/PROJECT_ID/topics/TOPIC_ID.

  • RESOURCE_DATA : valeur booléenne qui spécifie si l'abonnement inclut des données de ressources dans la charge utile :

    • True : inclut toutes les données de ressources. Pour limiter les champs inclus, ajoutez le champ fieldMask et spécifiez au moins un champ pour la ressource modifiée. Seuls les abonnements aux ressources Chat permettent d'inclure des données de ressources.
    • False : exclut les données de ressources.

S'abonner à tous les événements Chat d'une organisation Google Workspace en tant qu'application Google Chat

Un abonnement client permet à votre application Chat de surveiller les événements d'espace et les événements utilisateur dans l'ensemble d'une organisation Google Workspace.

Pour en savoir plus sur la distribution des événements pour les abonnements client, y compris dans les espaces gérés par des organisations externes, consultez Limites et comportements de distribution des abonnements client.

Conditions requises et limites

  • Authentification : S'authentifier en tant qu'application Chat avec l'approbation unique d'un administrateur
  • SKU : l'organisation Google Workspace doit disposer d'au moins une licence SKU Enterprise. Notez que cette exigence n'est pas strictement appliquée pendant la phase du programme Preview développeur, mais qu'elle le sera à l'avenir (nous l'annoncerons séparément).
  • Unicité : une application Chat ne peut créer qu'un seul abonnement client pour une organisation Google Workspace donnée. Une organisation Google Workspace peut avoir jusqu'à cinq abonnements client au total (créés par différentes applications Chat).
  • Champs d'application : nécessite un ou plusieurs des champs d'application suivants, en fonction des types d'événements que vous souhaitez recevoir :
    • https://www.googleapis.com/auth/chat.app.all.spaces.readonly : pour recevoir des événements concernant les espaces.
    • https://www.googleapis.com/auth/chat.app.all.memberships.readonly : pour recevoir des événements concernant les appartenances.
    • https://www.googleapis.com/auth/chat.app.all.messages.readonly : pour recevoir des événements concernant les messages et les réactions.
    • https://www.googleapis.com/auth/chat.app.all.users.readstate.readonly ( Preview développeur) : pour recevoir des événements sur l'état de lecture des utilisateurs.

Créer un abonnement client

Pour créer un abonnement client, appelez la méthode subscriptions.create.

L'exemple de code Python suivant crée un abonnement client :

Python 

"""Create a customer subscription."""

from google.oauth2 import service_account
from apiclient.discovery import build

# Specify required scopes.
# Replace with the scopes needed for the event types you want to receive.
SCOPES = ['https://www.googleapis.com/auth/chat.app.all.messages.readonly']

# Specify service account details.
CREDENTIALS = (
    service_account.Credentials.from_service_account_file('credentials.json')
    .with_scopes(SCOPES)
)

# Monitor all events for the Google Workspace organization.
TARGET_RESOURCE = '//admin.googleapis.com/customers/CUSTOMER_ID'

# The types of events to receive.
EVENT_TYPES = [
    'google.workspace.chat.message.v1.created',
    'google.workspace.chat.message.v1.updated',
    'google.workspace.chat.message.v1.deleted',
]

# The endpoint to deliver events to.
TOPIC = 'TOPIC_NAME'

# Call the Workspace Events API.
# Note: Use the v1beta endpoint for Developer Preview features.
service = build(
    'workspaceevents',
    'v1beta',
    credentials=CREDENTIALS,
)

BODY = {
    'target_resource': TARGET_RESOURCE,
    'event_types': EVENT_TYPES,
    'notification_endpoint': {'pubsub_topic': TOPIC},
    'payload_options': {'include_resource': RESOURCE_DATA},
}

response = service.subscriptions().create(body=BODY).execute()
print(response)

Remplacez les éléments suivants :

  • CUSTOMER_ID : ID client. Vous pouvez également utiliser l'alias my_customer pour l'organisation Google Workspace de l'application Chat.
  • TOPIC_NAME : nom complet du sujet Pub/Sub que vous avez créé dans votre projet Cloud. Formaté en tant que projects/PROJECT_ID/topics/TOPIC_ID.
  • RESOURCE_DATA : valeur booléenne qui spécifie si l'abonnement inclut des données de ressources dans la charge utile :
    • True : inclut toutes les données de ressources. Pour limiter les champs inclus, ajoutez le champ fieldMask et spécifiez au moins un champ pour la ressource modifiée. Seuls les abonnements aux ressources Chat permettent d'inclure des données de ressources.
    • False : exclut les données de ressources.