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). Votre application peut s'abonner à une ressource Google Workspace pour recevoir les événements qui vous intéressent.

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

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

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

1. Une application Chat s'abonne à un espace Chat.
2. Modifications apportées à l'espace Chat. 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 informations 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 une liste des termes courants utilisés dans l'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 spécification CloudEvents et peuvent être un événement d'abonnement ou un événement de cycle de vie :

Événement d'abonnement

 Modification de la ressource Google Workspace que vous surveillez, par exemple un nouveau message dans un espace Google 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 aucun événement d'abonnement. Par défaut, votre abonnement reçoit toujours les événements de cycle de vie. Pour en savoir plus, consultez Événements du 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 ressource Subscription. 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 concernant la ressource cible. Par exemple, si vous vous êtes abonné à un espace Google Chat, vous pouvez choisir de recevoir ou non des événements concernant l'espace et ses ressources enfants, comme les membres et les messages.

Point de terminaison de notification

Point de terminaison où l'abonnement Google Workspace reçoit les événements. L'API Google Workspace Events accepte les sujets Google Cloud Pub/Sub comme 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 affiche les événements acceptés pour chaque ressource cible possible.

Pour en savoir plus, consultez les guides suivants :

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

Structure des événements Google Workspace

Les événements Google Workspace suivent la spécification CloudEvents, qui est une méthode standard dans l'industrie 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 indiquer 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 spaces.message Chat qui a été créée.

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

• Inclure les données de ressource : contient tout ou partie des champs de la ressource modifiée. Si vous choisissez d'inclure des données de ressources, la durée de votre abonnement est limitée à quatre heures maximum, ou à 24 heures si vous utilisez la délégation à l'échelle du domaine.
• Exclure les données de ressource : ne contient que le nom de la ressource modifiée. La durée de votre abonnement est de sept jours maximum. Pour obtenir des informations sur 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 le champ payloadOptions 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 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 CloudEvent, y compris le type d'événement. Dans ce cas, l'événement concerne un message modifié dans l'espace.
• data : données d'événement avec des informations sur la ressource spaces.message mise à jour, mises en forme sous forme de chaîne encodée en Base64.
• messageId : identifiant du message Google Cloud Pub/Sub.

Pour en savoir plus sur la façon dont les CloudEvents sont spécifiés 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