Подпишитесь на события с помощью API событий Google Workspace.

На этой странице представлен обзор API событий Google Workspace и объясняется, как использовать API для подписки на события в Google Workspace.

События Google Workspace отражают изменения в ресурсах Google Workspace, например, создание, обновление или удаление ресурсов. Используйте API событий Google Workspace, чтобы подписаться на ресурс Google Workspace и получать соответствующие события.

Как ваше приложение получает события

Чтобы ваше приложение могло получать события Google Workspace, используйте API событий Google Workspace для создания подписок на ресурсы Google Workspace.

В следующем примере описывается, как API событий Google Workspace передает события в приложение чата по подписке:

1. Приложение для чата подписывается на пространство Google Chat.
2. В чате происходят изменения. Например, в чате появляется новое сообщение.
3. Чат отправляет событие в тему в Google Cloud Pub/Sub , которая служит конечной точкой уведомлений для подписки. Событие содержит данные об изменении. Например, для события о новом сообщении оно содержит подробную информацию о созданном ресурсе Message .
4. Приложение «Чат» обрабатывает сообщение Google Cloud Pub/Sub, содержащее событие, и при необходимости выполняет соответствующие действия.

Важная терминология

К числу распространенных терминов, используемых в API событий Google Workspace, относятся:

Мероприятие Google Workspace

Изменение ресурса Google Workspace. События форматируются в соответствии со спецификацией CloudEvents и могут быть либо событием подписки , либо событием жизненного цикла :

Подписка на мероприятие

Изменение ресурса Google Workspace, который вы отслеживаете, например, новое сообщение в чате. Вы можете указать, насколько подробную информацию об измененном ресурсе вы хотите получать. Подробнее см. раздел «Структура событий Google Workspace» .

Событие жизненного цикла

Событие, связанное с вашей подпиской Google Workspace. События жизненного цикла уведомляют вас о проблемах и состоянии вашей подписки, чтобы вы не пропустили события, связанные с подпиской. По умолчанию ваша подписка всегда получает события жизненного цикла. Подробнее см. в разделе «События жизненного цикла для подписок Google Workspace» .

Подписка на Google Workspace

Именованный объект, отслеживающий ресурс из приложения Google Workspace. Подписка представлена ​​ресурсом Subscription . Подписка определяется следующей информацией:

Целевой ресурс

Ресурс Google Workspace, который вы хотите отслеживать. Этот ресурс представлен в поле targetResource подписки Google Workspace. Каждая подписка может отслеживать только один ресурс. Чтобы узнать, какие ресурсы Google Workspace поддерживает API событий Google Workspace, см. раздел «Поддерживаемые события Google Workspace» .

Типы событий

Типы изменений, о которых вы хотите получать уведомления для целевого ресурса. Например, если вы подписаны на чат, вы можете выбрать, получать ли события, касающиеся этого пространства и его дочерних ресурсов, таких как членство и сообщения.

конечная точка уведомления

Конечная точка, куда подписка Google Workspace получает события. API событий Google Workspace поддерживает темы Google Cloud Pub/Sub в качестве конечной точки уведомлений. Чтобы узнать больше об использовании Google Cloud Pub/Sub, см. документацию Google Cloud Pub/Sub .

Варианты полезной нагрузки

Данные о событиях , которые вы хотите получать, касающиеся измененных ресурсов.

Поддерживаемые события Google Workspace

События, которые может получать ваше приложение, зависят от целевого ресурса вашей подписки. В следующей таблице показаны поддерживаемые события для каждого возможного целевого ресурса.

Для получения более подробной информации ознакомьтесь со следующими руководствами:

• Подпишитесь на события в чате
• Подпишитесь на события Drive
• Подпишитесь на мероприятия Meet

Структура событий Google Workspace

События Google Workspace соответствуют спецификации CloudEvents , которая является отраслевым стандартом описания данных событий. События Google Workspace содержат следующее:

• Атрибуты CloudEvent.
• Данные о ресурсе Google Workspace, изменившиеся в результате этого события.

В следующем разделе объясняется структура атрибутов и данных для событий Google Workspace.

атрибуты CloudEvent

События Google Workspace содержат следующие обязательные атрибуты CloudEvents :

данные о событии

Данные события представляют собой полезную нагрузку, отражающую изменение целевого ресурса вашей подписки, включая дочерние ресурсы целевого ресурса. В вашей подписке вы можете указать, хотите ли вы, чтобы полезная нагрузка включала данные об измененном ресурсе или только имя измененного ресурса.

Например, если у вас есть подписка на чат, вы можете получать события о новых сообщениях в этом пространстве. Для событий о новых сообщениях данные события содержат полезную нагрузку с ресурсом Chat spaces.message , который был создан.

При создании подписки вы можете указать, какой объем данных о ресурсах будет включен в события, получаемые вашим приложением.

Эти параметры для данных событий представлены в поле payloadOptions вашей подписки.

События в виде сообщений Google Cloud Pub/Sub

В подписках на API событий Google Workspace используются темы Google Cloud Pub/Sub в качестве конечной точки уведомлений, которая получает события Google Workspace. События кодируются в виде сообщений Google Cloud Pub/Sub. Ваше приложение может обрабатывать сообщения Google Cloud Pub/Sub для выполнения действий или ответа на событие.

В следующем примере показано сообщение Google Cloud Pub/Sub, содержащее событие об обновлении сообщения в чате:

 {
    "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"
    }
}

В этом примере содержатся следующие поля:

• attributes : Атрибуты для объекта CloudEvent , которые включают тип события. В данном случае событие связано с обновлением сообщения в пространстве.
• data : Данные события с подробной информацией об обновленном ресурсе spaces.message , отформатированные как строка, закодированная в Base64.
• messageId : Идентификатор сообщения Google Cloud Pub/Sub.

Чтобы узнать больше о том, как события CloudEvents указываются в сообщениях Google Cloud Pub/Sub, см. раздел «Привязка протокола Google Cloud Pub/Sub для событий CloudEvents» .

Связанные темы

• Выберите области действия API событий Google Workspace.
• Создайте подписку на Google Workspace.