На этой странице представлен обзор API событий Google Workspace и объясняется, как использовать API для подписки на события в Google Workspace.
События Google Workspace представляют собой изменения в ресурсах Google Workspace, например, когда ресурсы создаются, обновляются или удаляются. Ваше приложение может подписаться на ресурс Google Workspace, чтобы вы получали соответствующие события, которые вас интересуют.
Как ваше приложение получает события
Чтобы ваше приложение могло получать события Google Workspace, вы используете API событий Google Workspace для создания подписок на ресурсы Google Workspace.
Вот как API Google Workspace Events доставляет события в ваше приложение через подписку:
- Ваше приложение подписывается на ресурс в приложении Google Workspace, например на пространство Google Chat.
- Ресурс, на который вы подписаны, изменится.
- Приложение Google Workspace передает событие в тему в Google Cloud Pub/Sub , которая служит конечной точкой уведомления для вашей подписки на Google Workspace. Событие содержит данные о том, что изменилось в ресурсе.
- Ваше приложение обрабатывает сообщение 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 Чат-группы | //chat.googleapis.com/spaces/ SPACE_ID |
Подробную информацию см. в разделе «Подписка на события Google Chat» . | Пользователь Google Chat, который авторизует подписку, должен быть участником пространства через свою Google Workspace или учетную запись Google. | |
| Пользователи Google Чата | //cloudidentity.googleapis.com/users/ USER_ID |
Подробную информацию см. в разделе «Подписка на события Google Chat» . | Подписка получает только события о пользователе, который авторизовал подписку. Пользователь не может авторизовать подписку от имени других пользователей. | |
| Google Встреча | ||||
| Помещения для встреч Google Meet | //meet.googleapis.com/spaces/ SPACE_ID |
Подробную информацию см. в разделе «Подписка на мероприятия Google Meet» . | ||
| Пользователи Google Meet | //cloudidentity.googleapis.com/users/ USER_ID |
Подробную информацию см. в разделе «Подписка на мероприятия Google Meet» . | Подписка получает события о пространствах для собраний, где пользователь является одним из следующих:
| |
Структура событий Google Workspace
События Google Workspace соответствуют спецификации CloudEvents , которая является стандартным способом описания данных о событиях. События Google Workspace содержат следующее:
В следующем разделе объясняется структура атрибутов и данных событий Google Workspace.
Атрибуты CloudEvent
События Google Workspace содержат следующие обязательные атрибуты CloudEvents :
| Атрибут | Описание | Пример |
|---|---|---|
| Тип данных, переданных в событии. | |
| Идентификатор CloudEvent. | |
| Источник события. Для событий Google Workspace это полное имя ресурса подписки. | //workspaceevents.googleapis.com/subscriptions/chat-spaces-abcdefg |
| Версия спецификации CloudEvents, используемая для этого события. | |
| Ресурс Google Workspace, где произошло событие. | |
| Метка времени возникновения события в формате RFC 3339 . | |
| Тип события Google Workspace. | |
Данные о событии
Данные о событиях — это полезная нагрузка, которая представляет собой изменение целевого ресурса вашей подписки, включая дочерние ресурсы целевого ресурса. В своей подписке вы можете указать, хотите ли вы, чтобы полезные данные включали данные об измененном ресурсе или только имя измененного ресурса.
Например, если у вас есть подписка на чат-группу, вы можете получать события о новых сообщениях в этой чат-группе. Для событий о новых сообщениях данные событий содержат полезную нагрузку с созданным ресурсом 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 .