Подпишитесь на события с помощью 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 доставляет события в приложение Google Chat через подписку:

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

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

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

Событие Google Workspace

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

Событие подписки

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

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

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

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

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

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

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

Типы событий

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

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

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

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

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

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

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

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

• Подпишитесь на события Google Chat
• Подпишитесь на события Google Диска
• Подпишитесь на мероприятия Google Meet

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

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

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

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

Атрибуты CloudEvent

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

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

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

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

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

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

Эти параметры данных о событиях представлены в поле 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 Events
• Создайте подписку Google Workspace