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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Ограничения

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