Эта страница переведена с помощью Cloud Translation API.

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

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

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

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

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

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

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

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

Цели

Настройте свою среду.
Создайте и разверните функцию Cloud Run.
Настройте надстройку Google Workspace для приложения «Чат».
Протестируйте приложение.

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

Корпоративный аккаунт Google Workspace с доступом к Google Chat .
Проект Google Cloud с включенной оплатой. Чтобы проверить, включена ли оплата в существующем проекте, см. раздел «Проверка статуса оплаты ваших проектов ». Чтобы создать проект и настроить оплату, см. раздел «Создание проекта Google Cloud» .

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

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

В консоли 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

В консоли Google Cloud перейдите на страницу Cloud Run:
Перейдите в Cloud Run
Убедитесь, что выбран проект для вашего приложения «Чат».
Нажмите «Написать функцию» .
На странице создания сервиса настройте свою функцию:
1. В поле «Название сервиса» введите addonchatapp .
2. В списке регионов выберите нужный регион.
3. В списке «Среда выполнения» выберите самую последнюю версию Node.js.
4. В разделе «Аутентификация» выберите «Требовать аутентификацию» .
5. Нажмите «Создать» и дождитесь, пока Cloud Run создаст службу. Консоль перенаправит вас на вкладку «Источник» .

На вкладке «Источник» :

В поле "Точка входа" удалите текст по умолчанию и введите avatarApp .
Замените содержимое файла index.js следующим кодом:

node/chat/avatar-app/index.js

Посмотреть на GitHub

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 }
        }]}]
      }
    }]
  };
}

Нажмите «Сохранить и повторно развернуть» .

Python

В консоли Google Cloud перейдите на страницу Cloud Run:
Перейдите в Cloud Run
Убедитесь, что выбран проект для вашего приложения «Чат».
Нажмите «Написать функцию» .
На странице создания сервиса настройте свою функцию:
1. В поле «Название сервиса» введите addonchatapp .
2. В списке регионов выберите нужный регион.
3. В списке «Среда выполнения» выберите самую последнюю версию Python.
4. В разделе «Аутентификация» выберите «Требовать аутентификацию» .
5. Нажмите «Создать» и дождитесь, пока Cloud Run создаст службу. Консоль перенаправит вас на вкладку «Источник» .

На вкладке «Источник» :

В поле "Точка входа " удалите текст по умолчанию и введите avatar_app .
Замените содержимое файла main.py следующим кодом:

python/chat/avatar-app/main.py

Посмотреть на GitHub

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 }},
        ]}]
      }
    }]
  }

Нажмите «Сохранить и повторно развернуть» .

Java

В консоли Google Cloud перейдите на страницу Cloud Run:
Перейдите в Cloud Run
Убедитесь, что выбран проект для вашего приложения «Чат».
Нажмите «Написать функцию» .
На странице создания сервиса настройте свою функцию:
1. В поле «Название сервиса» введите addonchatapp .
2. В списке регионов выберите нужный регион.
3. В списке «Среда выполнения» выберите самую последнюю версию Java.
4. В разделе «Аутентификация» выберите «Требовать аутентификацию» .
5. Нажмите «Создать» и дождитесь, пока Cloud Run создаст службу. Консоль перенаправит вас на вкладку «Источник» .

На вкладке «Источник» :

В поле "Точка входа" удалите текст по умолчанию и введите App .
Переименуйте стандартный Java-файл в src/main/java/com/google/chat/avatar/App.java .
Замените содержимое файла App.java следующим кодом:

java/chat/avatar-app/src/main/java/com/google/chat/avatar/App.java

Посмотреть на GitHub

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)))))))));
  }
}

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

java/chat/avatar-app/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/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>

Нажмите «Сохранить и повторно развернуть» .

Откроется страница с подробными сведениями о сервисе Cloud Run. Дождитесь развертывания функции.

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

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

В консоли Google Cloud перейдите на страницу Cloud Run:
Перейдите в Cloud Run
Убедитесь, что выбран проект, для которого вы включили Cloud Run.
В списке функций нажмите addonchatapp .
На странице сведений о сервисе скопируйте URL-адрес функции. URL-адрес заканчивается на run.app .
В поле поиска Google Cloud найдите "Google Chat API", затем щелкните Google Chat API и нажмите "Управление" .
Перейти к API чата
Нажмите «Конфигурация» и настройте приложение 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. В разделе «Журналы» выберите « Записывать ошибки в журнал» и перейдите в раздел «Ведение журнала» .
Нажмите « Сохранить ».

Далее разрешите приложению «Чат» вызывать функцию Cloud Run.

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

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

В консоли Google Cloud перейдите на страницу Cloud Run:
Перейдите в Cloud Run
В списке служб Cloud Run установите флажок рядом с принимающей функцией. (Не нажимайте на саму функцию.)
Нажмите «Разрешения» . Откроется панель «Разрешения» .
Нажмите «Добавить основного пользователя» .
В поле «Новые участники» введите адрес электронной почты учетной записи службы дополнения Google Workspace, связанной с вашим приложением «Чат».
Адрес электронной почты учетной записи службы находится на странице конфигурации Chat API, в разделе «Настройки подключения» > «URL-адрес конечной точки HTTP» > «Электронная почта учетной записи службы» :
Перейдите в раздел «Настройка API чата».
В разделе «Выберите роль» выберите Cloud Run > Cloud Run Service Invoker .
Нажмите « Сохранить ».

Приложение «Чат» готово к приему и ответам на сообщения в чате.

Протестируйте свое приложение для чата

Чтобы протестировать приложение «Чат», откройте личное сообщение в приложении «Чат» и отправьте сообщение:

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

В сообщении приложения «Чат» отображается карточка с именем отправителя и его аватаром, как показано на следующем изображении:

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

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

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

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

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

Уборка

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

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

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

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

В консоли Google Cloud перейдите на страницу «Управление ресурсами» > IAM и администрирование > Управление ресурсами .
Перейдите в Диспетчер ресурсов
В списке проектов выберите проект, который хотите удалить, и нажмите кнопку «Удалить .
В диалоговом окне введите идентификатор проекта, а затем нажмите «Завершить» , чтобы удалить проект.

Создайте HTTP-приложение Google Chat. Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

Цели

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

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

Создайте и разверните функцию Cloud Run.

Node.js

Python

Java

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

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

Протестируйте свое приложение для чата

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

Уборка

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