На этой странице объясняется, как создать дополнение Google Workspace, работающее в Google Chat, используя службу HTTP.
В этом кратком руководстве показано, как создать HTTP-сервис с использованием сервисов Google Cloud. Для создания приложения Chat необходимо написать и развернуть облачную функцию , которую приложение Chat будет использовать для ответа на сообщение пользователя.
При использовании архитектуры HTTP вы настраиваете Chat для интеграции с Google Cloud или локальным сервером с помощью HTTP, как показано на следующей схеме:
На предыдущей диаграмме пользователь, взаимодействующий с приложением HTTP-чата, имеет следующий поток информации:
- Пользователь отправляет сообщение в чате в приложение чата, либо в личном сообщении, либо в чат-пространстве.
- HTTP-запрос отправляется на веб-сервер, который представляет собой либо облачную, либо локальную систему, содержащую логику приложения чата.
- При желании логику приложения Chat можно интегрировать с сервисами Google Workspace (например, Календарь и Таблицы), другими сервисами Google (например, Карты, YouTube и Vertex AI) или другими веб-сервисами (например, системой управления проектами или инструментом тикетов).
- Веб-сервер отправляет HTTP-ответ обратно в службу приложения Chat.
- Ответ доставляется пользователю.
- При желании приложение чата может вызывать API чата для асинхронной публикации сообщений или выполнения других операций.
Такая архитектура обеспечивает гибкость в использовании существующих библиотек и компонентов, которые уже присутствуют в вашей системе, поскольку эти чат-приложения могут быть разработаны с использованием различных языков программирования.
Цели
- Настройте свою среду.
- Создайте и разверните облачную функцию.
- Настройте дополнение Google Workspace для приложения Chat.
- Протестируйте приложение.
Предпосылки
- Учетная запись Google Workspace Business или Enterprise с доступом к Google Chat .
- Проект Google Cloud с включённым биллингом. Чтобы проверить, включён ли биллинг для существующего проекта, см. раздел Проверка статуса биллинга ваших проектов . Чтобы создать проект и настроить биллинг, см. раздел Создание проекта Google Cloud .
Настройте среду
Перед использованием 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.
Создание и развертывание облачной функции
Создайте и разверните облачную функцию, которая генерирует карточку чата с отображаемым именем и аватаром отправителя. Когда приложение чата получает сообщение, оно запускает функцию и отвечает карточкой.
Чтобы создать и развернуть функцию для вашего приложения чата, выполните следующие действия:
Node.js
В консоли Google Cloud перейдите на страницу Cloud Functions:
Убедитесь, что выбран проект для вашего приложения чата.
Нажмите
Создать функцию .На странице «Создать функцию» настройте свою функцию:
- В разделе Окружающая среда выберите Функция запуска облака .
- В поле Имя функции введите
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 перейдите на страницу Cloud Functions:
Убедитесь, что выбран проект для вашего приложения чата.
Нажмите
Создать функцию .На странице «Создать функцию» настройте свою функцию:
- В разделе Окружающая среда выберите Функция запуска облака .
- В поле Имя функции введите
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 перейдите на страницу Cloud Functions:
Убедитесь, что выбран проект для вашего приложения чата.
Нажмите
Создать функцию .На странице «Создать функцию» настройте свою функцию:
- В разделе Окружающая среда выберите Функция запуска облака .
- В поле Имя функции введите
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>
Нажмите Развернуть .
Откроется страница сведений о функциях Cloud Functions, на которой ваша функция будет отображаться с двумя индикаторами выполнения: один для сборки, а другой для сервиса. Когда оба индикатора выполнения исчезнут и вместо них появится галочка, ваша функция будет развернута и готова к работе.
Настройте дополнение
После развертывания облачной функции выполните следующие действия для создания надстройки и развертывания приложения Google Chat:
В консоли Google Cloud выберите > Функции облака .
Убедитесь, что выбран проект, для которого вы включили Cloud Functions.
В списке функций нажмите AddOnChatApp .
Откройте вкладку Триггеры .
В поле HTTPS скопируйте URL-адрес.
Найдите «Google Chat API» и нажмите Google Chat API , затем нажмите Управление .
Нажмите «Конфигурация» и настройте приложение Google Chat:
- В поле «Имя приложения» введите
Add-on Chat app
. - В поле URL-адрес аватара введите
https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png
. - В поле Описание введите
Add-on Chat app
. - В разделе «Функциональность» выберите Присоединяйтесь к пространствам и групповым беседам .
- В разделе «Настройки подключения» выберите URL-адрес конечной точки HTTP и вставьте URL-адрес для триггера облачной функции в поле.
- В разделе «Аудитория аутентификации» выберите URL конечной точки HTTP .
- В разделе «Видимость» выберите «Сделать это приложение Google Chat доступным для определенных людей и групп в вашем домене» и введите свой адрес электронной почты.
- В разделе Журналы выберите Записывать ошибки в Журнал .
- В поле «Имя приложения» введите
Нажмите «Сохранить» .
Затем разрешите приложению чата вызывать функцию облака.
Разрешите Google Chat вызывать вашу функцию
Чтобы разрешить надстройке Google Workspace вызывать вашу функцию, добавьте учетную запись службы надстройки Google Workspace с ролью Cloud Run Invoker .
В консоли Google Cloud перейдите на страницу Cloud Run:
В списке служб Cloud Run установите флажок рядом с функцией получения. (Не нажимайте на саму функцию.)
Нажмите «Разрешения» . Откроется панель «Разрешения» .
Нажмите Добавить принципала .
В поле New principals введите адрес электронной почты учётной записи службы надстройки Google Workspace, связанной с вашим проектом. Адрес электронной почты учётной записи службы можно найти в разделе Connection settings > HTTP endpoint URL > Service Account Email на странице конфигурации Chat API:
В разделе «Выбор роли» выберите Cloud Run > Cloud Run Invoker .
Нажмите «Сохранить» .
Приложение Chat готово принимать и отвечать на сообщения в Chat.
Протестируйте свое приложение чата
Чтобы протестировать приложение Chat, откройте чат-комнату в приложении и отправьте сообщение:
Откройте Google Chat, используя учетную запись Google Workspace, которую вы указали при добавлении себя в качестве доверенного тестировщика.
- Нажмите новый чат» .
- В поле Добавить 1 или более человек введите название вашего чат-приложения.
Выберите приложение чата из результатов. Откроется личное сообщение.
- В новом прямом сообщении с приложением введите
Hello
и нажмитеenter
.
Сообщение приложения «Чат» содержит карточку, на которой отображается имя отправителя и его аватар, как показано на следующем изображении:
Чтобы добавить доверенных тестировщиков и узнать больше о тестировании интерактивных функций, ознакомьтесь с разделом Тестирование интерактивных функций для приложений Google Chat .
Устранение неполадок
Когда приложение или карточка Google Chat возвращает ошибку, в интерфейсе Chat отображается сообщение «Что-то пошло не так» или «Не удалось обработать ваш запрос». Иногда в интерфейсе Chat не отображается сообщение об ошибке, но приложение или карточка Chat выдаёт неожиданный результат; например, сообщение может не появиться.
Хотя сообщение об ошибке может не отображаться в пользовательском интерфейсе чата, при включенном ведении журнала ошибок для приложений чата доступны описательные сообщения об ошибках и данные журнала, которые помогут вам исправить ошибки. Сведения о просмотре, отладке и исправлении ошибок см. в статье «Устранение неполадок и исправление ошибок Google Chat» .
Уборка
Чтобы избежать списания средств с вашего аккаунта Google Cloud за ресурсы, используемые в этом руководстве, мы рекомендуем вам удалить проект Cloud.
- В консоли Google Cloud перейдите на страницу «Управление ресурсами» . Выберите « Меню > «IAM и администрирование» > «Управление ресурсами» .
- В списке проектов выберите проект .
- В диалоговом окне введите идентификатор проекта, а затем нажмите кнопку «Завершить» , чтобы удалить проект.