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 les modifications apportées aux ressources Google Workspace, comme la création, la mise à jour ou la suppression de ressources. Votre application peut s'abonner à une ressource Google Workspace afin de recevoir les événements qui vous intéressent.
Comment votre application reçoit les événements
Pour permettre à votre application de recevoir des événements Google Workspace, vous devez utiliser l'API Google Workspace Events afin de créer des abonnements aux ressources Google Workspace.
Dans l'exemple suivant, voici comment l'API Google Workspace Events envoie 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, il contient des détails 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 les mesures nécessaires.
Terminologie importante
Voici une liste de 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 selon la spécification CloudEvents et peuvent être des événements d'abonnement ou des événements de cycle de vie:
- Événement d'abonnement
- Modification de la ressource Google Workspace que vous surveillez, telle qu'un nouveau message dans un espace Google Chat. Vous pouvez spécifier les 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 du 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 Événements de cycle de vie pour les abonnements Google Workspace.
- Abonnement Google Workspace
Entité nommée qui surveille une ressource depuis 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 page Événements Google Workspace compatibles. - Types d'événements
- Types de modifications pour lesquels vous souhaitez être informé pour la ressource cible. Par exemple, si vous êtes abonné à un espace Google Chat, vous pouvez choisir de recevoir ou non des événements concernant cet espace et ses ressources enfants, telles que les abonnements et les messages.
- Point de terminaison de la notification
- Point de terminaison sur lequel l'abonnement Google Workspace reçoit les é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 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 pour lesquels votre application peut recevoir des événements dépendent de la ressource cible de votre abonnement. Le tableau suivant affiche les événements acceptés pour chaque ressource cible possible.
Ressource cible | Format | Événements compatibles | Limites (le cas échéant) | |
---|---|---|---|---|
Google Chat | ||||
Espaces Google Chat |
Pour vous abonner à un espace spécifique:
Pour s'abonner à tous les espaces dont l'utilisateur est membre:
|
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 |
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 |
Pour en savoir plus, consultez S'abonner aux événements Google Meet. |
||
Utilisateurs de Google Meet | //cloudidentity.googleapis.com/users/USER_ID |
Pour en savoir plus, consultez S'abonner aux événements Google Meet. |
L'abonnement reçoit des événements concernant les espaces de réunion dans lesquels l'utilisateur est l'un des éléments 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 de l'événement CloudEvent.
- Données sur la ressource Google Workspace qui a changé à 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 |
---|---|---|
|
Type de données transmises dans l'événement. |
|
|
Identifiant de l'événement CloudEvent. |
|
|
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
|
|
Version de spécification CloudEvents utilisée pour cet événement. |
|
|
Ressource Google Workspace dans laquelle l'événement s'est produit. |
|
|
Code temporel du moment où l'événement s'est produit, au format RFC 3339. |
|
|
Type d'événement Google Workspace. |
|
Données d'événement
Les données d'événement correspondent à 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 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 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 que votre application reçoit:
- Include resource data (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. La durée de votre abonnement peut atteindre 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 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 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 contenant des détails sur la ressourcespaces.message
mise à jour, formatées sous la forme d'une 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 CloudEvents dans les messages Google Cloud Pub/Sub, consultez la section Liaison de protocole Google Cloud Pub/Sub pour CloudEvents.
Articles associés
- S'abonner aux é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