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

Типы событий

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

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

Конечная точка, куда подписка 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 :

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

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

Например, если у вас есть подписка на чат-пространство, вы можете получать события о новых сообщениях в нём. Данные о событиях содержат полезную нагрузку с созданным ресурсом 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