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

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

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

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

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

Иллюстрация того, как API Google Workspace Events доставляет события.
Рис. 1. Пример того, как Google Workspace Events API доставляет события в приложение Chat.

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

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

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

Ниже приведен список общих терминов, используемых в API Google Workspace Events:

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

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

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

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

Целевой ресурс
Ресурс Google Workspace, который вы хотите отслеживать. Этот ресурс представлен в поле targetResource подписки Google Workspace. Каждая подписка может отслеживать только один ресурс. Чтобы узнать, какие ресурсы Google Workspace поддерживает API Google Workspace Events, см. раздел Поддерживаемые события Google Workspace .
Типы событий
Типы изменений, о которых вы хотите получать уведомления для целевого ресурса. Например, если вы подписались на пространство Google Chat, вы можете выбрать, получать ли события об этом пространстве и его дочерних ресурсах, таких как членство и сообщения.
Конечная точка уведомления
Конечная точка, откуда подписка Google Workspace получает события. API Google Workspace Events поддерживает темы Google Cloud Pub/Sub в качестве конечной точки уведомлений. Дополнительную информацию об использовании Google Cloud Pub/Sub см. в документации Google Cloud Pub/Sub .
Варианты полезной нагрузки
Данные о событии , которые вы хотите получить об измененных ресурсах.

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

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

Целевой ресурс Поддерживаемые события
Google Чат-группы
  • Сообщения
  • Членство
  • Реакции
  • Космос
Пользователи Google Чата
  • Членство
Площадки для встреч Google Meet
  • Конференции
  • Участники сессий
  • Записи
  • Стенограммы
Пользователи Google Meet
  • Конференции
  • Сессии участников
  • Записи
  • Стенограммы

Чтобы узнать больше, ознакомьтесь со следующими руководствами:

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

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

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

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

Атрибуты CloudEvent

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

Атрибут Описание Пример

datacontenttype

 Тип данных, переданных в событии.

application/json

id

 Идентификатор CloudEvent.

spaces/AAAABBBBBBB/spaceEvents/ABCDEFGHIJKLMNO

source

 Источник события. Для событий Google Workspace это полное имя ресурса подписки. //workspaceevents.googleapis.com/subscriptions/chat-spaces-abcdefg

specversion

 Версия спецификации CloudEvents, используемая для этого события.

1.0

subject

 Ресурс Google Workspace, где произошло событие.

//chat.googleapis.com/spaces/AAAABBBBBBB

time

 Метка времени возникновения события в формате RFC 3339 .

2023-09-07T21:37:36.260127Z

type

 Тип события Google Workspace.

google.workspace.chat.message.v1.created

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

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

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

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

  • Включить данные ресурса. Содержит некоторые или все поля измененного ресурса. Если вы решите включить данные ресурсов, продолжительность вашей подписки будет ограничена 4 часами или 24 часами, если вы используете делегирование на уровне домена .
  • Исключить данные ресурса : содержит только имя измененного ресурса. Срок вашей подписки — до 7 дней. Чтобы получить подробную информацию о событии, вы можете запросить ресурс, используя имя ресурса.

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

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

Подписки на Google Workspace Events API используют темы 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 .