Работа с событиями из Google Chat

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

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

Вот несколько примеров того, как можно использовать события:

• Отслеживайте новые сообщения в пространстве и реагируйте на них, например, проверяя наличие ключевых слов или фраз.
• Отправляйте приветственное сообщение пользователям при присоединении к сообществу, чтобы объяснить правила сообщества или поделиться советами по эффективному использованию приложения «Чат».
• Отслеживайте и анализируйте активность в чате. Например, чтобы отправлять ежемесячный отчет о новых участниках или сообщениях, получивших наибольшее количество реакций или ответов.
• Общайтесь между разными платформами обмена сообщениями. Например, пользователи могут отправлять и получать сообщения от пользователей на другой платформе обмена сообщениями, не покидая Chat.

Как проходят мероприятия

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

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

В следующей таблице показано, как действие в чате влияет на связанный ресурс API чата, а также тип события, которое получает ваше приложение чата:

Активность	Ресурс API чата	Тип события
Пользователь отправляет сообщение в чат.	Создан ресурс " Message .	Новое сообщение
Пользователь становится менеджером пространства.	Обновлен раздел «Информация Membership ».	Обновленное членство
Пользователь реагирует на сообщение.	Создан ресурс Reaction .	Новая реакция
Пользователь оставляет пробел.	Ресурс " Membership удален.	Удаленное членство

Получайте события из Google Chat.

Для получения событий ваше приложение «Чат» может выполнять одно из следующих действий:

• Подпишитесь на события, используя API Google Workspace Events, чтобы получать информацию о них по мере их проведения.
• Запрос последних событий осуществляется с помощью API чата.

В таблице ниже объясняется разница и причины для запроса информации или подписки на мероприятия:

	Подпишитесь на мероприятия	Запрос событий
Варианты использования	Обрабатывайте события или реагируйте на них в режиме реального времени. Отслеживайте активность пользователей в сети и находите новые площадки для мониторинга.	Периодически обрабатывать события или реагировать на них с помощью триггера. Получение пропущенных событий из подписки (из-за сбоя или неактивной подписки).
API	API событий Google Workspace	API чата
Источник событий	Пространства, пользователи и организации Google Workspace (предварительная версия для разработчиков science )	Только свободные места
Поддерживаемые мероприятия	Сообщения Членство Реакции Космос Список поддерживаемых типов событий см. в разделе «Типы событий для создания подписок» в документации по API событий Google Workspace.	Сообщения Членство Реакции Космос Список поддерживаемых типов событий см. в ресурсе spaceEvents в справочной документации по API чата.
Формат мероприятия	Сообщение Google Cloud Pub/Sub, отформатированное в соответствии со спецификацией CloudEvent. Подробности см. в разделе «Структура событий Google Workspace» .	Ресурс API чата ( spaces.spaceEvent )
данные о событии	Строка, закодированная в Base64, с данными о ресурсах или без них. Примеры полезной нагрузки см. в разделе «Данные событий» .	JSON-данные, содержащие информацию о ресурсах. Некоторые типы событий содержат только определенные поля ресурсов. Примеры данных см. в справочной документации .

Пример: Запрос или подписка на события, касающиеся членства в определенном пространстве.

В этом примере приложение для чата хочет получать информацию об изменениях в составе участников чат-пространства. В этом пространстве происходит следующая активность пользователей:

• Пользователь присоединяется к пространству, что создает ресурс Membership и запускает событие добавления нового участника.
• Пользователь становится администратором пространства, что обновляет ресурс Membership для этого пользователя и запускает событие обновления членства.
• Если пользователь покидает рабочее пространство, это приводит к удалению ресурса Membership для этого пользователя и запускает событие удаления участника.

Подпишитесь на мероприятия для членов клуба

Для получения событий в режиме реального времени приложение «Чат» вызывает метод subscriptions.create() API событий Google Workspace, чтобы подписаться на все типы событий, связанных с членством в пространстве. После создания подписки приложение «Чат» может начать получать события, связанные с членством.

На рисунке 2 показано, что приложение «Чат» имеет активную подписку на пространство, поэтому приложение получает событие всякий раз, когда изменяется членство в пространстве. Затем приложение «Чат» может обрабатывать или реагировать в режиме реального времени на любые действия, например, отправлять личное приветственное сообщение участнику, присоединившемуся к пространству.

Чтобы узнать о создании подписок с помощью API событий Google Workspace, см. документацию по API событий Google Workspace .

Запрос информации о последних мероприятиях для членов организации.

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

На рисунке 3 показано, как приложение чата вызывает метод spaces.spaceEvents.list() API чата после завершения всех действий, связанных с членством, и фильтрует запрос по новым, обновленным и удаленным событиям членства. API чата возвращает список ресурсов spaceEvent , представляющих каждое изменение членства. Затем приложение чата может обрабатывать данные или отвечать на основе недавней активности, например, отправлять еженедельное сообщение с кратким обзором активности членов пространства за последние 7 дней.

Чтобы запросить события с помощью API чата, см. раздел «Список событий из пространства Google Chat» .

Ограничения и особенности доставки

Общие ограничения

• Чтобы получать события, связанные с членством, пользователь или приложение чата должны быть непосредственными членами пространства. Если пользователь был добавлен, обновлен или удален из пространства косвенно через группу Google, подписка не будет получать эти события. Чтобы понять, как работает членство в группах Google, см. раздел «Добавление группы Google в пространство» .

Подписки пользователей

• Для подписок пользователей события, касающиеся новых участников в личных сообщениях или безымянных групповых чатах ( google.workspace.chat.membership.v1.created ), срабатывают только после отправки первого сообщения.

Подписки для клиентов ( science предварительная версия для разработчиков)

Для клиентских подписок действуют следующие ограничения:

• Организация Google Workspace должна иметь как минимум одну лицензию Enterprise SKU. Обратите внимание, что это требование не является строгим на этапе программы предварительного просмотра для разработчиков, но будет введено в будущем (об этом будет объявлено отдельно).
• Приложение для чата может создать только одну клиентскую подписку для данной организации Google Workspace. В общей сложности организация Google Workspace может иметь до пяти клиентских подписок (созданных разными приложениями для чата).

При оформлении клиентских подписок доставка мероприятий осуществляется в соответствии со следующими общими правилами:

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

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

Пространства, управляемые вашей организацией Google Workspace.

Если в пространстве, управляемом организацией Google Workspace, происходит изменение состава участников, это регистрируется как событие пространства .

Название ресурса космического события имеет следующий формат:

spaces/{spaceId}/spaceEvents/{spaceEventId}

Помещения, находящиеся в управлении сторонних организаций.

Если членство пользователя, управляемого вашей организацией Google Workspace, изменяется в пространстве, управляемом внешней организацией (например, во внешнем именованном пространстве или в личном сообщении, созданном внешним пользователем), ваша подписка получает это событие как событие пользователя .

Имя ресурса пользовательского события имеет следующий формат:

users/{userId}/userEvents/{userEventId}

Связанные темы

• Обзор API событий Google Workspace
• Создать подписку
• Узнайте подробности о мероприятии в Google Chat Space.
• Список событий из пространства Google Чата