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

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

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

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

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

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

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

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

Цели

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

Предварительные условия

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

Прежде чем использовать API Google, вам необходимо включить их в проекте Google Cloud. Вы можете включить один или несколько API в одном проекте Google Cloud.
  • В консоли Google Cloud включите API Google Chat, API Cloud Build, API облачных функций, API Cloud Pub/Sub, API облачного ведения журнала, API реестра артефактов и API Cloud Run.

    Включите API

Создайте и разверните облачную функцию

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

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

Node.js

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

    Перейти к облачным функциям

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

  2. Нажмите Создать функцию .

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

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

  5. В разделе «Исходный код» выберите «Встроенный редактор» .

  6. В Точке входа удалите текст по умолчанию и введите avatarApp .

  7. Замените содержимое index.js следующим кодом:

    /**
     * Google Cloud 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
     */
    exports.avatarApp = function 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 }
                        }]
                    }]
                }
            }]
        }}}}});
    };
    
  8. Нажмите «Развернуть» .

Питон

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

    Перейти к облачным функциям

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

  2. Нажмите Создать функцию .

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

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

  5. В разделе «Исходный код» выберите «Встроенный редактор» .

  6. В Точке входа удалите текст по умолчанию и введите avatar_app .

  7. Замените содержимое 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 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 }
                        }]
                    }]
                }
            }]
        }}}}}
    
  8. Нажмите «Развернуть» .

Ява

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

    Перейти к облачным функциям

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

  2. Нажмите Создать функцию .

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

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

  5. В разделе «Исходный код» выберите «Встроенный редактор» .

  6. В Точке входа удалите текст по умолчанию и введите AvatarApp .

  7. Переименуйте файл Java по умолчанию в src/main/java/AvatarApp.java .

  8. Замените содержимое 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;
        }
    }
    
  9. Замените содержимое 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>
    
  10. Нажмите «Развернуть» .

Откроется страница сведений об облачных функциях, и ваша функция появится с двумя индикаторами хода выполнения: один для сборки, а другой для службы. Когда оба индикатора хода выполнения исчезнут и будут заменены галочками, ваша функция развернута и готова.

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

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

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

    Перейти в Cloud Run

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

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

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

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

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

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

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

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

  1. В консоли Google Cloud нажмите > Функции облака .

    Перейти к облачным функциям

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

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

  3. Откройте вкладку «Триггеры» .

  4. В разделе HTTPS скопируйте URL-адрес.

  5. Найдите «Google Chat API» и нажмите «Google Chat API» , затем нажмите «Управление» .

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Очистить

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

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

    Зайдите в диспетчер ресурсов

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