S'abonner à des événements à l'aide de l'API Google Workspace Events

Cette page présente l'API Google Workspace Events et explique comment vous pouvez utiliser l'API pour vous abonner à des événements dans Google Workspace.

Les événements Google Workspace représentent des modifications apportées aux ressources Google Workspace, comme la création, la mise à jour ou la suppression de ressources. Votre appli peut s'abonner à une ressource Google Workspace afin de recevoir les événements pertinents qui vous intéressent.

Comment votre application reçoit les événements

Pour autoriser votre application à recevoir des événements Google Workspace, vous devez utiliser le L'API Google Workspace Events pour créer des abonnements à Google Workspace ressources.

Illustration de la manière dont l'API Google Workspace Events envoie des événements.
Figure 1 : Exemple illustrant comment le paramètre L'API Google Workspace Events envoie des événements Application Chat

Dans l'exemple suivant, voici comment l'API Google Workspace Events fournit à une application Google Chat via un abonnement:

  1. Une application Chat s'abonne à un espace Chat.
  2. L'espace Chat change. Par exemple, un nouveau message est publié dans l'espace.
  3. Le chat envoie un événement à un sujet dans Google Cloud Pub/Sub, qui sert de point de terminaison de notification pour l'abonnement. L'événement contient des données sur ce qui a changé. Par exemple, pour un événement concernant s'affiche, l'événement contient des détails sur la ressource Message qui est créé.
  4. L'application Chat traite l'environnement Google Cloud Message Pub/Sub contenant l'événement et, si nécessaire, prend des mesures.

Terminologie importante

Vous trouverez ci-dessous une liste des termes couramment utilisés dans les API Google Workspace Events:

Événement Google Workspace

Modification d'une ressource Google Workspace. Les événements sont mis en forme à l'aide de la méthode CloudEvents et il peut s'agir d'un événement d'abonnement ou un événement de cycle de vie:

Événement d'abonnement
Une modification apportée à la ressource Google Workspace que vous surveillez, comme un nouveau message dans un espace Google Chat. Vous pouvez spécifier détails que vous souhaitez recevoir sur la ressource qui a été modifiée. Pour en savoir plus, consultez Structure des événements Google Workspace
Événement de cycle de vie
Événement concernant votre abonnement Google Workspace. Événements du cycle de vie vous informer des problèmes et de l'état de votre abonnement afin que vous puissiez pour éviter de manquer des événements d'abonnement. Par défaut, votre abonnement reçoit les événements de cycle de vie. Pour en savoir plus, consultez la section Événements de cycle de vie des abonnements Google Workspace.
Abonnement Google Workspace

Entité nommée qui surveille une ressource depuis un environnement Google Workspace application. Un abonnement est représenté par Subscription ressource. Un abonnement est défini par les informations suivantes:

Ressource cible
Ressource Google Workspace que vous souhaitez surveiller. Cette ressource est représentée dans le champ targetResource de la abonnement Google Workspace. Chaque abonnement ne peut et de surveiller une ressource. Pour savoir quelles ressources Google Workspace la compatibilité de l'API Google Workspace Events, consultez Événements Google Workspace compatibles
Types d'événements
Types de modifications pour lesquelles vous souhaitez être informé la ressource cible. Par exemple, si vous êtes abonné à un espace Google Chat, vous pouvez choisir de recevoir ou non des événements sur l'espace et ses ressources enfants, telles que les abonnements et les messages.
Point de terminaison de la notification
Point de terminaison où L'abonnement Google Workspace reçoit des événements. La L'API Google Workspace Events est compatible avec les sujets Google Cloud Pub/Sub un point de terminaison de notification. Pour en savoir plus sur l'utilisation de Google Cloud Pub/Sub, consultez les Documentation Google Cloud Pub/Sub
Options de charge utile
Données d'événement que vous souhaitez recevoir sur les ressources modifiées.

Événements Google Workspace compatibles

Les événements pour lesquels votre application peut recevoir des événements dépendent de la ressource cible de votre abonnement. Le tableau suivant présente les événements acceptés pour chaque ressource cible possible.

Ressource cible Événements compatibles
Espaces Google Chat
  • Messages
  • Souscriptions
  • Réactions
  • Espace
Utilisateurs de Google Chat
  • Souscriptions
Espaces de réunion Google Meet
  • Conférences
  • Sessions des participants
  • Enregistrements
  • Transcriptions
Utilisateurs de Google Meet
  • Conférences
  • Sessions des participants
  • Enregistrements
  • Transcriptions

Pour en savoir plus, consultez les guides suivants:

Structure des événements Google Workspace

Les événements Google Workspace suivent la session CloudEvents spécification, qui est une façon standard de l'industrie de décrire les données d'événement. Google Workspace événements contiennent les éléments suivants:

  • Attributs de l'événement CloudEvent.
  • Données sur la ressource Google Workspace qui a changé suite à l'événement

La section suivante explique la structure des attributs et des données pour événements Google Workspace.

Attributs CloudEvent

Les événements Google Workspace contiennent les éléments obligatoires suivants : Attributs CloudEvents:

Attribut Description Exemple

datacontenttype

Type de données transmises dans l'événement.

application/json

id

Identifiant de l'événement CloudEvent.

spaces/AAAABBBBBBB/spaceEvents/ABCDEFGHIJKLMNO

source

Source de l'événement. Pour les événements Google Workspace, il s'agit du nom de ressource complet de l'abonnement. //workspaceevents.googleapis.com/subscriptions/chat-spaces-abcdefg

specversion

Version de spécification CloudEvents utilisée pour cet événement.

1.0

subject

Ressource Google Workspace dans laquelle l'événement s'est produit.

//chat.googleapis.com/spaces/AAAABBBBBBB

time

Code temporel du moment où l'événement s'est produit, au format RFC 3339.

2023-09-07T21:37:36.260127Z

type

Type d'événement Google Workspace.

google.workspace.chat.message.v1.created

Données d'événement

Les données d'événement sont une charge utile qui représente une modification de la cible de votre abonnement ressource, y compris les ressources enfants de la ressource cible. Dans votre vous pouvez spécifier si la charge utile doit inclure des données la ressource modifiée, ou simplement le nom de la ressource modifiée.

Par exemple, si vous êtes abonné à un espace Chat, vous peut recevoir des événements concernant les nouveaux messages reçus dans l'espace. Pour les événements concernant les données d'événement contiennent une charge utile avec l'objet Ressource spaces.message créée.

Lorsque vous créez un abonnement, vous pouvez spécifier la quantité de données de ressources inclus dans les événements que votre application reçoit:

  • Inclure les données de ressource:contient tout ou partie des champs des données ressource. Si vous choisissez d'inclure des données de ressources, votre abonnement est limitée à 4 heures ou 24 heures si vous utilisez l'ensemble du domaine délégation.
  • Exclure les données de ressources: ne contient que le nom de l'élément ressource. La durée de votre abonnement peut atteindre sept jours. Pour obtenir des informations l'événement, vous pouvez interroger la ressource à l'aide de son nom.

Ces options pour les données d'événement sont représentées dans la payloadOptions de votre abonnement.

Événements en tant que messages Google Cloud Pub/Sub

Les abonnements à l'API Google Workspace Events utilisent Google Cloud Pub/Sub. des sujets en tant que point de terminaison des notifications qui reçoit les événements. Les événements sont encodés en tant que messages Google Cloud Pub/Sub. Votre application peut traiter le message Google Cloud Pub/Sub pour prendre des mesures ou répondre l'événement.

L'exemple suivant présente un message Google Cloud Pub/Sub contenant un événement concernant un message modifié dans un espace Chat:

 {
    "message":
    {
        "attributes":
        {
            "ce-datacontenttype": "application/json",
            "ce-id": "spaces/SPACE_ID/spaceEvents/SPACE_EVENT_ID",
            "ce-source": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
            "ce-specversion": "1.0",
            "ce-subject": "//chat.googleapis.com/spaces/SPACE_ID",
            "ce-time": "2023-09-07T21:37:53.274191Z",
            "ce-type": "google.workspace.chat.message.v1.updated"
        },
        "data": "EVENT_DATA",
        "messageId": "PUBSUB_MESSAGE_ID",
        "orderingKey": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
        "publishTime": "2023-09-07T21:37:53.713Z"
    }
}

Notez les champs suivants:

  • attributes : attributs de l'événement CloudEvent, qui incluent : le type d'événement. Dans ce cas, l'événement concerne un message mis à jour dans espace.
  • data: données d'événement contenant des détails sur l'événement mis à jour spaces.message, mise en forme sous la forme d'une chaîne encodée en base64.
  • messageId: identifiant du message Google Cloud Pub/Sub.

En savoir plus sur la spécification des événements CloudEvents dans Google Cloud Pub/Sub consultez la page Liaison de protocole Google Cloud Pub/Sub pour CloudEvents.