Работа с событиями из 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 в пространство .