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

Trang này giải thích cách tạo ứng dụng Chat qua HTTP. Có nhiều cách để triển khai cấu trúc này. Trên Google Cloud, bạn có thể sử dụng Cloud Functions, Cloud Run và App Engine. Trong phần bắt đầu nhanh này, 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 này, bạn định cấu hình Chat để tích hợp 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ơ đồ dưới đây:

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

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:

  1. 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.
  2. Yêu cầu HTTP được gửi tới máy chủ web là một đám mây hoặc hệ thống tại chỗ chứa ứng dụng Chat logic.
  3. 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ợ).
  4. Máy chủ web gửi phản hồi HTTP trở lại dịch vụ ứng dụng Chat trong Chat.
  5. Phản hồi được gửi đến người dùng.
  6. Nếu muốn, ứng dụng Chat có thể gọi API Chat để đăng thông báo một cách không đồng bộ hoặc thực hiện các thao tác khác các toán tử.

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 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 Chức năng đám mây.
  • Xuất bản ứng dụng lên Chat.
  • Kiểm thử ứng dụng.

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

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

Trước khi sử dụng các API của Google, bạn cần bật các API này trong một dự án trê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.

    Bật API

Tạo và triển khai một Chức năng trên đám mây

Tạo và triển khai Chức năng đám mây tạo thẻ Chat bằng tên hiển thị và hình đại diện của người gửi. Khi nhận được tin nhắn, ứng dụng Chat sẽ chạy hàm và phản hồi bằng thẻ.

Cách tạo và triển khai chức năng cho ứng dụng Chat: hoàn thành các bước sau:

Node.js

  1. Trong Google Cloud Console, hãy chuyển đến trang Cloud Functions:

    Chuyển đến Cloud Functions

    Hãy đảm bảo dự án cho ứng dụng Chat của bạn đã chọn.

  2. Nhấp vào Create Function (Tạo hàm).

  3. Trên trang Tạo hàm, hãy thiết lập hàm:

    1. Trong mục Môi trường, hãy chọn thế hệ thứ 2.
    2. Trong Tên hàm, hãy nhập QuickStartChatApp.
    3. Trong mục Khu vực, hãy chọn một khu vực.
    4. Trong phần Xác thực, chọn Yêu cầu xác thực.
    5. Nhấp vào Tiếp theo.
  4. Trong Thời gian chạy, hãy chọn phiên bản mới nhất của Node.js.

  5. Trong Mã nguồn, chọn Trình chỉnh sửa cùng dòng.

  6. Trong Điểm truy cập, hãy xoá văn bản mặc định rồi nhập avatarApp.

  7. Thay thế nội dung của index.js bằng mã sau:

    node/avatar-app/index.js
    // The ID of the slash command "/about".
    // It's not enabled by default, set to the actual ID to enable it. You need to
    // use the same ID as set in the Google Chat API configuration.
    const ABOUT_COMMAND_ID = "";
    
    /**
     * 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.message) {
        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 event = req.body;
    
      // Checks for the presence of a slash command in the message.
      if (event.message.slashCommand) {
        // Executes the slash command logic based on its ID.
        // Slash command IDs are set in the Google Chat API configuration.
        switch (event.message.slashCommand.commandId) {
          case ABOUT_COMMAND_ID:
            return res.send({
              privateMessageViewer: event.user,
              text: 'The Avatar app replies to Google Chat messages.'
            });
        }
      }
    
      const sender = req.body.message.sender.displayName;
      const image = req.body.message.sender.avatarUrl;
      const data = createMessage(sender, image);
      res.send(data);
    };
    
    /**
     * Creates a card with two widgets.
     * 
     * @param {string} displayName the sender's display name
     * @param {string} avatarUrl the URL for the sender's avatar
     * @return {Object} a card with the user's avatar.
     */
    function createMessage(displayName, 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 }
            }]}]
          }
        }]
      };
    }

  8. Nhấp vào Triển khai.

Python

  1. Trong bảng điều khiển Google Cloud, hãy truy cập vào trang Cloud Functions:

    Chuyển đến Cloud Functions

    Hãy đảm bảo dự án cho ứng dụng Chat của bạn đã chọn.

  2. Nhấp vào Create Function (Tạo hàm).

  3. Trên trang Tạo hàm, hãy thiết lập hàm:

    1. Trong mục Môi trường, hãy chọn thế hệ thứ 2.
    2. Trong Tên hàm, hãy nhập QuickStartChatApp.
    3. Trong mục Khu vực, hãy chọn một khu vực.
    4. Trong phần Xác thực, chọn Yêu cầu xác thực.
    5. Nhấp vào Tiếp theo.
  4. Trong phần Thời gian chạy, hãy chọn phiên bản Python mới nhất.

  5. Trong Mã nguồn, chọn Trình chỉnh sửa cùng dòng.

  6. Trong Entry point (Điểm truy cập), hãy xoá văn bản mặc định rồi nhập avatar_app.

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

    python/avatar-app/main.py
    from typing import Any, Mapping
    
    import flask
    import functions_framework
    
    # The ID of the slash command "/about".
    # It's not enabled by default, set to the actual ID to enable it. You need to
    # use the same ID as set in the Google Chat API configuration.
    ABOUT_COMMAND_ID = ""
    
    @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)
    
      # Checks for the presence of a slash command in the message.
      if "slashCommand" in request_json["message"]:
        # Executes the slash command logic based on its ID.
        # Slash command IDs are set in the Google Chat API configuration.
        if request_json["message"]["slashCommand"]["commandId"] == ABOUT_COMMAND_ID:
          return {
            "privateMessageViewer": request_json["user"],
            "text": 'The Avatar app replies to Google Chat messages.'
          }
    
      display_name = request_json["message"]["sender"]["displayName"]
      avatar = request_json["message"]["sender"]["avatarUrl"]
      response = create_message(name=display_name, image_url=avatar)
      return response
    
    
    def create_message(name: str, image_url: str) -> Mapping[str, Any]:
      """Google Cloud Function that handles requests from Google Chat
    
      Args:
          str name: the sender's display name.
          str image_url: the URL for the sender's avatar.
    
      Returns:
          Mapping[str, Any]: a card with the user's avatar.
      """
      return {
        "text": "Here's your avatar",
        "cardsV2": [{
          "cardId": "avatarCard",
          "card": {
              "name": "Avatar Card",
              "header": { "title": f"Hello {name}!" },
              "sections": [{
                "widgets": [{
                  "textParagraph": { "text": "Your avatar picture:" }
                }, {
                  "image": { "imageUrl": image_url }
                }]
              }]
          }
        }]
      }

  8. Nhấp vào Triển khai.

Java

  1. Trong Google Cloud Console, hãy chuyển đến trang Cloud Functions:

    Chuyển đến Cloud Functions

    Hãy đảm bảo dự án cho ứng dụng Chat của bạn đã chọn.

  2. Nhấp vào Create Function (Tạo hàm).

  3. Trên trang Tạo hàm, hãy thiết lập hàm:

    1. Trong mục Môi trường, hãy chọn thế hệ thứ 2.
    2. Trong Tên hàm, hãy nhập QuickStartChatApp.
    3. Trong mục Khu vực, hãy chọn một khu vực.
    4. Trong phần Xác thực, chọn Yêu cầu xác thực.
    5. Nhấp vào Tiếp theo.
  4. Trong Thời gian chạy, hãy chọn phiên bản Java mới nhất.

  5. Trong Mã nguồn, chọn Trình chỉnh sửa cùng dòng.

  6. Trong Điểm truy cập, hãy xoá văn bản mặc định rồi nhập App.

  7. Đổi tên src/main/java/com/example/Example.java thành src/main/java/App.java.

  8. Thay thế nội dung của App.java bằng mã sau:

    java/avatar-app/src/main/java/App.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 App implements HttpFunction {
      private static final Gson gson = new Gson();
    
      // The ID of the slash command "/about".
      // It's not enabled by default, set to the actual ID to enable it. You need to
      // use the same ID as set in the Google Chat API configuration.
      private static final String ABOUT_COMMAND_ID = "";
    
      @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("message")) {
          response.getWriter().write("Hello! This function must be called from Google Chat.");
          return;
        }
    
        // Checks for the presence of a slash command in the message.
        if (body.getAsJsonObject("message").has("slashCommand")) {
          // Executes the slash command logic based on its ID.
          // Slash command IDs are set in the Google Chat API configuration.
          JsonObject slashCommand = body.getAsJsonObject("message").getAsJsonObject("slashCommand");
          switch (slashCommand.get("commandId").getAsString()) {
            case ABOUT_COMMAND_ID:
            JsonObject aboutMessage = new JsonObject();
            aboutMessage.addProperty("text", "The Avatar app replies to Google Chat messages.");
            aboutMessage.add("privateMessageViewer", body.getAsJsonObject("user"));
              response.getWriter().write(gson.toJson(aboutMessage));
              return;
          }
        }
    
        JsonObject sender = body.getAsJsonObject("message").getAsJsonObject("sender");
        String displayName = sender.has("displayName") ? sender.get("displayName").getAsString() : "";
        String avatarUrl = sender.has("avatarUrl") ? sender.get("avatarUrl").getAsString() : "";
        Message message = createMessage(displayName, avatarUrl);
        response.getWriter().write(gson.toJson(message));
      }
    
      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("previewLink");
        cardWithId.setCard(card);
    
        Message message = new Message();
        message.setText("Here's your avatar");
        message.setCardsV2(List.of(cardWithId));
    
        return message;
      }
    }

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

    java/avatar-app/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.1</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 11 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>

  10. 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 các chỉ báo tiến trình sẽ biến mất và được thay thế bằng một dấu kiểm. Đây là chức năng của bạn đã được triển khai và sẵn sàng.

Cho phép Google Chat gọi chức năng của bạn

Để cho phép Google Chat gọi chức năng của bạn, hãy thêm Google Chat tài khoản dịch vụ có vai trò Cloud Run Invoker.

  1. Trong bảng điều khiển Google Cloud, hãy truy cập vào trang Cloud Run:

    Chuyển đến Cloud Run

  2. Trong danh sách dịch vụ Cloud Run, hãy chọn hộp đánh dấu bên cạnh dịch vụ nhận . (Đừng nhấp vào chính hàm đó.)

  3. Nhấp vào Quyền. Bảng điều khiển Quyền sẽ mở ra.

  4. Nhấp vào Thêm người đại diện.

  5. Trong phần New principals (Tài khoản chính mới), hãy nhập chat@system.gserviceaccount.com.

  6. Trong phần Chọn vai trò, hãy chọn Cloud Run > Trình gọi tắt Cloud Run.

  7. Nhấp vào Lưu.

Phát hành ứng dụng lên Google Chat

Sau khi triển khai Hàm trên đám mây, hãy làm theo các bước sau để biến hàm đó thành ứng dụng Google Chat:

  1. Trong bảng điều khiển Google Cloud, hãy nhấp vào biểu tượng Trình đơn &gt; Chức năng đám mây.

    Chuyển đến Cloud Functions

    Đảm bảo rằng dự án mà bạn đã bật Cloud Functions đã chọn.

  2. Trong danh sách chức năng, hãy nhấp vào QuickStartChatApp.

  3. Nhấp vào thẻ Trình kích hoạt.

  4. Trong phần HTTPS, hãy sao chép URL.

  5. Tìm "Google Chat API" rồi nhấp vào API Google Chat, rồi nhấp vào Quản lý.

    Chuyển đến Chat API

  6. 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 Quickstart App.
    2. Trong mục URL hình đại diện, hãy nhập https://developers.google.com/chat/images/quickstart-app-avatar.png.
    3. Trong phần Mô tả, hãy nhập Quickstart app.
    4. Trong phần Chức năng, hãy chọn Nhận tin nhắn 1:1Tham gia các không gian và cuộc trò chuyện nhóm.
    5. 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.
    6. Trong mục Đối tượng xác thực, hãy chọn URL điểm cuối HTTP.
    7. 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.
    8. Trong mục Nhật ký, hãy chọn Ghi lỗi vào nhật ký.
  7. 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 tin nhắn:

  1. Mở Google Chat bằng tài khoản Google Workspace mà bạn khi bạn tự thêm chính mình làm người kiểm tra đáng tin cậy.

    Chuyển đến Google Chat

  2. Nhấp vào Cuộc trò chuyện mới.
  3. Trong trường Thêm 1 hoặc nhiều người, nhập tên của Ứng dụng Chat.
  4. Chọn ứng dụng Chat trong kết quả. Một tin nhắn trực tiếp sẽ mở ra.

  5. 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ào enter.

Phản hồi của ứng dụng Chat chứa một thông báo dạng 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:

Ứng dụng Chat phản hồi bằng một thẻ có tên hiển thị và hình ả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ề 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 một ứng dụng Google Chat hoặc card trả về một lỗi, thì phương thức Giao diện Chat hiển thị một thông báo với nội dung "Đã 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í vào tài khoản Google Cloud của bạn cho tài nguyên được sử dụng trong hướng dẫn này, chúng tôi khuyên bạn nên xóa Dự án trên đám mây.

  1. Trong bảng điều khiển Google Cloud, hãy chuyển đến trang Quản lý tài nguyên. Nhấp chuột Thực đơn &gt; IAM và Quản trị viên &gt; Quản lý tài nguyên.

    Chuyển đến Trình quản lý tài nguyên

  2. Trong danh sách dự án, hãy chọn dự án mà bạn muốn xoá rồi nhấp vào Xoá .
  3. Trong hộp thoại, hãy nhập mã dự án rồi nhấp vào Tắt để xoá dự án.