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 cuándo se crean, se actualizan o se borran recursos. Tu app puede suscribirse a un recurso de Google Workspace para que recibas eventos relevantes que te interesan.

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 muestra cómo la API de Google Workspace Events entrega eventos a una app de Google Chat a través de una suscripción:

1. Una app de Chat se suscribe a un espacio de Chat.
2. El espacio de Chat cambia. Por ejemplo, se publica un mensaje nuevo en el espacio.
3. Chat entrega un evento a un tema en Cloud Pub/Sub de Google Cloud, 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 Message que se crea.
4. 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

A continuación, se muestra 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 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 estás supervisando, como un mensaje nuevo en un espacio de Google Chat. Puedes especificar la cantidad de detalles que deseas recibir sobre el recurso que cambió. Para obtener más información, 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 los problemas y el estado de tu suscripción para que puedas evitar perder eventos de suscripción. De forma predeterminada, tu suscripción siempre recibe eventos del ciclo de vida. Para obtener más información, consulta Eventos de ciclo de vida de las suscripciones a Google Workspace.

Suscripción a Google Workspace

Es una entidad denominada 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 deseas 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

Son los tipos de cambios sobre los que quieres 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 notificación

Es 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 un 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 del evento que deseas recibir sobre los recursos modificados.

Eventos de Google Workspace admitidos

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

Para obtener más información, consulta las siguientes guías:

• Cómo suscribirse a eventos de Google Chat
• Cómo suscribirte a eventos de Google Meet

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 del 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 de CloudEvents obligatorios:

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. En el caso de los eventos sobre mensajes nuevos, los datos del evento 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:

• Incluir datos de recursos: Contiene algunos o todos los campos del recurso modificado. Si eliges incluir datos de recursos, la duración de tu suscripción se limita a 4 horas o a 24 horas si usas la delegación a nivel del dominio.
• Excluir datos de recursos: Solo contiene 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 para los 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 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"
    }
}

Ten en cuenta los siguientes campos:

• attributes: Atributos para el CloudEvent, que incluyen el tipo de evento. En este caso, el evento se relaciona con un mensaje actualizado en el espacio.
• data: Los datos del evento con detalles sobre el recurso spaces.message actualizado, con formato de cadena 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 los CloudEvents en los mensajes de Google Cloud Pub/Sub, consulta Vinculación de protocolos de Google Cloud Pub/Sub para CloudEvents.

Temas relacionados

• Cómo suscribirse a eventos de Google Chat
• Cómo suscribirte a eventos de Google Meet
• Eventos del ciclo de vida para las suscripciones a Google Workspace
• Elige los permisos de la API de Google Workspace Events
• Cómo crear una suscripción a Google Workspace