Создайте HTTP-приложение Google Chat.

На этой странице объясняется, как создать дополнение Google Workspace, работающее в Google Chat, используя службу HTTP.

В этом кратком руководстве показано, как создать HTTP-сервис с использованием сервисов Google Cloud. Для создания приложения Chat необходимо написать и развернуть функцию Cloud Run , которую приложение Chat будет использовать для ответа на сообщение пользователя.

При использовании архитектуры HTTP вы настраиваете Chat для интеграции с Google Cloud или локальным сервером с помощью HTTP, как показано на следующей схеме:

Архитектура приложения чата, использующего веб-сервис на локальном сервере.

На предыдущей диаграмме пользователь, взаимодействующий с приложением HTTP-чата, имеет следующий поток информации:

  1. Пользователь отправляет сообщение в чате в приложение чата, либо в личном сообщении, либо в чат-пространстве.
  2. HTTP-запрос отправляется на веб-сервер, который представляет собой либо облачную, либо локальную систему, содержащую логику приложения чата.
  3. При желании логику приложения Chat можно интегрировать с сервисами Google Workspace (например, Календарь и Таблицы), другими сервисами Google (например, Карты, YouTube и Vertex AI) или другими веб-сервисами (например, системой управления проектами или инструментом тикетов).
  4. Веб-сервер отправляет HTTP-ответ обратно в службу приложения Chat.
  5. Ответ доставляется пользователю.
  6. При желании приложение чата может вызывать API чата для асинхронной публикации сообщений или выполнения других операций.

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

Цели

  • Настройте свою среду.
  • Создайте и разверните функцию Cloud Run.
  • Настройте дополнение Google Workspace для приложения Chat.
  • Протестируйте приложение.

Предпосылки

Настройте среду

Перед использованием API Google необходимо включить их в проекте Google Cloud. Вы можете включить один или несколько API в одном проекте Google Cloud.

  • В консоли Google Cloud включите Cloud Build API, Cloud Functions API, Cloud Pub/Sub API, Cloud Logging API, Artifact Registry API и Cloud Run API.

    Включить API

Создание и развертывание функции Cloud Run

Создайте и разверните функцию Cloud Run, которая генерирует карточку чата с отображаемым именем и аватаром отправителя. Когда приложение Chat получает сообщение, оно запускает функцию и отвечает карточкой.

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

Node.js

  1. В консоли Google Cloud перейдите на страницу Cloud Run:

    Перейти к Cloud Run

    Убедитесь, что выбран проект для вашего приложения чата.

  2. Нажмите «Написать функцию» .

  3. На странице «Создать услугу» настройте свою функцию:

    1. В поле Имя службы введите addonchatapp .
    2. В списке Регион выберите регион.
    3. В списке Runtime выберите самую последнюю версию Node.js.
    4. В разделе Аутентификация выберите Требовать аутентификацию .
    5. Нажмите «Создать» и дождитесь, пока Cloud Run создаст службу. Консоль перенаправит вас на вкладку «Источник» .

  4. На вкладке «Источник» :

    1. В поле «Точка входа» удалите текст по умолчанию и введите avatarApp .
    2. Замените содержимое index.js следующим кодом: 
    /**  * Google Cloud Run function that responds to messages sent from a  * Google Chat space.  *  * @param {Object} req Request sent from Google Chat space  * @param {Object} res Response to send back  */ import { http } from '@google-cloud/functions-framework';  http('avatarApp', (req, res) => {     if (req.method === 'GET' || !req.body.chat) {         return res.send('Hello! This function is meant to be used ' +             'in a Google Chat Space.');     }      // Stores the Google Chat event as a variable.     const chatMessage = req.body.chat.messagePayload.message;      // Replies with the sender's avatar in a card.     const displayName = chatMessage.sender.displayName;     const avatarUrl = chatMessage.sender.avatarUrl;     res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {         text: 'Here\'s your avatar',         cardsV2: [{             cardId: 'avatarCard',             card: {                 name: 'Avatar Card',                 header: {                     title: `Hello ${displayName}!`,                 },                 sections: [{                     widgets: [{                         textParagraph: { text: 'Your avatar picture: ' }                     }, {                         image: { imageUrl: avatarUrl }                     }]                 }]             }         }]     }}}}}); });
    1. Замените содержимое package.json следующим кодом: 
    {   "name": "avatar-app",   "version": "1.0.0",   "description": "Google Chat Avatar App",   "main": "index.js",   "type": "module",   "scripts": {     "start": "node index.js"   },   "dependencies": {     "@google-cloud/functions-framework": "^3.0.0"   } }
    1. Нажмите «Сохранить и повторно развернуть» .

Питон

  1. В консоли Google Cloud перейдите на страницу Cloud Run:

    Перейти к Cloud Run

    Убедитесь, что выбран проект для вашего приложения чата.

  2. Нажмите «Написать функцию» .

  3. На странице «Создать услугу» настройте свою функцию:

    1. В поле Имя службы введите addonchatapp .
    2. В списке Регион выберите регион.
    3. В списке Runtime выберите самую последнюю версию Python.
    4. В разделе Аутентификация выберите Требовать аутентификацию .
    5. Нажмите «Создать» и дождитесь, пока Cloud Run создаст службу. Консоль перенаправит вас на вкладку «Источник» .

  4. На вкладке «Источник» :

    1. В поле «Точка входа» удалите текст по умолчанию и введите avatar_app .
    2. Замените содержимое main.py следующим кодом: 
    from typing import Any, Mapping  import flask import functions_framework  @functions_framework.http def avatar_app(req: flask.Request) -> Mapping[str, Any]:     """Google Cloud Run Function that handles requests from Google Chat      Args:         flask.Request: the request      Returns:         Mapping[str, Any]: the response     """     if req.method == "GET":         return "Hello! This function must be called from Google Chat."      request_json = req.get_json(silent=True)      # Stores the Google Chat event as a variable.     chat_message = request_json["chat"]["messagePayload"]["message"]      # Replies with the sender's avatar in a card.     display_name = chat_message["sender"]["displayName"]     avatar_url = chat_message["sender"]["avatarUrl"]     return { "hostAppDataAction": { "chatDataAction": { "createMessageAction": { "message": {         "text": "Here's your avatar",         "cardsV2": [{             "cardId": "avatarCard",             "card": {                 "name": "Avatar Card",                 "header": { "title": f"Hello {display_name}!" },                 "sections": [{                     "widgets": [{                         "textParagraph": { "text": "Your avatar picture:" }                     }, {                         "image": { "imageUrl": avatar_url }                     }]                 }]             }         }]     }}}}}
    1. Нажмите «Сохранить и повторно развернуть» .

Ява

  1. В консоли Google Cloud перейдите на страницу Cloud Run:

    Перейти к Cloud Run

    Убедитесь, что выбран проект для вашего приложения чата.

  2. Нажмите «Написать функцию» .

  3. На странице «Создать услугу» настройте свою функцию:

    1. В поле Имя службы введите addonchatapp .
    2. В списке Регион выберите регион.
    3. В списке Runtime выберите самую последнюю версию Java.
    4. В разделе Аутентификация выберите Требовать аутентификацию .
    5. Нажмите «Создать» и дождитесь, пока Cloud Run создаст службу. Консоль перенаправит вас на вкладку «Источник» .

  4. На вкладке «Источник» :

    1. В поле «Точка входа» удалите текст по умолчанию и введите AvatarApp .
    2. Переименуйте файл Java по умолчанию в src/main/java/gcfv2/AvatarApp.java .
    3. Замените содержимое AvatarApp.java следующим кодом: 
    import java.util.List;  import com.google.api.services.chat.v1.model.CardWithId; import com.google.api.services.chat.v1.model.GoogleAppsCardV1Card; import com.google.api.services.chat.v1.model.GoogleAppsCardV1CardHeader; import com.google.api.services.chat.v1.model.GoogleAppsCardV1Image; import com.google.api.services.chat.v1.model.GoogleAppsCardV1Section; import com.google.api.services.chat.v1.model.GoogleAppsCardV1TextParagraph; import com.google.api.services.chat.v1.model.GoogleAppsCardV1Widget; import com.google.api.services.chat.v1.model.Message; import com.google.cloud.functions.HttpFunction; import com.google.cloud.functions.HttpRequest; import com.google.cloud.functions.HttpResponse; import com.google.gson.Gson; import com.google.gson.JsonObject;  public class AvatarApp implements HttpFunction {     private static final Gson gson = new Gson();      @Override     public void service(HttpRequest request, HttpResponse response) throws Exception {         JsonObject body = gson.fromJson(request.getReader(), JsonObject.class);         if (request.getMethod().equals("GET") || !body.has("chat")) {             response.getWriter().write("Hello! This function is meant to be used " +                 "in a Google Chat Space..");             return;         }          // Stores the Google Chat event as a variable.         JsonObject chatMessage = body.getAsJsonObject("chat")             .getAsJsonObject("messagePayload").getAsJsonObject("message");          // Replies with the sender's avatar in a card.         String displayName = chatMessage.getAsJsonObject("sender").get("displayName").getAsString();         String avatarUrl = chatMessage.getAsJsonObject("sender").get("avatarUrl").getAsString();         Message message = createMessage(displayName, avatarUrl);          JsonObject createMessageAction = new JsonObject();         createMessageAction.add("message", gson.fromJson(gson.toJson(message), JsonObject.class));          JsonObject chatDataAction = new JsonObject();         chatDataAction.add("createMessageAction", createMessageAction);          JsonObject hostAppDataAction = new JsonObject();         hostAppDataAction.add("chatDataAction", chatDataAction);          JsonObject dataActions = new JsonObject();         dataActions.add("hostAppDataAction", hostAppDataAction);         response.getWriter().write(gson.toJson(dataActions));     }      Message createMessage(String displayName, String avatarUrl) {         GoogleAppsCardV1CardHeader cardHeader = new GoogleAppsCardV1CardHeader();         cardHeader.setTitle(String.format("Hello %s!", displayName));          GoogleAppsCardV1TextParagraph textParagraph = new GoogleAppsCardV1TextParagraph();         textParagraph.setText("Your avatar picture: ");          GoogleAppsCardV1Widget avatarWidget = new GoogleAppsCardV1Widget();         avatarWidget.setTextParagraph(textParagraph);          GoogleAppsCardV1Image image = new GoogleAppsCardV1Image();         image.setImageUrl(avatarUrl);          GoogleAppsCardV1Widget avatarImageWidget = new GoogleAppsCardV1Widget();         avatarImageWidget.setImage(image);          GoogleAppsCardV1Section section = new GoogleAppsCardV1Section();         section.setWidgets(List.of(avatarWidget, avatarImageWidget));          GoogleAppsCardV1Card card = new GoogleAppsCardV1Card();         card.setName("Avatar Card");         card.setHeader(cardHeader);         card.setSections(List.of(section));          CardWithId cardWithId = new CardWithId();         cardWithId.setCardId("avatarCard");         cardWithId.setCard(card);          Message message = new Message();         message.setText("Here's your avatar");         message.setCardsV2(List.of(cardWithId));          return message;     } }

  5. Замените содержимое pom.xml следующим кодом:

    <project xmlns="http://maven.apache.org/POM/4.0.0"  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">     <modelVersion>4.0.0</modelVersion>      <groupId>com.google.chat</groupId>     <artifactId>avatar-app</artifactId>     <version>1.0-SNAPSHOT</version>      <properties>         <maven.compiler.target>17</maven.compiler.target>         <maven.compiler.source>17</maven.compiler.source>     </properties>      <dependencies>         <dependency>         <groupId>com.google.cloud.functions</groupId>         <artifactId>functions-framework-api</artifactId>         <version>1.0.4</version>         </dependency>          <!-- https://mvnrepository.com/artifact/com.google.code.gson/gson -->         <dependency>             <groupId>com.google.code.gson</groupId>             <artifactId>gson</artifactId>             <version>2.9.1</version>         </dependency>          <!-- https://mvnrepository.com/artifact/com.google.apis/google-api-services-chat -->         <dependency>             <groupId>com.google.apis</groupId>             <artifactId>google-api-services-chat</artifactId>             <version>v1-rev20230115-2.0.0</version>         </dependency>     </dependencies>      <!-- Required for Java functions in the inline editor -->     <build>         <plugins>         <plugin>             <groupId>org.apache.maven.plugins</groupId>             <artifactId>maven-compiler-plugin</artifactId>             <version>3.8.1</version>             <configuration>             <excludes>                 <exclude>.google/</exclude>             </excludes>             </configuration>         </plugin>         </plugins>     </build> </project>
    1. Нажмите «Сохранить и повторно развернуть» .

Откроется страница с подробной информацией о сервисе Cloud Run. Дождитесь развертывания функции.

Настройте дополнение

После развертывания функции Cloud Run выполните следующие действия для создания надстройки и развертывания приложения Google Chat:

  1. В консоли Google Cloud перейдите на страницу Cloud Run:

    Перейти к Cloud Run

    Убедитесь, что выбран проект, для которого вы включили Cloud Run.

  2. В списке функций нажмите addonchatapp .

  3. На странице сведений о сервисе скопируйте URL-адрес функции. URL заканчивается на run.app .

  4. В поле поиска Google Cloud найдите «Google Chat API», затем нажмите Google Chat API и нажмите Управление .

    Перейти к API чата

  5. Нажмите «Конфигурация» и настройте приложение Google Chat:

    1. В поле «Имя приложения» введите Add-on Chat app .
    2. В поле URL-адрес аватара введите https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png .
    3. В поле Описание введите Add-on Chat app .
    4. В разделе «Функциональность» выберите Присоединяйтесь к пространствам и групповым беседам .
    5. В разделе «Параметры подключения» выберите URL-адрес конечной точки HTTP .
    6. Скопируйте адрес электронной почты учётной записи сервиса . Этот адрес электронной почты понадобится вам при авторизации дополнения для вызова вашей функции.
    7. В разделе Триггеры выберите Использовать общий URL-адрес конечной точки HTTP для всех триггеров и вставьте URL-адрес триггера функции Cloud Run в поле.
    8. В разделе «Видимость» выберите «Сделать это приложение Google Chat доступным для определенных людей и групп в вашем домене» и введите свой адрес электронной почты.
    9. В разделе Журналы выберите Записывать ошибки в Журнал .

  6. Нажмите «Сохранить» .

Затем разрешите приложению Chat вызывать функцию Cloud Run.

Разрешите Google Chat вызывать вашу функцию

Чтобы разрешить надстройке Google Workspace вызывать вашу функцию, добавьте учетную запись службы надстройки Google Workspace с ролью Cloud Run Service Invoker .

  1. В консоли Google Cloud перейдите на страницу Cloud Run:

    Перейти к Cloud Run

  2. В списке служб Cloud Run установите флажок рядом с функцией получения. (Не нажимайте на саму функцию.)

  3. Нажмите «Разрешения» . Откроется панель «Разрешения» .

  4. Нажмите Добавить принципала .

  5. В поле Новые участники введите адрес электронной почты учетной записи службы надстройки Google Workspace, связанной с вашим приложением Chat.

    Адрес электронной почты учетной записи службы находится на странице конфигурации API чата в разделе Параметры подключения > URL-адрес конечной точки HTTP > Электронная почта учетной записи службы :

    Перейти к настройке API чата

  6. В разделе Выбор роли выберите Cloud Run > Cloud Run Service Invoker .

  7. Нажмите «Сохранить» .

Приложение Chat готово принимать и отвечать на сообщения в Chat.

Протестируйте свое приложение чата

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

  1. Откройте Google Chat, используя учетную запись Google Workspace, которую вы указали при добавлении себя в качестве доверенного тестировщика.

    Перейти в Google Чат

  2. Нажмите новый чат» .
  3. В поле Добавить 1 или более человек введите название вашего чат-приложения.

  4. Выберите приложение чата из результатов. Откроется личное сообщение.

  5. В новом прямом сообщении с приложением введите Hello и нажмите enter .

Сообщение приложения «Чат» содержит карточку, на которой отображается имя отправителя и его аватар, как показано на следующем изображении:

Приложение чата отвечает карточкой с отображаемым именем и аватаром отправителя. Изображение

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

Устранение неполадок

Когда приложение или карточка Google Chat возвращает ошибку, в интерфейсе Chat отображается сообщение «Что-то пошло не так» или «Не удалось обработать ваш запрос». Иногда в интерфейсе Chat не отображается сообщение об ошибке, но приложение или карточка Chat выдаёт неожиданный результат; например, сообщение может не появиться.

Хотя сообщение об ошибке может не отображаться в пользовательском интерфейсе чата, при включенном ведении журнала ошибок для приложений чата доступны описательные сообщения об ошибках и данные журнала, которые помогут вам исправить ошибки. Сведения о просмотре, отладке и исправлении ошибок см. в статье «Устранение неполадок и исправление ошибок Google Chat» .

Уборка

Чтобы избежать списания средств с вашего аккаунта Google Cloud за ресурсы, используемые в этом руководстве, мы рекомендуем вам удалить проект Cloud.

  1. В консоли Google Cloud перейдите на страницу «Управление ресурсами» . Выберите « Меню > «IAM и администрирование» > «Управление ресурсами» .

    Перейти к диспетчеру ресурсов

  2. В списке проектов выберите проект .
  3. В диалоговом окне введите идентификатор проекта, а затем нажмите кнопку «Завершить» , чтобы удалить проект.