Как подключить приложение Chat к другим сервисам и инструментам

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

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

1. Определять, когда требуется авторизация или конфигурация.
2. Возвращает базовую карточку авторизации, которая предлагает пользователю войти в аккаунт или настроить сервис.
3. Перенаправьте на URI завершения, чтобы Google Chat автоматически повторил исходное взаимодействие после того, как пользователь завершит авторизацию.

Требования

HTTP

Приложение Google Chat, которое получает и обрабатывает действия пользователей. Чтобы создать его, выполните краткое руководство по HTTP.

Примечание. Примеры кода в этом руководстве написаны для запуска в качестве функции Google Cloud Run для Node.js.

Apps Script

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

определять, что требуется авторизация;

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

• Токен доступа для подключения к стороннему сервису ещё не создан или срок его действия истек.
• Токен доступа не распространяется на запрошенный ресурс.
• Токен доступа не охватывает области действия, необходимые для запроса.

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

Если вы создаете скрипт в Google Apps Script, вы можете использовать библиотеку OAuth2 для Google Apps Script (или версию OAuth1), в которой функция hasAccess проверяет, разрешил ли пользователь доступ к сервису. Если вы используете запросы UrlFetchApp.fetch, то можете задать для параметра muteHttpExceptions значение true, чтобы проверить код ответа и контент в возвращенном объекте HttpResponse.

Запрашивать у пользователей базовую авторизацию с помощью карточки

Если приложение Chat обнаруживает, что требуется авторизация или настройка, верните ответ AuthorizationError, чтобы показать пользователю частную карточку базовой авторизации.

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

На изображении ниже показана стандартная карта авторизации Google.

Рисунок 1. Основной запрос на авторизацию для аккаунта Example Account. В запросе говорится, что приложение Chat хочет показывать дополнительную информацию, но для этого ему нужен доступ к аккаунту пользователя.

Чтобы показать пользователям базовую карту авторизации, верните объект AuthorizationError:

HTTP

Верните следующий ответ JSON:

{
  "basic_authorization_prompt": {
    "authorization_url": "<var>AUTHORIZATION_URL</var>",
    "resource": "<var>RESOURCE_DISPLAY_NAME</var>"
  }
}

Apps Script

CardService.newAuthorizationException()
    .setAuthorizationUrl('<var>AUTHORIZATION_URL</var>')
    .setResourceDisplayName('<var>RESOURCE_DISPLAY_NAME</var>')
    .throwException();

Замените следующее:

• AUTHORIZATION_URL – URL-адрес HTTPS веб-приложения, которое обрабатывает аутентификацию, авторизацию или конфигурацию.
• RESOURCE_DISPLAY_NAME – отображаемое название защищенного ресурса или сервиса. Это название показывается пользователю в запросе авторизации. Например, если ваш RESOURCE_DISPLAY_NAME – Example Account, в запросе будет указано, что приложению требуется разрешение на доступ к вашему Example Account.

Завершите запрос на настройку

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

При срабатывании этих триггеров приложение Chat получает URI перенаправления для завершения (configCompleteRedirectUri / completeRedirectUri) в полезной нагрузке события:

• Сообщение: chat.messagePayload.configCompleteRedirectUri
• Добавлено в чат-группу: chat.addedToSpacePayload.configCompleteRedirectUri
• Команда приложения: chat.appCommandPayload.configCompleteRedirectUri

Вы должны закодировать этот URI переадресации в <var>AUTHORIZATION_URL</var> и перенаправить на него браузер пользователя после завершения процесса авторизации. Перенаправление на этот URL означает, что запрос на авторизацию или конфигурацию выполнен.

Когда пользователь будет успешно перенаправлен на URI перенаправления для завершения, указанный в исходной полезной нагрузке события, Google Chat выполнит следующие действия:

1. Удаляет запрос на частную авторизацию, показанный пользователю, который инициировал сеанс.
2. Преобразует исходное сообщение в общедоступное, чтобы его могли видеть другие участники группы.
3. Отправляет исходный объект события в приложение Chat во второй раз.

Если вы не перенаправите пользователя на URI перенаправления для завершения, он сможет завершить процесс авторизации, но Google Chat не будет автоматически повторять предыдущее выполнение, и пользователю придется вручную снова вызвать ваше приложение Chat.

Переход по URI переадресации после завершения влияет только на одно взаимодействие с пользователем. Если пользователь несколько раз отправлял сообщения в приложение Chat и получил несколько запросов, то после аутентификации и настройки по одному из запросов будет повторена только эта конкретная операция.

Как аутентифицировать пользователя Chat вне Chat

При переходе по URL за пределы Chat (например, при обратном вызове OAuth) часто требуется сопоставить внешний сеанс с идентификатором пользователя в Chat. Мы рекомендуем защитить целевое веб-приложение с помощью входа с аккаунтом Google.

Используйте токен идентификации, выданный при входе в аккаунт, чтобы получить идентификатор пользователя. Заявление sub содержит уникальный идентификатор пользователя Google и может быть сопоставлено с названием ресурса пользователя (chat.user.name) из Google Chat.

Внимание! Всегда проверяйте целостность токена, прежде чем принимать заявленный идентификатор пользователя.

Чтобы связать утверждение sub с названием ресурса users/{user} в Google Chat, добавьте к значению утверждения sub префикс users/. Например, значение утверждения sub, равное 123, соответствует параметру users/123 в объектах событий, отправляемых в ваше приложение Chat.

Примеры кода

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

Node.js

Посмотреть на GitHub

Python

Посмотреть на GitHub

Java

Посмотреть на GitHub

Apps Script

Посмотреть на GitHub

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

• Как получать и обрабатывать действия пользователей
• Как настроить аутентификацию и авторизацию для приложений Google Chat и запросов API Google Chat
• Как подключить дополнение Google Workspace к стороннему сервису

Приложения Chat, не являющиеся дополнениями: подключение приложения Chat к другим сервисам и инструментам

Если вы поддерживаете приложение Chat, которое не является дополнением Google Workspace, ваше приложение Chat запрашивает конфигурацию с помощью actionResponse типа REQUEST_CONFIG и считывает configCompleteRedirectUrl из объекта Event верхнего уровня.

Чтобы преобразовать приложение Chat, которое не является дополнением, в дополнение Google Workspace, ознакомьтесь со статьей Как преобразовать приложение Google Chat в дополнение Google Workspace.

Как запросить конфигурацию у пользователя в приложении Chat, которое не является дополнением

В приложении Chat, которое не является дополнением, верните пользователю URL конфигурации в следующем формате:

{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "CONFIGURATION_URL"
  }
}

Это указывает Google Chat на то, что пользователю нужно показать личный запрос, где CONFIGURATION_URL – это ссылка, по которой пользователь может перейти для дополнительной аутентификации, авторизации или настройки. Ответ REQUEST_CONFIG не может быть отправлен вместе с обычным ответом. Любой текст, карточки и другие атрибуты будут проигнорированы.

Завершите запрос на настройку в приложении Chat, которое не является дополнением

Каждое взаимодействие MESSAGE, ADDED_TO_SPACE и APP_COMMANDEvent, которое получает приложение Chat, не являющееся дополнением, включает поле верхнего уровня configCompleteRedirectUrl. Закодируйте этот URL в URL конфигурации и перенаправьте на него пользователя после завершения, чтобы Google Chat удалил запрос, сделал исходное сообщение общедоступным и повторно отправил исходное событие взаимодействия в ваше приложение Chat.

Примеры реализации можно найти на GitHub: образец приложения для подключения на Node.js и образец приложения для аутентификации MyProfile на Python.