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

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

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

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

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

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

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

Пример того, как сообщение, опубликованное в чате Google, запускает событие.
Рисунок 1. Пользователь публикует сообщение в чате, что создаёт ресурс Message . Затем чат создаёт событие, содержащее данные о новом сообщении.

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

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

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

Получать события из Google Chat

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

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

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

Подписаться на события Запрос событий
Варианты использования
  • Обрабатывайте события или реагируйте на них в режиме реального времени.
  • Контролируйте активность пользователей и открывайте для себя новые пространства для мониторинга.
  • Обрабатывайте события или реагируйте на них периодически или посредством триггера.
  • Извлечение пропущенных событий из подписки (из-за сбоя или неактивности подписки).
API API событий Google Workspace API чата
Источник событий Пространства и пользователи Только пробелы
Поддерживаемые события
  • Сообщения
  • Членство
  • Реакции
  • Космос

Список поддерживаемых типов событий см. в разделе Типы событий для создания подписок в документации API событий Google Workspace.
  • Сообщения
  • Членство
  • Реакции
  • Космос

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

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

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

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

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

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

Приложение чата, которое подписывается на события с помощью API событий Google Workspace.
Рисунок 2. Приложение чата получает события членства через подписку с использованием API Google Workspace Events.

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

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

Запрос о недавних событиях членства

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

Приложение чата, которое запрашивает события, используя API чата.
Рисунок 3. Приложение Chat получает последние события членства, отправляя запросы на события пространства с помощью API Chat.

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

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

Ограничения

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