Trang này được dịch bởi Cloud Translation API.

Tạo ứng dụng Google Chat loại HTTP

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 dịch vụ HTTP.

Hướng dẫn bắt đầu nhanh này hướng dẫn bạn cách tạo một dịch vụ HTTP bằng các dịch vụ của Google Cloud. Để tạo ứng dụng Chat, bạn viết và triển khai một hàm Cloud Run mà ứng dụng Chat dùng để phản hồi tin nhắn của người dùng.

Với cấu trúc HTTP, bạn có thể định cấu hình Chat để tích hợp với Google Cloud hoặc một máy chủ tại chỗ bằng cách sử dụng HTTP, như minh hoạ trong sơ đồ sau:

Cấu trúc của một ứng dụng Chat sử dụng dịch vụ web trong máy chủ tại cơ sở.

Trong sơ đồ trước đó, một người dùng tương tác với ứng dụng HTTP Chat sẽ có luồng thông tin như sau:

Người dùng gửi tin nhắn trong Chat cho một ứng dụng Chat, có thể là 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ỗ có chứa logic của ứng dụng Chat.
Bạn có thể tích hợp logic của ứng dụng Chat 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ụ phát hành vé).
Máy chủ web gửi phản hồi HTTP trở lại dịch vụ ứng dụng Chat trong Chat.
Câu trả lời được gửi đến người dùng.
Bạn cũng có thể dùng ứng dụng Chat để gọi Chat API nhằm đă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 giú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 trò chuyện 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 hàm Cloud Run.
Định cấu hình một 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 Business hoặc Enterprise có quyền truy cập vào Google Chat.
Một dự án trê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 phần 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 Cloud Build API, Cloud Functions API, Cloud Pub/Sub API, Cloud Logging API, Artifact Registry API và Cloud Run API.

Bật các API

Tạo và triển khai một hàm Cloud Run

Tạo và triển khai một hàm Cloud Run để tạo thẻ Chat 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 Run:

Chuyển đến Cloud Run

Đảm bảo rằng bạn đã chọn dự án cho ứng dụng Chat.
Nhấp vào Viết một hàm.
Trên trang Tạo dịch vụ, hãy thiết lập hàm của bạn:
1. Trong trường Tên dịch vụ, hãy nhập addonchatapp.
2. Trong danh sách Khu vực, hãy chọn một khu vực.
3. Trong danh sách Runtime (Thời gian chạy), hãy chọn phiên bản Node.js mới nhất.
4. Trong phần Xác thực, hãy chọn Yêu cầu xác thực.
5. Nhấp vào Tạo rồi đợi Cloud Run tạo dịch vụ. Bảng điều khiển sẽ chuyển hướng bạn đến thẻ Nguồn.

Trong thẻ Nguồn:

Trong Đ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 đoạn mã sau:

/**
 * Google Cloud Run 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
 */
import { http } from '@google-cloud/functions-framework';

http('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 }
                    }]
                }]
            }
        }]
    }}}}});
});

Thay thế nội dung của package.json bằng đoạn mã sau:

{
  "name": "avatar-app",
  "version": "1.0.0",
  "description": "Google Chat Avatar App",
  "main": "index.js",
  "type": "module",
  "scripts": {
    "start": "node index.js"
  },
  "dependencies": {
    "@google-cloud/functions-framework": "^3.0.0"
  }
}

Nhấp vào Lưu và triển khai lại.

Python

Trong Google Cloud Console, hãy chuyển đến trang Cloud Run:

Chuyển đến Cloud Run

Đảm bảo rằng bạn đã chọn dự án cho ứng dụng Chat.
Nhấp vào Viết một hàm.
Trên trang Tạo dịch vụ, hãy thiết lập hàm của bạn:
1. Trong trường Tên dịch vụ, hãy nhập addonchatapp.
2. Trong danh sách Khu vực, hãy chọn một khu vực.
3. Trong danh sách Runtime (Thời gian chạy), hãy chọn phiên bản Python gần đây nhất.
4. Trong phần Xác thực, hãy chọn Yêu cầu xác thực.
5. Nhấp vào Tạo rồi đợi Cloud Run tạo dịch vụ. Bảng điều khiển sẽ chuyển hướng bạn đến thẻ Nguồn.

Trong thẻ Nguồn:

Trong Đ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 đoạn 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 Run 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 Lưu và triển khai lại.

Java

Trong Google Cloud Console, hãy chuyển đến trang Cloud Run:

Chuyển đến Cloud Run

Đảm bảo rằng bạn đã chọn dự án cho ứng dụng Chat.
Nhấp vào Viết một hàm.
Trên trang Tạo dịch vụ, hãy thiết lập hàm của bạn:
1. Trong trường Tên dịch vụ, hãy nhập addonchatapp.
2. Trong danh sách Khu vực, hãy chọn một khu vực.
3. Trong danh sách Runtime (Thời gian chạy), hãy chọn phiên bản Java mới nhất.
4. Trong phần Xác thực, hãy chọn Yêu cầu xác thực.
5. Nhấp vào Tạo rồi đợi Cloud Run tạo dịch vụ. Bảng điều khiển sẽ chuyển hướng bạn đến thẻ Nguồn.

Trong thẻ Nguồn:

Trong Đ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/gcfv2/AvatarApp.java.
Thay thế nội dung của AvatarApp.java bằng đoạn 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 đoạn 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 Lưu và triển khai lại.

Trang chi tiết về dịch vụ Cloud Run sẽ mở ra. Chờ hàm triển khai.

Định cấu hình tiện ích bổ sung

Sau khi triển khai hàm Cloud Run, 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 Google Cloud Console, hãy chuyển đến trang Cloud Run:

Chuyển đến Cloud Run

Đảm bảo rằng bạn đã chọn dự án mà bạn đã bật Cloud Run.
Trong danh sách hàm, hãy nhấp vào addonchatapp.
Trên trang Chi tiết dịch vụ, hãy sao chép URL cho hàm. URL này kết thúc bằng run.app.
Trong trường tìm kiếm của Google Cloud, hãy tìm "Google Chat API", sau đó nhấp vào Google Chat API rồi nhấp vào Quản lý.

Chuyển đến Chat API
Nhấp vào Cấu hình rồi thiết lập ứng dụng Google Chat:
1. Trong Tên ứng dụng, hãy nhập Add-on Chat app.
2. Trong URL hình đại diện, hãy nhập https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png.
3. Trong phần Nội dung mô tả, hãy nhập Add-on Chat app.
4. Trong phần Chức năng, hãy chọn Tham gia không gian và cuộc trò chuyện nhóm.
5. Trong phần Connection settings (Chế độ cài đặt kết nối), hãy chọn HTTP endpoint URL (URL điểm cuối HTTP).
6. Sao chép Email tài khoản dịch vụ. Bạn cần có email này khi uỷ quyền cho tiện ích bổ sung gọi hàm của bạn.
7. Trong mục Điều kiện kích hoạt, hãy chọn Sử dụng một URL điểm cuối HTTP chung cho tất cả điều kiện kích hoạt rồi dán URL cho điều kiện kích hoạt hàm Cloud Run vào hộp.
8. 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.
9. Trong mục Nhật ký, hãy chọn Ghi lỗi vào Nhật ký.
Nhấp vào Lưu.

Tiếp theo, hãy cho phép ứng dụng Chat gọi hàm Cloud Run.

Uỷ quyền cho Google Chat gọi hàm của bạn

Để cho phép 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ụ tiện ích bổ sung Google Workspace bằng vai trò Trình gọi dịch vụ Cloud Run.

Trong Google Cloud Console, hãy chuyển đến trang Cloud Run:

Chuyển đến 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 đối tượng chính.
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 bổ sung Google Workspace được liên kết với ứng dụng Chat của bạn.

Địa chỉ email của tài khoản dịch vụ nằm trên trang cấu hình Chat API, trong phần Connection settings (Cài đặt kết nối) > HTTP endpoint URL (URL điểm cuối HTTP) > Service Account Email (Địa chỉ email của tài khoản dịch vụ):

Chuyển đến phần cấu hình Chat API
Trong phần Chọn vai trò, hãy chọn Cloud Run > Cloud Run Service Invoker (Đối tượng gọi dịch vụ Cloud Run).
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 nhắn tin trực tiếp bằng ứng dụng Chat rồi gửi một 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ử tin cậy.

Truy cập vào Google Chat
Nhấp vào biểu tượng Cuộc trò chuyện mới.
Trong trường Thêm một hoặc nhiều người, 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.

Lưu ý: Nếu bạn không thấy ứng dụng Chat trong danh sách kết quả, hãy đảm bảo rằng bạn đã thêm tài khoản Google Workspace vào chế độ cài đặt Chế độ hiển thị của trang Cấu hình Chat API trong Google Cloud Console.
Trong tin nhắn trực tiếp mới với ứng dụng, hãy nhập Hello rồi nhấn enter.

Tin nhắn của ứng dụng Chat có 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 ảnh sau:

Ứng dụng Chat phản hồi bằng một thẻ có tên hiển thị và hình đại diện của người gửi

Để thêm người kiểm thử đáng tin cậy và tìm hiểu thêm về việc 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 một ứ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ị bất kỳ thông báo lỗi nào, nhưng ứng dụng hoặc thẻ Chat 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 xuất hiện trong giao diện người dùng Chat, nhưng bạn có thể sử dụng 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 lỗi trong Google Chat.

Dọn dẹp

Để tránh phát sinh phí cho tài khoản Google Cloud của bạn đối với các tài nguyên được dùng trong hướng dẫn này, bạn nên xoá dự án trên Cloud.

Thận trọng: Thao tác xoá dự án sẽ gây ra những tác động sau:

Mọi nội dung trong dự án sẽ bị xoá. Nếu đã dùng một dự án hiện có cho hướng dẫn này, thì khi xoá dự án đó, bạn cũng sẽ xoá mọi công việc khác mà bạn đã thực hiện trong dự án.
Mã dự án tuỳ chỉnh sẽ bị mất. Khi tạo dự án này, có thể bạn đã tạo một mã dự án tuỳ chỉnh mà bạn muốn sử dụng trong tương lai. Để giữ lại những URL sử dụng mã dự án (chẳng hạn như URL trên appspot.com), hãy xoá các tài nguyên đã chọn trong dự án thay vì xoá toàn bộ dự án.

Nếu bạn dự định khám phá nhiều hướng dẫn và hướng dẫn bắt đầu nhanh, thì việc sử dụng lại các dự án có thể giúp bạn tránh vượt quá hạn mức dự án.

Trong Google Cloud Console, hãy chuyển đến trang Quản lý tài nguyên. Nhấp vào Trình đơn > IAM và Quản trị viên > Quản lý tài nguyên.
Chuyển đến Resource Manager
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 Tắt để xoá dự án.

Tạo ứng dụng Google Chat loại HTTP Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Mục tiêu

Điều kiện tiên quyết

Thiết lập môi trường

Tạo và triển khai một hàm Cloud Run

Node.js

Python

Java

Định cấu hình tiện ích bổ sung

Uỷ quyền cho Google Chat gọi hàm của bạn

Kiểm thử ứng dụng Chat

Khắc phục sự cố

Dọn dẹp

Tạo ứng dụng Google Chat loại HTTP