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 l'utiliser pour vous abonner à des événements dans Google Workspace.

Les événements Google Workspace représentent des modifications apportées aux ressources Google Workspace (création, mise à jour ou suppression de ressources, par exemple). Utilisez l'API Google Workspace Events pour vous abonner à une ressource Google Workspace et recevoir les événements pertinents.

Comment votre application reçoit-elle des événements ?

Pour permettre à votre application de recevoir des événements Google Workspace, utilisez l'API Google Workspace Events afin de créer des abonnements aux ressources Google Workspace.

L'exemple suivant décrit comment l'API Google Workspace Events fournit des événements à une application Chat via un abonnement :

1. Une application Chat s'abonne à un espace Google Chat.
2. L'espace Chat est modifié. Par exemple, un nouveau message est publié dans l'espace.
3. 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 été modifié. Par exemple, pour un événement concernant un nouveau message, l'événement contient des détails sur la ressource Message créée.
4. L'application Chat traite le message Google Cloud Pub/Sub contenant l'événement et, si nécessaire, prend des mesures.

Terminologie importante

Voici quelques termes courants utilisés dans l'API Google Workspace Events :

Événement Google Workspace

Modification apportée à une ressource Google Workspace. Les événements sont mis en forme à l'aide de la spécification CloudEvents et peuvent être un événement d'abonnement ou un événement de cycle de vie :

Événement d'abonnement

Modification apportée à la ressource Google Workspace que vous surveillez, par exemple un nouveau message dans un espace Chat. Vous pouvez spécifier le niveau de détail que vous souhaitez recevoir sur la ressource 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. Les événements de cycle de vie vous informent des problèmes et de l'état de votre abonnement afin que vous ne manquiez pas d'événements d'abonnement. Par défaut, votre abonnement reçoit toujours des événements de cycle de vie. Pour en savoir plus, consultez Événements de cycle de vie pour les abonnements Google Workspace.

Abonnement Google Workspace

Entité nommée qui surveille une ressource à partir d'une application Google Workspace. Un abonnement est représenté par une 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 l'abonnement Google Workspace. Chaque abonnement ne peut surveiller qu'une seule ressource. Pour savoir quelles ressources Google Workspace sont compatibles avec l' API Google Workspace Events, consultez Événements Google Workspace compatibles.

Types d'événements

Types de modifications pour lesquels vous souhaitez recevoir des notifications pour la ressource cible. Par exemple, si vous êtes abonné à un espace Chat, vous pouvez choisir de recevoir des événements concernant l'espace et ses ressources enfants, telles que les souscriptions et les messages.

Point de terminaison de notification

Point de terminaison où l'abonnement Google Workspace reçoit des événements. L'API Google Workspace Events est compatible avec les sujets Google Cloud Pub/Sub en tant que point de terminaison de notification. Pour en savoir plus sur l'utilisation de Google Cloud Pub/Sub, consultez la documentation Google Cloud Pub/Sub.

Options de charge utile

Les données d'événement que vous souhaitez recevoir sur les ressources modifiées.

Événements Google Workspace compatibles

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

Pour en savoir plus, consultez les guides suivants :

• S'abonner aux événements Chat
• S'abonner aux événements Drive
• S'abonner aux événements Meet

Structure des événements Google Workspace

Les événements Google Workspace suivent la spécification CloudEvents, qui est une méthode standard du secteur pour décrire les données d'événement. Les événements Google Workspace contiennent les éléments suivants :

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

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

Attributs CloudEvent

Les événements Google Workspace contiennent les attributs CloudEvents obligatoires suivants :

Données d'événement

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

Par exemple, si vous êtes abonné à un espace Chat, vous pouvez recevoir des événements concernant les nouveaux messages dans l'espace. Pour les événements concernant les nouveaux messages, les données d'événement contiennent une charge utile avec la ressource Chat spaces.message qui a été créée.

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

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

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

Les abonnements à l'API Google Workspace Events utilisent des sujets Google Cloud Pub/Sub comme point de terminaison de notification qui reçoit les événements Google Workspace. 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 montre un message Google Cloud Pub/Sub contenant un événement concernant un message mis à jour 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"
    }
}

Cet exemple contient les champs suivants :

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

Pour en savoir plus sur la spécification des CloudEvents dans les messages Google Cloud Pub/Sub, consultez Liaison de protocole Google Cloud Pub/Sub pour CloudEvents.

Articles associés

• Choisir les habilitations de l'API Google Workspace Events
• Créer un abonnement Google Workspace