Cette page a été traduite par l'API Cloud Translation.

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, par exemple lors de la création, de la mise à jour ou de la suppression de ressources. Votre application peut s'abonner à une ressource Google Workspace afin de recevoir les événements pertinents qui vous intéressent.

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

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

Illustration de la manière dont l'API Google Workspace Events fournit des événements.

Voici comment l'API Google Workspace Events envoie des événements à votre application via un abonnement:

Votre application s'abonne à une ressource d'une application Google Workspace, telle qu'un espace Google Chat.
La ressource pour laquelle vous êtes abonné change.
L'application Google Workspace envoie un événement à un sujet dans Google Cloud Pub/Sub, qui sert de point de terminaison de notification pour votre abonnement Google Workspace. L'événement contient des données sur ce qui a changé dans la ressource.
Votre application traite le message Google Cloud Pub/Sub contenant l'événement et, si nécessaire, prend les mesures nécessaires.

Terminologie importante

Voici une liste des termes couramment 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 la quantité de détails 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 puissiez éviter les événements manquants. Par défaut, votre abonnement reçoit toujours 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 à 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 connaître les ressources Google Workspace compatibles avec l'API Google Workspace Events, consultez la section Événements Google Workspace compatibles.
Types d'événements: Types de modifications pour lesquelles vous souhaitez recevoir des notifications concernant la ressource cible. Par exemple, si vous êtes abonné à un espace Google Chat, vous pouvez choisir de recevoir ou non les événements concernant cet espace et ses ressources enfants, tels 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. L'API Google Workspace Events est compatible avec les sujets Google Cloud Pub/Sub en tant que point de terminaison des notifications. Pour en savoir plus sur l'utilisation de Google Cloud Pub/Sub, consultez la documentation de 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 auxquels votre application peut recevoir des événements dépendent de la ressource cible de votre abonnement. Le tableau suivant affiche les événements compatibles avec chaque ressource cible possible.

Ressource cible	Format	Événements compatibles	Limites (le cas échéant)
Google Chat
Espaces Google Chat	`//chat.googleapis.com/spaces/SPACE_ID`	Messages Souscriptions Réactions Espace Pour en savoir plus, consultez S'abonner aux événements Google Chat.	L'utilisateur Google Chat qui autorise l'abonnement doit être membre de l'espace via son compte Google Workspace ou Google.
Utilisateurs de Google Chat	`//cloudidentity.googleapis.com/users/USER_ID`	Souscriptions Pour en savoir plus, consultez S'abonner aux événements 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 au nom d'autres utilisateurs.
Google Meet
Espaces de réunion Google Meet	`//meet.googleapis.com/spaces/SPACE_ID`	Conférences Sessions des participants Enregistrements Transcriptions Pour en savoir plus, consultez S'abonner à des événements Google Meet.
Utilisateurs de Google Meet	`//cloudidentity.googleapis.com/users/USER_ID`	Conférences Sessions des participants Enregistrements Transcriptions Pour en savoir plus, consultez S'abonner à des événements Google Meet.	L'abonnement reçoit les événements concernant les espaces de réunion où l'utilisateur est l'un des suivants: Propriétaire de l'espace de réunion. Organisateur de l'événement Google Agenda associé à l'espace de réunion.

Structure des événements Google Workspace

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

Attributs de l'événement CloudEvent.
Données sur la ressource Google Workspace 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:

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 complet de la ressource 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 où 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 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 de cet espace. Pour les événements concernant de 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 incluses dans les événements reçus par votre application:

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 à 4 heures, ou à 24 heures si vous utilisez la délégation au niveau du domaine.
Exclure les données de ressource: ne contient que le nom de la ressource modifiée. Votre abonnement dure jusqu'à sept jours. Pour obtenir des détails 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 sous forme de messages Google Cloud Pub/Sub

Les abonnements à l'API Google Workspace Events utilisent les 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 présente 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"
    }
}

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 l'espace.
data: données d'événement avec les détails de la ressource spaces.message mise à jour, formatées en tant que chaîne encodée en base64.
messageId: identifiant du message Google Cloud Pub/Sub.

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

S'abonner à des événements Google Chat
Événements de cycle de vie pour les abonnements Google Workspace
Choisir les champs d'application de l'API Google Workspace Events
Créer un abonnement Google Workspace