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

Phát triển ứng dụng nhắn tin bằng Apps Script

Apps Script là một trong những cách nhanh nhất để tạo ứng dụng Chat cho Google Chat.

Bạn có thể thiết lập và chạy ứng dụng chỉ trong vài phút ngay trong trình duyệt.
Bạn không cần phải lo lắng về việc chạy và quản lý máy chủ, bảo trì liên tục hoặc chi phí hoạt động hay thậm chí là tải xuống và thiết lập môi trường phát triển.
Rất dễ gọi API Google – đặc biệt là APIGoogle Workspace – vì với Apps Script, không có tính năng tải xuống hoặc thiết lập, tính năng xác thực được xử lý tự động và lệnh gọi API Google cũng giống như lệnh gọi hàm gốc.

Hướng dẫn này giải thích cách tạo và đăng ký ứng dụng bằng Apps Script.

Bắt đầu

Phần này cho bạn biết cách tạo nhanh ứng dụng Chat bằng Apps Script.

Bước 1: Sao chép mẫu Apps Script

Cách dễ nhất để bắt đầu tạo ứng dụng Apps Script là sử dụng Mẫu trò chuyện. Thao tác này sẽ tạo một dự án Apps Script với các phương thức bạn cần. Sau đó, điền các phương thức theo yêu cầu để triển khai logic ứng dụng hoặc tích hợp với một ứng dụng bạn đã tạo. Mã sau đây là một ví dụ về mẫu được điền sẵn cho một ứng dụng đơn giản.

/**
 * Responds to a MESSAGE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onMessage(event) {
  var name = "";

  if (event.space.type == "DM") {
    name = "You";
  } else {
    name = event.user.displayName;
  }
  var message = name + " said \"" + event.message.text + "\"";

  return { "text": message };
}

/**
 * Responds to an ADDED_TO_SPACE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onAddToSpace(event) {
  var message = "";

  if (event.space.singleUserBotDm) {
    message = "Thank you for adding me to a DM, " + event.user.displayName + "!";
  } else {
    message = "Thank you for adding me to " +
        (event.space.displayName ? event.space.displayName : "this chat");
  }

  if (event.message) {
    // Bot added through @mention.
    message = message + " and you said: \"" + event.message.text + "\"";
  }

  return { "text": message };
}

/**
 * Responds to a REMOVED_FROM_SPACE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onRemoveFromSpace(event) {
  console.info("Bot removed from ",
      (event.space.name ? event.space.name : "this chat"));
}

Bước 2: Chỉnh sửa hàm onMessage

Theo mặc định, hàm onMessage trong mẫu trả về một đối tượng Message chứa văn bản và một thẻ đơn giản. Bạn có thể chỉnh sửa hàm này để trả về văn bản hoặc các tiện ích thẻ cụ thể.

function onMessage(e) {
  return { 'text': 'You said: \`' + e.message.text + '\`' };
}

Bước 3: Lấy mã triển khai

Trước khi có thể đăng ký ứng dụng của mình, bạn cần tải mã triển khai cho ứng dụng cụ thể này.

Nhấp vào Triển khai > Triển khai mới.
Trong phần Chọn loại, hãy nhấp vào Tiện ích bổ sung.
Điền vào các tuỳ chọn rồi nhấp vào Triển khai.
Trong mục "ID triển khai", hãy nhấp vào Sao chép.

Xem hướng dẫn Quản lý bản phát hành để tìm hiểu các phương pháp đề xuất để sử dụng mã triển khai.

Bước 4: Đăng ký ứng dụng

Bạn có thể đăng ký ứng dụng của mình trong bảng điều khiển Google Cloud. Trên màn hình đăng ký ứng dụng, bạn nhập tên ứng dụng, URL hình đại diện và nội dung mô tả. Để thử nghiệm, bạn có thể bật tính năng "Có thể nhắn tin trực tiếp cho ứng dụng" và "Ứng dụng hoạt động trong nhiều không gian có nhiều người dùng". Trong phần cài đặt kết nối, hãy chọn Apps Script và dán mã triển khai mà bạn đã sao chép ở bước trước.

Cài đặt kết nối để đăng ký ứng dụng của bạn.

Bước 5: Thử nghiệm ứng dụng

Để thử nghiệm ứng dụng, bạn có thể bắt đầu một tin nhắn trực tiếp với ứng dụng đó hoặc @đề cập đến ứng dụng trong Không gian. Khi bạn nói chuyện, nó sẽ phản hồi bất kỳ nội dung phản hồi Tin nhắn nào ở Bước 2. Vậy là xong!

Khái niệm về ứng dụng Apps Script

Sự kiện

Apps Script hỗ trợ một số chức năng của trình xử lý sự kiện mà ứng dụng của bạn có thể triển khai. Mỗi hàm xử lý một loại sự kiện khác nhau và mỗi hàm nhận được một đối số duy nhất e, là một đối tượng Sự kiện.

onAddToSpace(e): Hàm này được thực thi khi ứng dụng của bạn được thêm vào một không gian. Bạn có thể thêm trực tiếp ứng dụng của mình vào không gian hoặc thêm vào lượt đề cập bằng @. Trong trường hợp thứ hai, sự kiện e cũng sẽ có một thuộc tính message. Hàm này sẽ trả về một đối tượng Message. Đây thường là một thông báo chào mừng để cho người dùng cuối biết về ứng dụng của bạn hoặc phản hồi với lượt đề cập bằng @.
onMessage(e): Hàm này được gọi khi ứng dụng đã có trong không gian và người dùng đề cập đến ứng dụng bằng @. Hàm này sẽ trả về một đối tượng Message chứa phản hồi của ứng dụng.
onRemoveFromSpace(e): Hàm này được gọi khi người dùng xoá ứng dụng khỏi danh sách tin nhắn trực tiếp của họ hoặc khỏi một không gian. Giá trị trả về của hàm này bị bỏ qua vì ứng dụng của bạn đã bị xoá và không thể đăng thêm thông báo nào nữa.

Ví dụ sau sẽ triển khai onAddToSpace và onRemoveFromSpace:

// onAddToSpace() is invoked when the app is added to a space or when
// a user initiates / re-initiates a direct message with the app.
function onAddToSpace(e) {
  if (!e.space.singleUserBotDm) {
    return { 'text': 'Thanks for adding me to "' +
        (e.space.displayName ? e.space.displayName : "this chat") + '"!' };
  } else {
    return { 'text': 'Thanks for adding me to a DM!' };
  }
}
// onRemoveFromSpace() is invoked when app is removed from a space
// or when a user removes a direct message with the app.
function onRemoveFromSpace(e) {}

Xin lưu ý rằng e.space.displayName có thể không hiển thị trong tin nhắn trực tiếp giữa người với người.

Thẻ tương tác

Giống như các ứng dụng khác, ứng dụng Apps Script có thể hiển thị các thẻ có tính tương tác. Để tìm hiểu cách tạo thẻ tương tác, hãy xem tài liệu về thẻ tương tác. Điểm khác biệt chính đối với các ứng dụng Apps Script là chúng có thể chỉ định một phương thức cụ thể để gọi khi sự kiện onClick được kích hoạt bằng cách sử dụng các cặp khóa/giá trị action.actionMethodName và action.parameters.

Ủy quyền

Các ứng dụng Apps Script truy cập vào các tài nguyên được bảo vệ cần phải yêu cầu người dùng cấp quyền truy cập này vào lần đầu tiên họ chạy quyền truy cập này cho từng người dùng. Điều này không yêu cầu bạn thực hiện bất kỳ công việc nào, nhưng bạn cần lưu ý rằng người dùng có thể thấy hộp thoại uỷ quyền trong lần đầu tiên họ sử dụng ứng dụng của bạn.

Apps Script xử lý việc uỷ quyền ở cấp tập lệnh. Những ứng dụng yêu cầu uỷ quyền sẽ không thể thực hiện bất kỳ hành động nào cho đến khi người dùng cuối uỷ quyền cho ứng dụng. Nếu muốn ứng dụng hiển thị thông báo chào mừng khi ứng dụng chưa được uỷ quyền và được thêm trực tiếp vào không gian, bạn có thể chỉ định thông báo dự phòng trong tệp kê khai. Nếu ứng dụng của bạn yêu cầu logic khởi chạy, có thể bạn sẽ cần sao chép logic này trong thao tác onMessage. Ví dụ:

function onMessage(event) {
  var userProperties = PropertiesService.getUserProperties();
  if (!userProperties.getProperty('initialized')) {
    // handle the onAddToSpace initialization logic here.
    ...
    userProperties.setProperties({initialized: 'true'});
  }
  // Handle normal onMessage logic.
  ...
}

Thư không đồng bộ

Một số ứng dụng có thể cần gửi tin nhắn vào Google Chat dựa trên trình kích hoạt bên ngoài, chẳng hạn như Trình kích hoạt theo thời gian trong Apps Script.

Chúng tôi dự định tích hợp sẵn API Google Chat vào Apps Script cho trường hợp sử dụng này. Trong thời gian chờ đợi, cách duy nhất hiện tại để thực hiện việc này là thông qua API HTTP bên ngoài (xem tài liệu). Bạn cần có tài khoản dịch vụ Cloud (xem tài liệu) thông qua thư viện OAuth2 cho Apps Script.

Sau đây là ứng dụng mẫu đầy đủ đăng tin nhắn mỗi phút vào mọi không gian có chứa tin nhắn đó:

// Example app for Google Chat that demonstrates app-initiated messages
// by spamming the user every minute.
//
// This app makes use of the Apps Script OAuth2 library at:
//     https://github.com/googlesamples/apps-script-oauth2
//
// Follow the instructions there to add the library to your script.

// When added to a space, we store the space's ID in ScriptProperties.
function onAddToSpace(e) {
  PropertiesService.getScriptProperties()
      .setProperty(e.space.name, '');
  return {
    'text': 'Hi! I\'ll post a message here every minute. ' +
            'Please remove me after testing or I\'ll keep spamming you!'
  };
}

// When removed from a space, we remove the space's ID from ScriptProperties.
function onRemoveFromSpace(e) {
  PropertiesService.getScriptProperties()
      .deleteProperty(e.space.name);
}

// Add a trigger that invokes this function every minute via the
// "Edit > Current Project's Triggers" menu. When it runs, it will
// post in each space the app was added to.
function onTrigger() {
  var spaceIds = PropertiesService.getScriptProperties()
      .getKeys();
  var message = { 'text': 'Hi! It\'s now ' + (new Date()) };
  for (var i = 0; i < spaceIds.length; ++i) {
    postMessage(spaceIds[i], message);
  }
}
var SCOPE = 'https://www.googleapis.com/auth/chat.bot';
// The values below are copied from the JSON file downloaded upon
// service account creation.
// For SERVICE_ACCOUNT_PRIVATE_KEY, remember to include the BEGIN and END lines of the private key
var SERVICE_ACCOUNT_PRIVATE_KEY = '...';
var SERVICE_ACCOUNT_EMAIL = 'service-account@project-id.iam.gserviceaccount.com';

// Posts a message into the given space ID via the API, using
// service account authentication.
function postMessage(spaceId, message) {
  var service = OAuth2.createService('chat')
      .setTokenUrl('https://accounts.google.com/o/oauth2/token')
      .setPrivateKey(SERVICE_ACCOUNT_PRIVATE_KEY)
      .setClientId(SERVICE_ACCOUNT_EMAIL)
      .setPropertyStore(PropertiesService.getUserProperties())
      .setScope(SCOPE);
  if (!service.hasAccess()) {
    Logger.log('Authentication error: %s', service.getLastError());
    return;
  }
  var url = 'https://chat.googleapis.com/v1/' + spaceId + '/messages';
  UrlFetchApp.fetch(url, {
    method: 'post',
    headers: { 'Authorization': 'Bearer ' + service.getAccessToken() },
    contentType: 'application/json',
    payload: JSON.stringify(message),
  });
}

Tệp kê khai

Sau đây là ví dụ về tệp tệp kê khai của Apps Script phải đi kèm với tập lệnh.

Nếu không bắt đầu dự án từ mẫu Chat, bạn cần chỉnh sửa tệp kê khai để thêm đối tượng "chat": {} vào dự án đó.

Trong tệp kê khai, hãy đặt thời gian chạy thành Rhino: "runtimeVersion": "DEPRECATED_ES5". Các ứng dụng nhắn tin không hỗ trợ đầy đủ thời gian chạy Apps Script V8, vì vậy, nếu bạn chỉ định "runtimeVersion": "V8", ứng dụng Chat của bạn có thể gặp lỗi không ổn định. Ví dụ: cấu trúc phản hồi JSON có thể thay đổi theo tình huống bất ngờ cho các ứng dụng nhắn tin được tạo bằng thời gian chạy V8.

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {},
  "chat": {
    "addToSpaceFallbackMessage": "Thank you for adding me!"
  },
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "DEPRECATED_ES5"
}

Người dùng có thể thêm ứng dụng của bạn vào một không gian trước khi cho phép ứng dụng. Trong trường hợp này, ứng dụng không thể phản hồi sự kiện thêm vào không gian. Bạn có thể cung cấp thông báo chào mừng để hiển thị nếu điều này xảy ra, bằng cách sử dụng trường addToSpaceFallbackMessage.

Tệp kê khai có tên là appsscript.json và thuộc dự án Apps Script của bạn. Để xem tệp kê khai trong trình chỉnh sửa Apps Script, hãy chọn Xem > Hiển thị tệp kê khai.