Dịch vụ trò chuyện nâng cao

quản lý phòng, thành viên và tin nhắn trong Chat.

Dịch vụ Chat nâng cao cho phép bạn sử dụng API Google Chat trong Google Apps Script. API này cho phép tập lệnh tìm, tạo và sửa đổi phòng Chat, thêm hoặc xoá thành viên khỏi phòng, cũng như đọc hoặc đăng tin nhắn có văn bản, thẻ, tệp đính kèm và biểu tượng cảm xúc.

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

Đây là một dịch vụ nâng cao mà bạn phải bật trước khi sử dụng.

Tài liệu tham khảo

Để biết thêm thông tin về dịch vụ này, hãy xem tài liệu tham khảo API Chat . Giống như tất cả các dịch vụ nâng cao trong Apps Script, dịch vụ Chat sử dụng cùng các đối tượng, phương thức và tham số như API công khai.

Mã mẫu

Các mẫu này cho thấy cách thực hiện các hành động API Google Chat phổ biến bằng dịch vụ nâng cao.

Đăng tin nhắn bằng thông tin xác thực người dùng

Ví dụ sau đây minh hoạ cách đăng tin nhắn lên một phòng Chat thay mặt cho người dùng.

  1. Thêm phạm vi uỷ quyền chat.messages.create vào tệp appsscript.json của dự án Apps Script:

    "oauthScopes": [
  "https://www.googleapis.com/auth/chat.messages.create"
]

  2. Thêm một hàm như hàm này vào mã của dự án Apps Script:

    advanced/chat.gs
    /**
 * Posts a new message to the specified space on behalf of the user.
 * @param {string} spaceName The resource name of the space.
 */
function postMessageWithUserCredentials(spaceName) {
  try {
    const message = { text: "Hello world!" };
    Chat.Spaces.Messages.create(message, spaceName);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log("Failed to create message with error %s", err.message);
  }
}

Đăng tin nhắn bằng thông tin xác thực ứng dụng

Ví dụ sau đây minh hoạ cách đăng tin nhắn lên một phòng Chat thay mặt cho ứng dụng. Việc sử dụng dịch vụ Chat nâng cao với tài khoản dịch vụ không yêu cầu bạn chỉ định phạm vi uỷ quyền trong appsscript.json. Để biết thông tin chi tiết về việc xác thực bằng tài khoản dịch vụ, hãy xem bài viết Xác thực dưới dạng ứng dụng Google Chat.

advanced/chat.gs
/**
 * Posts a new message to the specified space on behalf of the app.
 * @param {string} spaceName The resource name of the space.
 */
function postMessageWithAppCredentials(spaceName) {
  try {
    // See https://developers.google.com/chat/api/guides/auth/service-accounts
    // for details on how to obtain a service account OAuth token.
    const appToken = getToken_();
    const message = { text: "Hello world!" };
    Chat.Spaces.Messages.create(
      message,
      spaceName,
      {},
      // Authenticate with the service account token.
      { Authorization: `Bearer ${appToken}` },
    );
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log("Failed to create message with error %s", err.message);
  }
}

Lấy một phòng

Ví dụ sau đây minh hoạ cách lấy thông tin về một phòng Chat.

  1. Thêm phạm vi uỷ quyền chat.spaces.readonly vào tệp appsscript.json của dự án Apps Script:

    "oauthScopes": [
  "https://www.googleapis.com/auth/chat.spaces.readonly"
]

  2. Thêm một hàm như hàm này vào mã của dự án Apps Script:

    advanced/chat.gs
    /**
 * Gets information about a Chat space.
 * @param {string} spaceName The resource name of the space.
 */
function getSpace(spaceName) {
  try {
    const space = Chat.Spaces.get(spaceName);
    console.log("Space display name: %s", space.displayName);
    console.log("Space type: %s", space.spaceType);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log("Failed to get space with error %s", err.message);
  }
}

Tạo một phòng

Ví dụ sau đây minh hoạ cách tạo một phòng Chat.

  1. Thêm phạm vi uỷ quyền chat.spaces.create vào tệp appsscript.json của dự án Apps Script:

    "oauthScopes": [
  "https://www.googleapis.com/auth/chat.spaces.create"
]

  2. Thêm một hàm như hàm này vào mã của dự án Apps Script:

    advanced/chat.gs
    /**
 * Creates a new Chat space.
 */
function createSpace() {
  try {
    const space = { displayName: "New Space", spaceType: "SPACE" };
    Chat.Spaces.create(space);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log("Failed to create space with error %s", err.message);
  }
}

Liệt kê tư cách thành viên

Ví dụ sau đây minh hoạ cách liệt kê tất cả thành viên của một phòng Chat.

  1. Thêm phạm vi uỷ quyền chat.memberships.readonly vào tệp appsscript.json của dự án Apps Script:

    "oauthScopes": [
  "https://www.googleapis.com/auth/chat.memberships.readonly"
]

  2. Thêm một hàm như hàm này vào mã của dự án Apps Script:

    advanced/chat.gs
    /**
 * Lists all the members of a Chat space.
 * @param {string} spaceName The resource name of the space.
 */
function listMemberships(spaceName) {
  let response;
  let pageToken = null;
  try {
    do {
      response = Chat.Spaces.Members.list(spaceName, {
        pageSize: 10,
        pageToken: pageToken,
      });
      if (!response.memberships || response.memberships.length === 0) {
        pageToken = response.nextPageToken;
        continue;
      }
      for (const membership of response.memberships) {
        console.log(
          "Member: %s, Role: %s",
          membership.member.displayName,
          membership.role,
        );
      }
      pageToken = response.nextPageToken;
    } while (pageToken);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log("Failed with error %s", err.message);
  }
}

Khắc phục sự cố

Nếu bạn gặp phải Error 400: invalid_scope với thông báo lỗi Some requested scopes cannot be shown (Không thể hiển thị một số phạm vi được yêu cầu), điều đó có nghĩa là bạn chưa chỉ định phạm vi uỷ quyền nào trong tệp appsscript.json của dự án Apps Script. Trong hầu hết các trường hợp, Apps Script sẽ tự động xác định những phạm vi mà một tập lệnh cần, nhưng khi sử dụng dịch vụ Chat nâng cao, bạn phải thêm theo cách thủ công các phạm vi uỷ quyền mà tập lệnh sử dụng vào tệp kê khai của dự án Apps Script. Xem phần Đặt phạm vi rõ ràng.

Để giải quyết lỗi này, hãy thêm các phạm vi uỷ quyền thích hợp vào tệp appsscript.json của dự án Apps Script trong mảng oauthScopes. Ví dụ: để gọi phương thức spaces.messages.create , hãy thêm như sau:

"oauthScopes": [
  "https://www.googleapis.com/auth/chat.messages.create"
]

Giới hạn và lưu ý

Dịch vụ Chat nâng cao không hỗ trợ:

Để tải tệp đính kèm tin nhắn xuống hoặc gọi phương thức bản dùng thử cho nhà phát triển, hãy sử dụng UrlFetchApp thay thế.