Создайте 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. В диалоговом окне введите идентификатор проекта, а затем нажмите кнопку «Завершить» , чтобы удалить проект.