Эта страница переведена с помощью 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. В разделе «Триггеры» выберите « Использовать общий URL-адрес конечной точки HTTP для всех триггеров» и вставьте URL-адрес триггера функции Cloud Run в поле.
7. В разделе «Видимость» выберите «Сделать это приложение Google Chat доступным для определенных людей и групп в вашем домене» и введите свой адрес электронной почты.
8. В разделе «Журналы» выберите « Записывать ошибки в журнал» и перейдите в раздел «Ведение журнала» .
Нажмите « Сохранить ».
В разделе «Настройки подключения» скопируйте адрес электронной почты учетной записи службы . Этот адрес электронной почты понадобится вам при авторизации дополнения для вызова вашей функции.

Далее разрешите приложению «Чат» вызывать функцию 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 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.