Se usó la API de Cloud Translation para traducir esta página.

Suscríbete a eventos con la API de Google Workspace Events

En esta página, se proporciona una descripción general de la API de Google Workspace Events y se explica cómo puedes usarla para suscribirte a eventos en Google Workspace.

Los eventos de Google Workspace representan cambios en los recursos de Google Workspace, como cuando se crean, actualizan o borran recursos. Tu app puede suscribirse a un recurso de Google Workspace para que recibas eventos relevantes que te interesen.

Cómo recibe eventos tu app

Si quieres permitir que tu app reciba eventos de Google Workspace, usa la API de Google Workspace Events para crear suscripciones a recursos de Google Workspace.

Ilustración de cómo la API de Google Workspace Events entrega eventos.

A continuación, te mostramos cómo la API de Google Workspace Events entrega eventos a tu app a través de una suscripción:

Tu app se suscribe a un recurso en una aplicación de Google Workspace, como un espacio de Google Chat.
El recurso al que te suscribiste cambia.
La aplicación de Google Workspace entrega un evento a un tema en Google Cloud Pub/Sub, que funciona como el extremo de notificación para tu suscripción a Google Workspace. El evento contiene datos sobre lo que cambió en el recurso.
Tu app procesa el mensaje de Google Cloud Pub/Sub que contiene el evento y, si es necesario, toma medidas.

Terminología importante

A continuación, se incluye una lista de términos comunes que se usan en la API de Google Workspace Events:

Evento de Google Workspace

Un cambio en un recurso de Google Workspace Los eventos se formatean mediante la especificación 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 estás supervisando, como un mensaje nuevo en un espacio de Google Chat. Puedes especificar cuántos detalles deseas recibir sobre el recurso que cambió. Para obtener más detalles, consulta Estructura de los eventos de Google Workspace.
Evento del ciclo de vida: Un evento sobre tu suscripción a Google Workspace Los eventos del ciclo de vida te notifican sobre problemas y el estado de tu suscripción para que puedas evitar la pérdida de eventos de suscripción. De forma predeterminada, tu suscripción siempre recibe eventos de ciclo de vida. Para obtener más información, consulta los eventos del ciclo de vida para las suscripciones a Google Workspace.

Suscripción a Google Workspace

Una entidad con nombre que supervisa un recurso desde una aplicación de Google Workspace. Una suscripción se representa con un recurso Subscription. Una suscripción se define según la siguiente información:

Recurso de destino: El recurso de Google Workspace que quieres supervisar. Este recurso se representa en el campo targetResource de 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 compatibles.
Tipos de eventos: Los tipos de cambios sobre los que deseas recibir notificaciones para el recurso de destino. Por ejemplo, si te suscribiste a un espacio de Google Chat, puedes elegir si quieres recibir eventos sobre el espacio y sus recursos secundarios, como membresías y mensajes.
Extremo de la notificación: El extremo en el que la suscripción a Google Workspace recibe eventos. La API de eventos de Google Workspace 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 compatibles

Los eventos en los que la app puede recibir eventos dependen del recurso de destino de la suscripción. En la siguiente tabla, se muestran los eventos compatibles para cada recurso de destino posible.

Recurso de destino	Formato	Eventos admitidos	Limitaciones (si corresponde)
Google Chat
Espacios de Google Chat	`//chat.googleapis.com/spaces/SPACE_ID`	Mensajes Membresías Reacciones Espacio Para conocer más detalles, consulta Cómo suscribirse a eventos de Google Chat.	El usuario de Google Chat que autoriza la suscripción debe ser miembro del espacio a través de su Cuenta de Google o de Google Workspace.
Usuarios de Google Chat	`//cloudidentity.googleapis.com/users/USER_ID`	Membresías Para conocer más detalles, consulta Cómo suscribirse a eventos de Google Chat.	La suscripción solo recibe eventos sobre el usuario que la autorizó. Un usuario no puede autorizar una suscripción en nombre de otros usuarios.
Google Meet
Salas de reuniones de Google Meet	`//meet.googleapis.com/spaces/SPACE_ID`	Conferencias Sesiones de participantes Grabaciones Expedientes Para conocer más detalles, consulta Cómo suscribirse a eventos de Google Meet.
Usuarios de Google Meet	`//cloudidentity.googleapis.com/users/USER_ID`	Conferencias Sesiones de participantes Grabaciones Expedientes Para conocer más detalles, consulta Cómo suscribirse a eventos de Google Meet.	La suscripción recibe eventos sobre salas de reuniones en las que el usuario es uno de los siguientes: El propietario de la sala de reuniones. Es el organizador del evento del Calendario de Google asociado a la sala de reuniones.

Estructura de 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 para los eventos de Google Workspace.

Atributos de CloudEvent

Los eventos de Google Workspace contienen los siguientes atributos obligatorios de CloudEvents:

Atributo	Descripción	Ejemplo
`datacontenttype`	El tipo de datos que se pasaron en el evento.	`application/json`
`id`	Un identificador para el CloudEvent.	`spaces/AAAABBBBBBB/spaceEvents/ABCDEFGHIJKLMNO`
`source`	Es la fuente del evento. En el caso de los eventos de Google Workspace, es el nombre completo del recurso de la suscripción.	`//workspaceevents.googleapis.com/subscriptions/chat-spaces-abcdefg`
`specversion`	La versión de la especificación de CloudEvents que se usa para este evento.	`1.0`
`subject`	El recurso de Google Workspace en el que ocurrió el evento.	`//chat.googleapis.com/spaces/AAAABBBBBBB`
`time`	Es la marca de tiempo del momento en que ocurrió el evento, en formato RFC 3339.	`2023-09-07T21:37:36.260127Z`
`type`	El tipo de evento de Google Workspace.	`google.workspace.chat.message.v1.created`

Datos de eventos

Los datos del evento son una carga útil que representa un cambio en el recurso de destino de tu suscripción, incluidos los recursos secundarios del recurso de destino. 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 ese espacio. Para los eventos sobre mensajes nuevos, los datos del evento contienen una carga útil con el recurso de Chat spaces.message que se creó.

Cuando creas una suscripción, puedes especificar la cantidad de datos de recursos que se incluyen en los eventos que recibe tu app:

Incluye datos de recursos: Contiene algunos o todos los campos del recurso modificado. Si eliges incluir datos de recursos, la duración de la suscripción se limita a un máximo de 4 horas, o a 24 horas si usas la delegación de todo el dominio.
Excluir datos de recursos: Contiene solo el nombre del recurso modificado. La duración de la suscripción es de hasta 7 días. Para obtener detalles sobre el evento, puedes consultar el recurso con el nombre del recurso.

Estas opciones de datos de eventos se representan en el campo payloadOptions de tu suscripción.

Eventos como mensajes de Google Cloud Pub/Sub

Las suscripciones a la API de Eventos de Google Workspace 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 realizar una acción 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"
    }
}

Ten en cuenta los siguientes campos:

attributes: Son los atributos de CloudEvent, que incluyen el tipo de evento. En este caso, el evento se trata de un mensaje actualizado en el espacio.
data: Son los datos del evento con detalles sobre el recurso spaces.message actualizado, con el formato de una string codificada en Base64.
messageId: Es el identificador del mensaje de Google Cloud Pub/Sub.

Para obtener más información sobre cómo se especifican CloudEvents en los mensajes de Google Cloud Pub/Sub, consulta Vinculación de protocolo de Google Cloud Pub/Sub para CloudEvents.

Suscríbete a eventos de Google Chat
Eventos de ciclo de vida para suscripciones a Google Workspace
Elige los permisos de la API de Google Workspace Events
Crea una suscripción a Google Workspace