Trang này giải thích cách tạo một Tiện ích bổ sung Google Workspace hoạt động trong Google Chat bằng cách sử dụng dịch vụ HTTP. Trong Google Chat, các tiện ích bổ sung sẽ xuất hiện với người dùng dưới dạng ứng dụng Google Chat. Để tìm hiểu thêm, hãy xem bài viết Tổng quan về việc mở rộng Google Chat.
Phần hướng dẫn nhanh này cho bạn biết cách tạo dịch vụ HTTP bằng các dịch vụ của Google Cloud. Để tạo ứng dụng Chat, bạn sẽ viết và triển khai một Hàm trên đám mây mà ứng dụng Chat sử dụng để phản hồi tin nhắn của người dùng.
Với cấu trúc HTTP, bạn định cấu hình Chat để tích hợp với Google Cloud hoặc máy chủ cục bộ bằng cách sử dụng HTTP, như minh hoạ trong sơ đồ sau:
Trong sơ đồ trước, người dùng tương tác với ứng dụng Chat qua HTTP có luồng thông tin như sau:
- Người dùng gửi tin nhắn trong Chat đến một ứng dụng Chat, trong tin nhắn trực tiếp hoặc trong một không gian Chat.
- Yêu cầu HTTP được gửi đến một máy chủ web là hệ thống trên đám mây hoặc tại chỗ chứa logic ứng dụng Chat.
- Nếu muốn, logic ứng dụng Chat có thể tích hợp với các dịch vụ của Google Workspace (như Lịch và Trang tính), các dịch vụ khác của Google (như Maps, YouTube và Vertex AI) hoặc các dịch vụ web khác (như hệ thống quản lý dự án hoặc công cụ tạo phiếu yêu cầu hỗ trợ).
- Máy chủ web gửi phản hồi HTTP trở lại dịch vụ ứng dụng Chat trong Chat.
- Phản hồi được gửi đến người dùng.
- Nếu muốn, ứng dụng Chat có thể gọi Chat API để đăng tin nhắn không đồng bộ hoặc thực hiện các thao tác khác.
Cấu trúc này cho phép bạn linh hoạt sử dụng các thư viện và thành phần hiện có trong hệ thống vì các ứng dụng Chat này có thể được thiết kế bằng nhiều ngôn ngữ lập trình.
Mục tiêu
- Thiết lập môi trường.
- Tạo và triển khai một Chức năng trên đám mây.
- Định cấu hình tiện ích bổ sung của Google Workspace cho ứng dụng Chat.
- Kiểm thử ứng dụng.
Điều kiện tiên quyết
- Tài khoản Google Workspace dành cho doanh nghiệp hoặc doanh nghiệp lớn có quyền truy cập vào Google Chat.
- Một dự án Google Cloud đã bật tính năng thanh toán. Để kiểm tra xem một dự án hiện có đã bật tính năng thanh toán hay chưa, hãy xem bài viết Xác minh trạng thái thanh toán của dự án. Để tạo dự án và thiết lập thông tin thanh toán, hãy xem phần Tạo dự án trên Google Cloud.
Thiết lập môi trường
Trước khi sử dụng API của Google, bạn cần bật các API đó trong một dự án Google Cloud. Bạn có thể bật một hoặc nhiều API trong một dự án Google Cloud.Trong Google Cloud Console, hãy bật API Google Chat, API Cloud Build, API Cloud Functions, API Cloud Pub/Sub, API Cloud Logging, API Artifact Registry và API Cloud Run.
Tạo và triển khai một Chức năng trên đám mây
Tạo và triển khai một Hàm trên đám mây để tạo thẻ Chat (Trò chuyện) có tên hiển thị và hình đại diện của người gửi. Khi ứng dụng Chat nhận được một tin nhắn, ứng dụng sẽ chạy hàm và phản hồi bằng thẻ.
Để tạo và triển khai hàm cho ứng dụng Chat, hãy hoàn tất các bước sau:
Node.js
Trong Google Cloud Console, hãy chuyển đến trang Cloud Functions:
Đảm bảo bạn đã chọn dự án cho ứng dụng Chat.
Nhấp vào
Tạo hàm.Trên trang Tạo hàm, hãy thiết lập hàm:
- Trong Environment (Môi trường), hãy chọn Cloud Run Function (Hàm Cloud Run).
- Trong Function name (Tên hàm), hãy nhập
AddOnChatApp
. - Trong mục Khu vực, hãy chọn một khu vực.
- Trong phần Xác thực, hãy chọn Yêu cầu xác thực.
- Nhấp vào Tiếp theo.
Trong Runtime (Thời gian chạy), hãy chọn phiên bản Node.js mới nhất.
Trong Source code (Mã nguồn), hãy chọn Inline Editor (Trình chỉnh sửa cùng dòng).
Trong Entry point (Điểm truy cập), hãy xoá văn bản mặc định rồi nhập
avatarApp
.Thay thế nội dung của
index.js
bằng mã sau:/** * 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 } }] }] } }] }}}}}); };
Nhấp vào Triển khai.
Python
Trong Google Cloud Console, hãy chuyển đến trang Cloud Functions:
Đảm bảo bạn đã chọn dự án cho ứng dụng Chat.
Nhấp vào
Tạo hàm.Trên trang Tạo hàm, hãy thiết lập hàm:
- Trong Environment (Môi trường), hãy chọn Cloud Run Function (Hàm Cloud Run).
- Trong Function name (Tên hàm), hãy nhập
AddOnChatApp
. - Trong mục Khu vực, hãy chọn một khu vực.
- Trong phần Xác thực, hãy chọn Yêu cầu xác thực.
- Nhấp vào Tiếp theo.
Trong Thời gian chạy, hãy chọn phiên bản Python mới nhất.
Trong Source code (Mã nguồn), hãy chọn Inline Editor (Trình chỉnh sửa cùng dòng).
Trong Entry point (Điểm truy cập), hãy xoá văn bản mặc định rồi nhập
avatar_app
.Thay thế nội dung của
main.py
bằng mã sau: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 } }] }] } }] }}}}}
Nhấp vào Triển khai.
Java
Trong Google Cloud Console, hãy chuyển đến trang Cloud Functions:
Đảm bảo bạn đã chọn dự án cho ứng dụng Chat.
Nhấp vào
Tạo hàm.Trên trang Tạo hàm, hãy thiết lập hàm:
- Trong Environment (Môi trường), hãy chọn Cloud Run Function (Hàm Cloud Run).
- Trong Function name (Tên hàm), hãy nhập
AddOnChatApp
. - Trong mục Khu vực, hãy chọn một khu vực.
- Trong phần Xác thực, hãy chọn Yêu cầu xác thực.
- Nhấp vào Tiếp theo.
Trong Runtime (Thời gian chạy), hãy chọn phiên bản Java mới nhất.
Trong Source code (Mã nguồn), hãy chọn Inline Editor (Trình chỉnh sửa cùng dòng).
Trong Entry point (Điểm truy cập), hãy xoá văn bản mặc định rồi nhập
AvatarApp
.Đổi tên tệp Java mặc định thành
src/main/java/AvatarApp.java
.Thay thế nội dung của
AvatarApp.java
bằng mã sau: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; } }
Thay thế nội dung của
pom.xml
bằng mã sau:<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>
Nhấp vào Triển khai.
Trang chi tiết về Chức năng đám mây sẽ mở ra và hàm của bạn sẽ xuất hiện cùng với hai chỉ báo tiến trình: một chỉ báo cho bản dựng và một chỉ báo cho dịch vụ. Khi cả hai chỉ báo tiến trình biến mất và được thay thế bằng dấu kiểm, hàm của bạn sẽ được triển khai và sẵn sàng.
Uỷ quyền cho Google Chat gọi hàm của bạn
Để Uỷ quyền cho tiện ích bổ sung Google Workspace gọi hàm của bạn, hãy thêm tài khoản dịch vụ của tiện ích bổ sung Google Workspace với vai trò Trình gọi Cloud Run.
Trong Google Cloud Console, hãy chuyển đến trang Cloud Run:
Trong danh sách dịch vụ Cloud Run, hãy chọn hộp đánh dấu bên cạnh hàm nhận. (Đừng nhấp vào chính hàm đó.)
Nhấp vào Quyền. Bảng điều khiển Quyền sẽ mở ra.
Nhấp vào Thêm người đại diện.
Trong phần Bên giao đại lý mới, hãy nhập địa chỉ email của tài khoản dịch vụ Tiện ích Google Workspace được liên kết với dự án của bạn.
Trong phần Chọn vai trò, hãy chọn Cloud Run > Trình gọi Cloud Run.
Nhấp vào Lưu.
Định cấu hình tiện ích bổ sung
Sau khi triển khai Hàm trên đám mây, hãy làm theo các bước sau để tạo một tiện ích bổ sung và triển khai ứng dụng Google Chat:
Trong bảng điều khiển Google Cloud, hãy nhấp vào biểu tượng Trình đơn > Hàm trên đám mây.
Đảm bảo bạn đã chọn dự án mà bạn đã bật Hàm trên đám mây.
Trong danh sách hàm, hãy nhấp vào AddOnChatApp.
Nhấp vào thẻ Trình kích hoạt.
Trong mục HTTPS, hãy sao chép URL.
Tìm "Google Chat API" rồi nhấp vào Google Chat API, sau đó nhấp vào Quản lý.
Nhấp vào Cấu hình rồi thiết lập ứng dụng Google Chat:
- Trong App name (Tên ứng dụng), hãy nhập
Add-on Chat app
. - Trong URL hình đại diện, hãy nhập
https://developers.google.com/chat/images/quickstart-app-avatar.png
. - Trong phần Description (Nội dung mô tả), hãy nhập
Add-on Chat app
. - Trong phần Chức năng, hãy chọn Nhận tin nhắn 1:1 và Tham gia không gian và cuộc trò chuyện nhóm.
- Trong phần Cài đặt kết nối, hãy chọn URL điểm cuối HTTP rồi dán URL cho trình kích hoạt Hàm trên đám mây vào hộp.
- Trong mục Đối tượng xác thực, hãy chọn URL điểm cuối HTTP.
- Trong phần Chế độ hiển thị, hãy chọn Cung cấp ứng dụng Google Chat này cho một số người và nhóm cụ thể trong miền của bạn rồi nhập địa chỉ email của bạn.
- Trong mục Nhật ký, hãy chọn Ghi lỗi vào nhật ký.
- Trong App name (Tên ứng dụng), hãy nhập
Nhấp vào Lưu.
Ứng dụng Chat đã sẵn sàng nhận và trả lời tin nhắn trên Chat.
Kiểm thử ứng dụng Chat
Để kiểm thử ứng dụng Chat, hãy mở một không gian tin nhắn trực tiếp bằng ứng dụng Chat và gửi tin nhắn:
Mở Google Chat bằng tài khoản Google Workspace mà bạn đã cung cấp khi thêm chính mình làm người kiểm thử đáng tin cậy.
- Nhấp vào Cuộc trò chuyện mới.
- Trong trường Thêm 1 người trở lên, hãy nhập tên của ứng dụng Chat.
Chọn ứng dụng Chat trong kết quả. Một tin nhắn trực tiếp sẽ mở ra.
- Trong tin nhắn trực tiếp mới với ứng dụng, hãy nhập
Hello
rồi nhấn vàoenter
.
Tin nhắn của ứng dụng Chat chứa một thẻ hiển thị tên và hình đại diện của người gửi, như minh hoạ trong hình sau:
Để thêm người kiểm thử đáng tin cậy và tìm hiểu thêm về cách kiểm thử các tính năng tương tác, hãy xem bài viết Kiểm thử các tính năng tương tác cho ứng dụng Google Chat.
Khắc phục sự cố
Khi ứng dụng Google Chat hoặc thẻ trả về lỗi, giao diện Chat sẽ hiển thị thông báo "Đã xảy ra lỗi". hoặc "Không thể xử lý yêu cầu của bạn". Đôi khi, giao diện người dùng Chat không hiển thị thông báo lỗi nào, nhưng ứng dụng Chat hoặc thẻ lại tạo ra kết quả không mong muốn; ví dụ: thông báo thẻ có thể không xuất hiện.
Mặc dù thông báo lỗi có thể không hiển thị trong giao diện người dùng Chat, nhưng bạn có thể xem thông báo lỗi mô tả và dữ liệu nhật ký để khắc phục lỗi khi bật tính năng ghi nhật ký lỗi cho ứng dụng Chat. Để được trợ giúp xem, gỡ lỗi và khắc phục lỗi, hãy xem bài viết Khắc phục và khắc phục lỗi Google Chat.
Dọn dẹp
Để tránh bị tính phí cho tài khoản Google Cloud của bạn đối với các tài nguyên được sử dụng trong hướng dẫn này, bạn nên xoá dự án trên Google Cloud.
- Trong Google Cloud Console, hãy chuyển đến trang Quản lý tài nguyên. Nhấp vào biểu tượng Trình đơn > IAM và quản trị > Quản lý tài nguyên.
- Trong danh sách dự án, hãy chọn dự án bạn muốn xoá rồi nhấp vào biểu tượng Xoá .
- Trong hộp thoại, hãy nhập mã dự án rồi nhấp vào Shut down (Tắt) để xoá dự án.