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

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

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

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

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

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

  1. Пользователь отправляет сообщение в чате в приложение чата, либо в личном сообщении, либо в чат-пространстве.
  2. HTTP-запрос отправляется на веб-сервер, который представляет собой либо облачную, либо локальную систему, содержащую логику приложения чата.
  3. При желании логика приложения «Чат» может интегрироваться с сервисами 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, которая генерирует карточку чата с отображаемым именем отправителя и изображением аватара. Когда приложение чата получает сообщение, оно запускает функцию и отвечает карточкой.

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

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 следующим кодом:
    node/chat/avatar-app/index.js
    import { http } from '@google-cloud/functions-framework';
    
    // The ID of the slash command "/about".
    // You must use the same ID in the Google Chat API configuration.
    const ABOUT_COMMAND_ID = 1;
    
    /**
     * Handle requests from Google Workspace add on
     *
     * @param {Object} req Request sent by Google Chat
     * @param {Object} res Response to be sent back to Google Chat
     */
    http('avatarApp', (req, res) => {
      const chatEvent = req.body.chat;
      let message;
      if (chatEvent.appCommandPayload) {
        message = handleAppCommand(chatEvent);
      } else {
        message = handleMessage(chatEvent);
      }
      res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: {
        message: message
      }}}});
    });
    
    /**
     * Responds to an APP_COMMAND event in Google Chat.
     *
     * @param {Object} event the event object from Google Chat
     * @return the response message object.
     */
    function handleAppCommand(event) {
      switch (event.appCommandPayload.appCommandMetadata.appCommandId) {
        case ABOUT_COMMAND_ID:
          return {
            text: 'The Avatar app replies to Google Chat messages.'
          };
      }
    }
    
    /**
     * Responds to a MESSAGE event in Google Chat.
     *
     * @param {Object} event the event object from Google Chat
     * @return the response message object.
     */
    function handleMessage(event) {
      // Stores the Google Chat user as a variable.
      const chatUser = event.messagePayload.message.sender;
      const displayName = chatUser.displayName;
      const avatarUrl = chatUser.avatarUrl;
      return {
        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. Нажмите «Сохранить и повторно развернуть» .

Питон

  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 следующим кодом:
    python/chat/avatar-app/main.py
    from typing import Any, Mapping
    
    import flask
    import functions_framework
    
    # The ID of the slash command "/about".
    # You must use the same ID in the Google Chat API configuration.
    ABOUT_COMMAND_ID = 1
    
    @functions_framework.http
    def avatar_app(req: flask.Request) -> Mapping[str, Any]:
      """Handle requests from Google Workspace add on
    
      Args:
        flask.Request req: the request sent by Google Chat
    
      Returns:
        Mapping[str, Any]: the response to be sent back to Google Chat
      """
      chat_event = req.get_json(silent=True)["chat"]
      if chat_event and "appCommandPayload" in chat_event:
        message = handle_app_command(chat_event)
      else:
        message = handle_message(chat_event)
      return { "hostAppDataAction": { "chatDataAction": { "createMessageAction": {
          "message": message
      }}}}
    
    def handle_app_command(event: Mapping[str, Any]) -> Mapping[str, Any]:
      """Responds to an APP_COMMAND event in Google Chat.
    
      Args:
        Mapping[str, Any] event: the event object from Google Chat
    
      Returns:
        Mapping[str, Any]: the response message object.
      """
      if event["appCommandPayload"]["appCommandMetadata"]["appCommandId"] == ABOUT_COMMAND_ID:
        return {
          "text": "The Avatar app replies to Google Chat messages.",
        }
      return {}
    
    def handle_message(event: Mapping[str, Any]) -> Mapping[str, Any]:
      """Responds to a MESSAGE event in Google Chat.
    
      Args:
        Mapping[str, Any] event: the event object from Google Chat
    
      Returns:
        Mapping[str, Any]: the response message object.
      """
      # Stores the Google Chat user as a variable.
      chat_user = event["messagePayload"]["message"]["sender"]
      display_name = chat_user.get("displayName", "")
      avatar_url = chat_user.get("avatarUrl", "")
      return {
        "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. В поле «Точка входа» удалите текст по умолчанию и введите App .
    2. Переименуйте файл Java по умолчанию в src/main/java/com/google/chat/avatar/App.java .
    3. Замените содержимое App.java следующим кодом:
    java/chat/avatar-app/src/main/java/com/google/chat/avatar/App.java
    package com.google.chat.avatar;
    
    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;
    import java.util.List;
    
    public class App implements HttpFunction {
      // The ID of the slash command "/about".
      // You must use the same ID in the Google Chat API configuration.
      private static final int ABOUT_COMMAND_ID = 1;
    
      private static final Gson gson = new Gson();
    
      /**
       * Handle requests from Google Workspace add on
       * 
       * @param request the request sent by Google Chat
       * @param response the response to be sent back to Google Chat
       */
      @Override
      public void service(HttpRequest request, HttpResponse response) throws Exception {
        JsonObject event = gson.fromJson(request.getReader(), JsonObject.class);
        JsonObject chatEvent = event.getAsJsonObject("chat");
        Message message;
        if (chatEvent.has("appCommandPayload")) {
          message = handleAppCommand(chatEvent);
        } else {
          message = handleMessage(chatEvent);
        }
        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));
      }
    
      /**
       * Handles an APP_COMMAND event in Google Chat.
       *
       * @param event the event object from Google Chat
       * @return the response message object.
       */
      private Message handleAppCommand(JsonObject event) throws Exception {
        switch (event.getAsJsonObject("appCommandPayload")
          .getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt()) {
          case ABOUT_COMMAND_ID:
            return new Message()
              .setText("The Avatar app replies to Google Chat messages.");
          default:
            return null;
        }
      }
    
      /**
       * Handles a MESSAGE event in Google Chat.
       *
       * @param event the event object from Google Chat
       * @return the response message object.
       */
      private Message handleMessage(JsonObject event) throws Exception {
        // Stores the Google Chat user as a variable.
        JsonObject chatUser = event.getAsJsonObject("messagePayload").getAsJsonObject("message").getAsJsonObject("sender");
        String displayName = chatUser.has("displayName") ? chatUser.get("displayName").getAsString() : "";
        String avatarUrl = chatUser.has("avatarUrl") ? chatUser.get("avatarUrl").getAsString() : "";
        return new Message()
          .setText("Here's your avatar")
          .setCardsV2(List.of(new CardWithId()
            .setCardId("avatarCard")
            .setCard(new GoogleAppsCardV1Card()
              .setName("Avatar Card")
              .setHeader(new GoogleAppsCardV1CardHeader()
                .setTitle(String.format("Hello %s!", displayName)))
              .setSections(List.of(new GoogleAppsCardV1Section().setWidgets(List.of(
                new GoogleAppsCardV1Widget().setTextParagraph(new GoogleAppsCardV1TextParagraph()
                  .setText("Your avatar picture:")),
                new GoogleAppsCardV1Widget()
                  .setImage(new GoogleAppsCardV1Image().setImageUrl(avatarUrl)))))))));
      }
    }
  5. Замените содержимое pom.xml следующим кодом:

    java/chat/avatar-app/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.1.4</version>
        </dependency>
        <dependency>
          <groupId>com.google.code.gson</groupId>
          <artifactId>gson</artifactId>
          <version>2.9.1</version>
        </dependency>
        <dependency>
          <groupId>com.google.apis</groupId>
          <artifactId>google-api-services-chat</artifactId>
          <version>v1-rev20230115-2.0.0</version>
        </dependency>
      </dependencies>
    
      <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 выдает ошибку, интерфейс чата отображает сообщение «Что-то пошло не так» или «Не удалось обработать ваш запрос». Иногда интерфейс чата не отображает никаких сообщений об ошибке, но приложение или карточка чата выдает неожиданный результат; например, сообщение на карточке может не появиться.

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

Уборка

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

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

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

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