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 (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 des é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.

Illustration de la façon dont l'API Google Workspace Events diffuse des événements. — **Figure 1 :** Exemple de la façon dont l'API Google Workspace Events envoie des événements à une application Chat.

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

Une application Chat s'abonne à un espace Chat.
L'espace Chat change. Par exemple, un nouveau message est publié dans l'espace.
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 un nouveau message, l'événement contient des informations sur la ressource Message créée.
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 couramment utilisés dans l'API Google Workspace Events:

Événement Google Workspace

Modification d'une ressource Google Workspace. Les événements sont formatés à l'aide de la spécification CloudEvents. Il peut s'agir d'un événement d'abonnement ou d'un événement de cycle de vie:

Événement d'abonnement: Modification de la ressource Google Workspace que vous surveillez, comme 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 la section 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 de manquer des événements d'abonnement. Par défaut, votre abonnement reçoit toujours des événements de cycle de vie. Pour en savoir plus, consultez la section Événements du 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: La 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 que vous souhaitez recevoir pour la ressource cible. Par exemple, si vous vous êtes abonné à un espace Google Chat, vous pouvez choisir de recevoir des événements concernant l'espace et ses ressources enfants, comme les adhésions 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 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 compatibles 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 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 du 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 des é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 du 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 où l'événement s'est produit.	`//chat.googleapis.com/spaces/AAAABBBBBBB`
`time`	Code temporel de l'événement, 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 simplement 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 liés à de nouveaux messages, les données d'événement contiennent une charge utile avec la ressource Chat spaces.message 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 la 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 la ressource: ne contient que le nom de la ressource modifiée. La durée de votre abonnement est de 7 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 de 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"
    }
}

Notez les champs suivants:

attributes: attributs du CloudEvent, y compris 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 informations sur la ressource spaces.message mise à jour, au format chaîne encodée en base64.
messageId: identifiant du message Google Cloud Pub/Sub.

Pour en savoir plus sur la manière dont les CloudEvents sont spécifiés dans les messages Google Cloud Pub/Sub, consultez la section Liaison de protocole Google Cloud Pub/Sub pour CloudEvents.

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