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

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

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

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

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

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

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

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

Цели

  • Настройте свою среду.
  • Создайте и разверните облачную функцию.
  • Настройте дополнение 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

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

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

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

Node.js

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

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

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

  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 перейдите на страницу Cloud Functions:

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

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

  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 перейдите на страницу Cloud Functions:

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

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

  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. Нажмите Развернуть .

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

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

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

  1. В консоли Google Cloud выберите > Функции облака .

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

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

  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/workspace/add-ons/images/quickstart-app-avatar.png .
    3. В поле Описание введите Add-on Chat app .
    4. В разделе «Функциональность» выберите Присоединяйтесь к пространствам и групповым беседам .
    5. В разделе «Настройки подключения» выберите URL-адрес конечной точки HTTP и вставьте URL-адрес для триггера облачной функции в поле.
    6. В разделе «Аудитория аутентификации» выберите URL конечной точки HTTP .
    7. В разделе «Видимость» выберите «Сделать это приложение Google Chat доступным для определенных людей и групп в вашем домене» и введите свой адрес электронной почты.
    8. В разделе Журналы выберите Записывать ошибки в Журнал .
  7. Нажмите «Сохранить» .

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

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

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

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

    Перейти к Cloud Run

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

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

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

  5. В поле New principals введите адрес электронной почты учётной записи службы надстройки Google Workspace, связанной с вашим проектом. Адрес электронной почты учётной записи службы можно найти в разделе Connection settings > HTTP endpoint URL > Service Account Email на странице конфигурации Chat API:

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

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