En esta página, se proporciona una descripción general de la API de Google Workspace Events y se explica cómo usarla para suscribirse a eventos en Google Workspace.
Los eventos de Google Workspace representan cambios en los recursos de Google Workspace, como cuándo se crean, se actualizan o se borran recursos. Usa la API de Google Workspace Events para suscribirte a un recurso de Google Workspace y recibir eventos relevantes.
Cómo recibe eventos tu app
Para permitir que tu app reciba eventos de Google Workspace, usa la API de Google Workspace Events para crear suscripciones a recursos de Google Workspace.
En el siguiente ejemplo, se describe cómo la API de Google Workspace Events entrega eventos a una app de Chat a través de una suscripción:
- Una app de Chat se suscribe a un espacio de Google Chat.
- El espacio de Chat cambia. Por ejemplo, se publica un mensaje nuevo en el espacio.
- Chat entrega un evento a un tema en
Google Cloud Pub/Sub,
que funciona como el extremo de notificación para la suscripción. El evento contiene datos sobre lo que cambió. Por ejemplo, para un evento sobre un mensaje nuevo, el evento contiene detalles sobre el recurso
Messageque se creó. - La app de Chat procesa el mensaje de Google Cloud Pub/Sub que contiene el evento y, si es necesario, toma medidas.
Terminología importante
Entre los términos comunes que se usan en la API de Google Workspace Events, se incluyen los siguientes:
- Evento de Google Workspace
Un cambio en un recurso de Google Workspace. Los eventos se formatean con la especificación de CloudEvents y pueden ser un evento de suscripción o un evento de ciclo de vida:
- Evento de suscripción
- Un cambio en el recurso de Google Workspace que supervisas, como un mensaje nuevo en un espacio de Chat. Puedes especificar cuántos detalles deseas recibir sobre el recurso que cambió. Para obtener más información, consulta Estructura de los eventos de Google Workspace.
- Evento de ciclo de vida
- Un evento sobre tu suscripción a Google Workspace. Los eventos de ciclo de vida te notifican sobre los problemas y el estado de tu suscripción para que no te pierdas los eventos de suscripción. De forma predeterminada, tu suscripción siempre recibe eventos de ciclo de vida. Para obtener más información, consulta Eventos de ciclo de vida para suscripciones de Google Workspace.
- Suscripción a Google Workspace
Una entidad con nombre que supervisa un recurso de una aplicación de Google Workspace. Una suscripción se representa con un
Subscriptionrecurso. Una suscripción se define con la siguiente información:- Recurso objetivo
- El recurso de Google Workspace que deseas supervisar.
Este recurso se representa en el campo
targetResourcede la suscripción a Google Workspace. Cada suscripción solo puede supervisar un recurso. Para ver qué recursos de Google Workspace admite la API de Google Workspace Events, consulta Eventos de Google Workspace admitidos. - Tipos de eventos
- Los tipos de cambios sobre los que deseas recibir notificaciones para el recurso objetivo. Por ejemplo, si te suscribiste a un espacio de Chat, puedes elegir si deseas recibir eventos sobre el espacio y sus recursos secundarios, como membresías y mensajes.
- Extremo de notificación
- El extremo en el que la suscripción a Google Workspace recibe eventos. La API de Google Workspace Events admite temas de Google Cloud Pub/Sub como extremo de notificación. Para obtener más información sobre el uso de Google Cloud Pub/Sub, consulta la documentación de Google Cloud Pub/Sub.
- Opciones de carga útil
- Los datos de eventos que deseas recibir sobre los recursos modificados.
Eventos de Google Workspace admitidos
Los eventos que puede recibir tu app dependen del recurso objetivo de tu suscripción. En la siguiente tabla, se muestran los eventos admitidos para cada recurso objetivo posible.
| Recurso objetivo | Eventos admitidos |
|---|---|
| Espacios de Chat |
|
| Usuarios de Chat |
|
| Archivos de Google Drive o archivos de unidades compartidas |
|
| Espacios de reuniones y usuarios de Google Meet |
Para obtener más información, consulta las siguientes guías:
Estructura de los eventos de Google Workspace
Los eventos de Google Workspace siguen la especificación de CloudEvents, que es una forma estándar de la industria de describir los datos de eventos. Los eventos de Google Workspace contienen lo siguiente:
- Atributos de CloudEvent
- Datos sobre el recurso de Google Workspace que cambió como resultado del evento
En la siguiente sección, se explica la estructura de los atributos y los datos de los eventos de Google Workspace.
Atributos de CloudEvent
Los eventos de Google Workspace contienen los siguientes atributos obligatorios de CloudEvents:
| Atributo | Descripción | Ejemplo |
|---|---|---|
|
El tipo de datos que se pasó en el evento |
|
|
Un identificador para CloudEvent |
|
|
La fuente del evento Para los eventos de Google Workspace, este es el nombre completo del recurso de la suscripción. |
//workspaceevents.googleapis.com/subscriptions/chat-spaces-abcdefg
|
|
La versión de la especificación de CloudEvent que se usa para este evento. |
|
|
El recurso de Google Workspace en el que ocurrió el evento |
|
|
La marca de tiempo en la que ocurrió el evento, en formato RFC 3339 |
|
|
El tipo de evento de Google Workspace |
|
Datos de eventos
Los datos de eventos son una carga útil que representa un cambio en el recurso objetivo de tu suscripción, incluidos los recursos secundarios del recurso objetivo. En tu suscripción, puedes especificar si deseas que la carga útil incluya datos sobre el recurso modificado o solo el nombre del recurso modificado.
Por ejemplo, si tienes una suscripción a un espacio de Chat, puedes recibir eventos sobre mensajes nuevos en el espacio. Para los eventos sobre mensajes nuevos, los datos de eventos contienen una carga útil con el recurso spaces.message de Chat que se creó.
Cuando creas una suscripción, puedes especificar cuántos datos de recursos se incluyen en los eventos que recibe tu app.
| Datos de recursos | Carga útil | Vencimiento de la suscripción |
|---|---|---|
| Incluir datos de recursos | Contiene algunos o todos los campos del recurso modificado. | Hasta 4 horas o 24 horas si usas la delegación de todo el dominio. |
| Excluir datos de recursos | Contiene solo el nombre del recurso modificado. | Hasta 7 días |
Estas opciones para los datos de eventos se representan en el
payloadOptions
campo de tu suscripción.
Eventos como mensajes de Google Cloud Pub/Sub
Las suscripciones a la API de Google Workspace Events usan temas de Google Cloud Pub/Sub como el extremo de notificación que recibe eventos de Google Workspace. Los eventos se codifican como mensajes de Google Cloud Pub/Sub. Tu app puede procesar el mensaje de Google Cloud Pub/Sub para tomar medidas o responder al evento.
En el siguiente ejemplo, se muestra un mensaje de Google Cloud Pub/Sub que contiene un evento sobre un mensaje actualizado en un espacio de 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"
}
}
Este ejemplo contiene los siguientes campos:
attributes: Atributos de CloudEvent, que incluyen el tipo de evento. En este caso, el evento trata sobre un mensaje actualizado en el espacio.data: Los datos de eventos con detalles sobre el recurso actualizadospaces.message, con formato de cadena codificada en Base64.messageId: El identificador del mensaje de Google Cloud Pub/Sub.
Para obtener más información sobre cómo se especifican los CloudEvents en los mensajes de Google Cloud Pub/Sub, consulta Vinculación del protocolo de Google Cloud Pub/Sub para CloudEvents.