Подпишитесь на события с помощью 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. Приложение «Чат» обрабатывает сообщение Google Cloud Pub/Sub, содержащее событие, и при необходимости выполняет соответствующие действия.

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

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

Мероприятие 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 Drive
• Подпишитесь на мероприятия Google 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.