Как работать с событиями из Google Chat

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

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

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

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

Как работают события

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

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

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

Действия	Ресурс Chat API	Тип события
Пользователь публикует сообщение в чат-группе Chat.	Создается ресурс Message.	Новое сообщение
Пользователь становится менеджером чат-группы.	Ресурс Membership обновлен.	Обновление статуса участника
Пользователь реагирует на сообщение.	Будет создан ресурс Reaction.	Новая реакция
Пользователь покидает чат-группу.	Удален ресурс Membership.	Удаленное членство

Получение событий из Google Chat

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

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

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

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

Пример: запрос или подписка на события, связанные с участниками чат-группы

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

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

Подписка на события, связанные с участием

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

На рисунке 2 у приложения Chat есть активная подписка на чат-группу, поэтому оно получает событие каждый раз, когда меняется состав участников чат-группы. Приложение Chat может обрабатывать эти действия или реагировать на них в режиме реального времени, например отправлять личное приветственное сообщение пользователю, который присоединился к чат-группе.

Информацию о создании подписок с помощью Google Workspace Events API можно найти в документации по Google Workspace Events API.

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

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

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

Чтобы запросить события с помощью Chat API, ознакомьтесь со статьей Как получить список событий из чат-группы Google Chat.

Ограничения и особенности показа

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

• Чтобы получать события, связанные с участниками, пользователь или приложение Chat должны быть непосредственными участниками чат-группы. Если они были добавлены, обновлены или удалены косвенно через группу Google, подписка не получает эти события. Чтобы узнать, как работает участие в группах Google, прочитайте статью Как добавить в чат-группу группу Google.

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

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

Подписки клиентов

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

• В организации Google Workspace должна быть хотя бы одна лицензия Enterprise.
• Приложение Chat может создать только одну подписку клиента для определенной организации Google Workspace. У организации Google Workspace может быть не более пяти подписок клиентов (созданных разными приложениями Chat).

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

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

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

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

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

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

spaces/{spaceId}/spaceEvents/{spaceEventId}

Чат-группы, управляемые внешними организациями

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

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

users/{userId}/userEvents/{userEventId}

Статьи по теме

• Обзор Google Workspace Events API
• Как создать подписку
• Как получить сведения о событии чат-группы Google Chat
• Как получить список событий из чат-группы Google Chat