На этой странице объясняется, как создать надстройку Google Workspace, которая будет работать в Google Chat с использованием службы HTTP. В Google Chat дополнения отображаются пользователям как приложения Google Chat. Дополнительную информацию см. в обзоре расширения Google Chat .
В этом кратком руководстве показано, как создать службу HTTP с использованием сервисов Google Cloud. Чтобы создать приложение чата, вы пишете и развертываете облачную функцию , которую приложение чата использует для ответа на сообщение пользователя.
При использовании архитектуры HTTP вы настраиваете Chat для интеграции с Google Cloud или локальным сервером с помощью HTTP, как показано на следующей схеме:
На предыдущей диаграмме пользователь, взаимодействующий с приложением HTTP Chat, имеет следующий поток информации:
- Пользователь отправляет сообщение в Chat в приложение Chat либо в прямом сообщении, либо в чат-группе.
- HTTP-запрос отправляется на веб-сервер, который является облачной или локальной системой и содержит логику приложения Chat.
- При желании логику приложения Chat можно интегрировать со службами Google Workspace (например, Календарем и Таблицами), другими службами Google (например, Картами, YouTube и Vertex AI) или другими веб-службами (например, системой управления проектами или инструментом продажи билетов).
- Веб-сервер отправляет ответ HTTP обратно в службу приложения Chat.
- Ответ доставляется пользователю.
- При желании приложение Chat может вызывать API Chat для асинхронной публикации сообщений или выполнения других операций.
Эта архитектура дает вам возможность использовать существующие библиотеки и компоненты, которые уже существуют в вашей системе, поскольку эти приложения чата могут быть разработаны с использованием разных языков программирования.
Цели
- Настройте свою среду.
- Создайте и разверните облачную функцию.
- Настройте надстройку Google Workspace для приложения 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.
Создайте и разверните облачную функцию
Создайте и разверните облачную функцию, которая создает карточку чата с отображаемым именем отправителя и изображением аватара. Когда приложение чата получает сообщение, оно запускает функцию и отвечает картой.
Чтобы создать и развернуть функцию для вашего приложения Chat, выполните следующие шаги:
Node.js
В консоли Google Cloud перейдите на страницу «Функции облака»:
Убедитесь, что выбран проект для вашего приложения Chat.
Нажмите
Создать функцию .На странице «Создать функцию» настройте свою функцию:
- В разделе «Среда » выберите «Функция запуска облака» .
- В поле «Имя функции» введите
AddOnChatApp
. - В разделе «Регион» выберите регион.
- В разделе «Аутентификация» выберите «Требовать аутентификацию» .
- Нажмите Далее .
В Runtime выберите самую последнюю версию Node.js.
В разделе «Исходный код» выберите «Встроенный редактор» .
В Точке входа удалите текст по умолчанию и введите
avatarApp
.Замените содержимое
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 } }] }] } }] }}}}}); };
Нажмите «Развернуть» .
Питон
В консоли Google Cloud перейдите на страницу «Функции облака»:
Убедитесь, что выбран проект для вашего приложения Chat.
Нажмите
Создать функцию .На странице «Создать функцию» настройте свою функцию:
- В разделе «Среда » выберите «Функция запуска облака» .
- В поле «Имя функции» введите
AddOnChatApp
. - В разделе «Регион» выберите регион.
- В разделе «Аутентификация» выберите «Требовать аутентификацию» .
- Нажмите Далее .
В Runtime выберите самую последнюю версию Python.
В разделе «Исходный код» выберите «Встроенный редактор» .
В Точке входа удалите текст по умолчанию и введите
avatar_app
.Замените содержимое
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 } }] }] } }] }}}}}
Нажмите «Развернуть» .
Ява
В консоли Google Cloud перейдите на страницу «Функции облака»:
Убедитесь, что выбран проект для вашего приложения Chat.
Нажмите
Создать функцию .На странице «Создать функцию» настройте свою функцию:
- В разделе «Среда » выберите «Функция запуска облака» .
- В поле «Имя функции» введите
AddOnChatApp
. - В разделе «Регион» выберите регион.
- В разделе «Аутентификация» выберите «Требовать аутентификацию» .
- Нажмите Далее .
В Runtime выберите самую последнюю версию Java.
В разделе «Исходный код» выберите «Встроенный редактор» .
В Точке входа удалите текст по умолчанию и введите
AvatarApp
.Переименуйте файл Java по умолчанию в
src/main/java/AvatarApp.java
.Замените содержимое
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; } }
Замените содержимое
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>
Нажмите «Развернуть» .
Откроется страница сведений об облачных функциях, и ваша функция появится с двумя индикаторами хода выполнения: один для сборки, а другой для службы. Когда оба индикатора выполнения исчезнут и будут заменены галочками, ваша функция развернута и готова.
Разрешите Google Chat вызывать вашу функцию
Чтобы разрешить надстройке Google Workspace вызывать вашу функцию, добавьте учетную запись службы надстройки Google Workspace с ролью Cloud Run Invoker .
В консоли Google Cloud перейдите на страницу Cloud Run:
В списке сервисов Cloud Run установите флажок рядом с функцией приема. (Не нажимайте на саму функцию.)
Нажмите Разрешения . Откроется панель «Разрешения» .
Нажмите Добавить принципала .
В разделе «Новые участники» введите адрес электронной почты учетной записи службы надстроек Google Workspace, связанной с вашим проектом.
В разделе «Выберите роль» выберите Cloud Run > Cloud Run Invoker .
Нажмите Сохранить .
Настроить дополнение
После развертывания облачной функции выполните следующие действия, чтобы создать надстройку и развернуть приложение Google Chat:
В консоли Google Cloud нажмите > Функции облака .
Убедитесь, что выбран проект, для которого вы включили облачные функции.
В списке функций нажмите AddOnChatApp .
Откройте вкладку «Триггеры» .
В разделе HTTPS скопируйте URL-адрес.
Найдите «Google Chat API» и нажмите «Google Chat API» , затем нажмите «Управление» .
Нажмите «Конфигурация» и настройте приложение Google Chat:
- В поле «Имя приложения» введите
Add-on Chat app
. - В URL-адресе аватара введите
https://developers.google.com/chat/images/quickstart-app-avatar.png
. - В поле «Описание» введите
Add-on Chat app
. - В разделе «Функциональность» выберите «Получать сообщения 1:1» и «Присоединяться к группам и групповым беседам» .
- В разделе «Настройки соединения» выберите URL-адрес конечной точки HTTP и вставьте URL-адрес триггера облачной функции в поле.
- В разделе «Аудитория аутентификации» выберите URL-адрес конечной точки HTTP .
- В разделе «Видимость » выберите «Сделать это приложение Google Chat доступным для определенных людей и групп в вашем домене» и введите свой адрес электронной почты.
- В разделе «Журналы» выберите «Записывать ошибки в журнал» .
- В поле «Имя приложения» введите
Нажмите Сохранить .
Приложение Chat готово получать сообщения в Chat и отвечать на них.
Проверьте свое приложение чата
Чтобы протестировать приложение Chat, откройте пространство для прямых сообщений в приложении Chat и отправьте сообщение:
Откройте Google Chat, используя учетную запись Google Workspace, которую вы указали при добавлении себя в качестве доверенного тестировщика.
- Нажмите новый чат» .
- В поле «Добавить 1 или несколько человек» введите название вашего приложения чата.
Выберите приложение чата из результатов. Откроется прямое сообщение.
- В новом прямом сообщении с приложением введите
Hello
и нажмитеenter
.
Сообщение приложения Chat содержит карточку, на которой отображается имя отправителя и изображение аватара, как показано на следующем изображении:
Чтобы добавить доверенных тестировщиков и узнать больше о тестировании интерактивных функций, см. раздел Тестирование интерактивных функций для приложений Google Chat .
Устранение неполадок
Когда приложение или карточка Google Chat возвращает ошибку, в интерфейсе Chat отображается сообщение «Что-то пошло не так». или «Невозможно обработать ваш запрос». Иногда в пользовательском интерфейсе чата не отображается сообщение об ошибке, но приложение или карточка чата выдает неожиданный результат; например, сообщение с карточкой может не появиться.
Хотя сообщение об ошибке может не отображаться в пользовательском интерфейсе чата, доступны описательные сообщения об ошибках и данные журнала, которые помогут вам исправить ошибки, если включено ведение журнала ошибок для приложений чата. Информацию о просмотре, отладке и исправлении ошибок см. в разделе «Устранение неполадок и исправление ошибок Google Chat» .
Очистить
Чтобы избежать списания средств с вашей учетной записи Google Cloud за ресурсы, используемые в этом руководстве, мы рекомендуем вам удалить проект Cloud.
- В консоли Google Cloud перейдите на страницу «Управление ресурсами» . Нажмите Меню > IAM и администрирование > ресурсами .
- В списке проектов выберите проект, который хотите удалить, и нажмите «Удалить .
- В диалоговом окне введите идентификатор проекта и нажмите «Завершить работу», чтобы удалить проект.