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

На этой странице объясняется, как создать приложение HTTP Chat. Существуют разные способы реализации этой архитектуры. В Google Cloud вы можете использовать Cloud Functions, Cloud Run и App Engine. В этом кратком руководстве вы напишете и развернете облачную функцию , которую приложение Chat использует для ответа на сообщение пользователя.

В этой архитектуре вы настраиваете 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 для бизнеса или предприятия с доступом к Google Chat .
• Проект Google Cloud с включенной оплатой. Чтобы проверить, включена ли оплата для существующего проекта, см. раздел Проверка статуса выставления счетов ваших проектов . Инструкции по созданию проекта и настройке оплаты см. в разделе Создание проекта Google Cloud .

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

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

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

  Включите API

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

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

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

Node.js

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

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

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

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

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

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

4. В Runtime выберите самую последнюю версию Node.js.

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

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

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

   узел/аватар-приложение/index.js

   Посмотреть на GitHub
   const functions = require('@google-cloud/functions-framework');
   
   // Command IDs (configure these in Google Chat API)
   const ABOUT_COMMAND_ID = 1; // ID for the "/about" slash command
   const HELP_COMMAND_ID = 2; // ID for the "Help" quick command
   
   /**
    * Google Cloud Function that handles HTTP requests from Google Chat.
    *
    * @param {Object} req - The HTTP request object sent from Google Chat.
    * @param {Object} res - The HTTP response object.
    */
   functions.http('avatarApp', (req, res) => {
     const event = req.body;
   
     if (event.appCommandMetadata) {
       handleAppCommands(event, res);
     } else {
       handleRegularMessage(event, res);
     }
   });
   
   /**
    * Handles slash and quick commands.
    *
    * @param {Object} event - The Google Chat event.
    * @param {Object} res - The HTTP response object.
    */
   function handleAppCommands(event, res) {
     const {appCommandId, appCommandType} = event.appCommandMetadata;
   
     switch (appCommandId) {
       case ABOUT_COMMAND_ID:
         return res.send({
           privateMessageViewer: event.user,
           text: 'The Avatar app replies to Google Chat messages.'
         });
       case HELP_COMMAND_ID:
         return res.send({
           privateMessageViewer: event.user,
           text: 'The Avatar app replies to Google Chat messages.'
         });
     }
   }
   
   /**
    * Handles regular messages (not commands).
    *
    * @param {Object} event - The Google Chat event.
    * @param {Object} res - The HTTP response object.
    */
   function handleRegularMessage(event, res) {
     const messageData = createMessage(event.user);
     res.send(messageData);
   }
   
   /**
    * Creates a card message with the user's avatar.
    *
    * @param {Object} user - The user who sent the message.
    * @param {string} user.displayName - The user's display name.
    * @param {string} user.avatarUrl - The URL of the user's avatar.
    * @return {Object} - The card message object.
    */
   function createMessage({displayName, 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}},
             ],
           }],
         },
       }],
     };
   }

8. Нажмите «Развернуть» .

Питон

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

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

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

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

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

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

4. В Runtime выберите самую последнюю версию Python.

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

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

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

   python/аватар-приложение/main.py

   Посмотреть на GitHub
   from typing import Any, Mapping
   
   import flask
   import functions_framework
   
   # Command IDs (configure these in Google Chat API)
   ABOUT_COMMAND_ID = 1  # ID for the "/about" slash command
   HELP_COMMAND_ID = 2  # ID for the "Help" quick command
   
   
   @functions_framework.http
   def avatar_app(req: flask.Request) -> Mapping[str, Any]:
       """Google Cloud Function that handles HTTP requests from Google Chat.
   
       Args:
           flask.Request: the request
   
       Returns:
           Mapping[str, Any]: the response
       """
       event = req.get_json(silent=True)
   
       if event and "appCommandMetadata" in event:
           return handle_app_commands(event)
       else:
           return handle_regular_message(event)
   
   
   def handle_app_commands(event: Mapping[str, Any]) -> Mapping[str, Any]:
       """Handles slash and quick commands.
   
       Args:
           Mapping[str, Any] event: The Google Chat event.
   
       Returns:
           Mapping[str, Any]: the response
       """
       app_command_id = event["appCommandMetadata"]["appCommandId"]
   
       if app_command_id == ABOUT_COMMAND_ID:
           return {
               "privateMessageViewer": event["user"],
               "text": "The Avatar app replies to Google Chat messages.",
           }
       elif app_command_id == HELP_COMMAND_ID:
           return {
               "privateMessageViewer": event["user"],
               "text": "The Avatar app replies to Google Chat messages.",
           }
       return {}
   
   
   
   
   def handle_regular_message(event: Mapping[str, Any]) -> Mapping[str, Any]:
       """Handles regular messages (not commands).
   
       Args:
           Mapping[str, Any] event: The Google Chat event.
   
       Returns:
           Mapping[str, Any]: the response
       """
   
       if not event or "user" not in event:
           return "Invalid request."
   
       message_data = create_message(event["user"])
       return message_data
   
   
   def create_message(user: Mapping[str, Any]) -> Mapping[str, Any]:
       """Creates a card message with the user's avatar.
   
       Args:
           Mapping[str, Any] user: The user who sent the message.
   
       Returns:
           Mapping[str, Any]: a card with the user's avatar.
       """
       display_name = user.get("displayName", "")
       avatar_url = 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}},
                               ]
                           }
                       ],
                   },
               }
           ],
       }

8. Нажмите «Развернуть» .

Ява

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

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

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

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

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

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

4. В Runtime выберите самую последнюю версию Java.

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

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

7. Переименуйте src/main/java/com/example/Example.java в src/main/java/AvatarApp.java .

8. Замените содержимое AvatarApp.java следующим кодом:

   java/avatar-app/src/main/java/AvatarApp.java

   Посмотреть на GitHub
   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.api.services.chat.v1.model.User;
   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 AvatarApp implements HttpFunction {
     private static final Gson gson = new Gson();
   
     // Command IDs (configure these in Google Chat API)
     private static final int ABOUT_COMMAND_ID = 1; // ID for the "/about" slash command
     private static final int HELP_COMMAND_ID = 2; // ID for the "Help" quick command
   
     @Override
     public void service(HttpRequest request, HttpResponse response) throws Exception {
       JsonObject event = gson.fromJson(request.getReader(), JsonObject.class);
   
       if (event.has("appCommandMetadata")) {
         handleAppCommands(event, response);
       } else {
         handleRegularMessage(event, response);
       }
     }
   
     /**
      * Handles slash and quick commands.
      *
      * @param event    The Google Chat event.
      * @param response The HTTP response object.
      */
     private void handleAppCommands(JsonObject event, HttpResponse response) throws Exception {
       int appCommandId = event.getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt();
   
       switch (appCommandId) {
         case ABOUT_COMMAND_ID:
           Message aboutMessage = new Message();
           aboutMessage.setText("The Avatar app replies to Google Chat messages.");
           aboutMessage.setPrivateMessageViewer(new User()
               .setName(event.getAsJsonObject("user").get("name").getAsString()));
           response.getWriter().write(gson.toJson(aboutMessage));
           return;
         case HELP_COMMAND_ID:
           Message helpMessage = new Message();
           helpMessage.setText("The Avatar app replies to Google Chat messages.");
           helpMessage.setPrivateMessageViewer(new User()
               .setName(event.getAsJsonObject("user").get("name").getAsString()));
           response.getWriter().write(gson.toJson(helpMessage));
           return;
       }
     }
   
     /**
      * Handles regular messages (not commands).
      *
      * @param event    The Google Chat event.
      * @param response The HTTP response object.
      */
     private void handleRegularMessage(JsonObject event, HttpResponse response) throws Exception {
   
       if (!event.has("user")) {
         response.getWriter().write("Invalid request.");
         return;
       }
   
       JsonObject user = event.getAsJsonObject("user");
       String displayName = user.has("displayName") ? user.get("displayName").getAsString() : "";
       String avatarUrl = user.has("avatarUrl") ? user.get("avatarUrl").getAsString() : "";
       Message message = createMessage(displayName, avatarUrl);
       response.getWriter().write(gson.toJson(message));
     }
   
     /**
      * Creates a card message with the user's avatar.
      *
      * @param displayName The user's display name.
      * @param avatarUrl   The URL of the user's avatar.
      * @return The card message object.
      */
     private Message createMessage(String displayName, String avatarUrl) {
       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)))))))));
     }
   }

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

   java/аватар-приложение/pom.xml

   Посмотреть на GitHub
   <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/maven-v4_0_0.xsd">
     <modelVersion>4.0.0</modelVersion>
   
     <groupId>gcfv2</groupId>
     <artifactId>avatar-app</artifactId>
     <version>0.0.1</version>
     <name>Avatar App</name>
   
     <properties>
       <maven.compiler.release>21</maven.compiler.release>
     </properties>
   
     <dependencies>
       <dependency>
         <groupId>com.google.cloud.functions</groupId>
         <artifactId>functions-framework-api</artifactId>
         <version>1.1.4</version>
       </dependency>
   
       <!-- https://mvnrepository.com/artifact/com.google.code.gson/gson -->
       <dependency>
         <groupId>com.google.code.gson</groupId>
         <artifactId>gson</artifactId>
         <version>2.12.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-rev20250116-2.0.0</version>
       </dependency>
   
     </dependencies>
   
   </project>

10. Нажмите «Развернуть» .

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

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

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

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

   Перейти в Cloud Run

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

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

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

5. В разделе «Новые участники» введите [e-mail] .

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

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

Опубликуйте приложение в Google Chat

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

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

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

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

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

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

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

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

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

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

   1. В поле «Имя приложения» введите Quickstart App .
   2. В URL-адресе аватара введите https://developers.google.com/chat/images/quickstart-app-avatar.png .
   3. В поле «Описание» введите Quickstart 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. Выберите приложение чата из результатов. Откроется прямое сообщение.

   Примечание. Если вы не видите свое приложение Chat в списке результатов, убедитесь, что вы включили свою учетную запись Google Workspace в настройки видимости на странице конфигурации Chat API в консоли Google Cloud.
5. В новом прямом сообщении с приложением введите Hello и нажмите enter .

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

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

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

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

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

Очистить

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

Внимание: Удаление проекта имеет следующие последствия:

• Все в проекте удалено. Если для этого руководства вы использовали существующий проект, то при его удалении вы также удаляете всю другую работу, выполненную в этом проекте.
• Пользовательские идентификаторы проектов теряются. Создавая этот проект, вы, возможно, создали собственный идентификатор проекта, который хотите использовать в будущем. Чтобы сохранить URL-адреса, использующие идентификатор проекта, например URL-адрес на сайте appspot.com, удалите выбранные ресурсы внутри проекта, а не удаляйте весь проект.

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

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

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

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

Связанные темы

• Чтобы добавить дополнительные функции в приложение Chat, см. следующее:

  • Создавайте интерактивные карточные сообщения
  • Реагировать на команды слэша
  • Открывать диалоги и отвечать на них

• Выберите архитектуру приложения Chat

• Проверка запросов от Google Chat