Trình kích hoạt có thể cài đặt

Giống như trình kích hoạt đơn giản, trình kích hoạt có thể cài đặt cho phép Apps Script tự động chạy một hàm khi một sự kiện nhất định (chẳng hạn như mở tài liệu) xảy ra. Tuy nhiên, trình kích hoạt có thể cài đặt mang lại nhiều tính linh hoạt hơn so với trình kích hoạt đơn giản: chúng có thể gọi dịch vụ yêu cầu quyền uỷ quyền, cung cấp một số loại sự kiện bổ sung bao gồm cả trình kích hoạt theo thời gian (đồng hồ) và có thể được kiểm soát theo phương thức lập trình. Đối với cả trình kích hoạt đơn giản và trình kích hoạt có thể cài đặt, Apps Script sẽ truyền hàm được kích hoạt một đối tượng sự kiện chứa thông tin về bối cảnh xảy ra sự kiện.

Quy định hạn chế

Mặc dù trình kích hoạt có thể cài đặt linh hoạt hơn so với trình kích hoạt đơn giản, nhưng vẫn phải tuân theo một số quy định hạn chế:

  • Các tệp này sẽ không chạy nếu tệp được mở ở chế độ chỉ có thể đọc (xem hoặc nhận xét). Đối với các tập lệnh độc lập, người dùng cần có ít nhất quyền xem tệp tập lệnh để trình kích hoạt chạy đúng cách.

  • Các lệnh thực thi tập lệnh và yêu cầu API không khiến điều kiện kích hoạt chạy. Ví dụ: việc gọi FormResponse.submit() để gửi phản hồi mới của biểu mẫu sẽ không khiến trình kích hoạt gửi của biểu mẫu chạy.

  • Trình kích hoạt có thể cài đặt luôn chạy trong tài khoản của người tạo trình kích hoạt đó. Ví dụ: nếu bạn tạo một trình kích hoạt mở có thể cài đặt, trình kích hoạt đó sẽ chạy khi đồng nghiệp của bạn mở tài liệu (nếu đồng nghiệp của bạn có quyền chỉnh sửa), nhưng trình kích hoạt đó sẽ chạy dưới dạng tài khoản của bạn. Điều này có nghĩa là nếu bạn tạo một điều kiện kích hoạt để gửi email khi một tài liệu được mở, thì email đó luôn được gửi từ tài khoản của bạn, không nhất thiết là tài khoản đã mở tài liệu. Tuy nhiên, bạn có thể tạo một điều kiện kích hoạt có thể cài đặt cho mỗi tài khoản. Điều này sẽ dẫn đến việc một email được gửi từ mỗi tài khoản.

  • Một tài khoản nhất định không thể xem các trình kích hoạt được cài đặt từ tài khoản thứ hai, mặc dù tài khoản đầu tiên vẫn có thể kích hoạt các trình kích hoạt đó.

  • Trình kích hoạt có thể cài đặt phải tuân theo giới hạn hạn mức của trình kích hoạt Apps Script.

Điều kiện kích hoạt theo thời gian

Trình kích hoạt theo thời gian (còn gọi là trình kích hoạt đồng hồ) tương tự như công việc cron trong Unix. Trình kích hoạt theo thời gian cho phép các tập lệnh thực thi tại một thời điểm cụ thể hoặc theo một khoảng thời gian định kỳ, thường xuyên như mỗi phút hoặc không thường xuyên như một lần mỗi tháng. (Xin lưu ý rằng một tiện ích bổ sung có thể sử dụng một trình kích hoạt dựa trên thời gian tối đa một lần mỗi giờ.) Thời gian có thể được tạo ngẫu nhiên một chút. Ví dụ: nếu bạn tạo một điều kiện kích hoạt định kỳ vào lúc 9 giờ sáng, Apps Script sẽ chọn một thời gian trong khoảng từ 9 giờ sáng đến 10 giờ sáng, sau đó duy trì thời gian đó nhất quán từ ngày này sang ngày khác để 24 giờ trôi qua trước khi điều kiện kích hoạt kích hoạt lại.

Sau đây là ví dụ về một ứng dụng Google Chat đăng một tin nhắn mỗi phút vào mọi không gian mà ứng dụng đó có mặt:

// 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 in the
// "Edit > Current Project's Triggers" menu. When it runs, it
// posts 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),
  });
}

Trình kích hoạt do sự kiện điều khiển

Về mặt khái niệm, trình kích hoạt do sự kiện điều khiển có thể cài đặt tương tự như trình kích hoạt đơn giản như onOpen(), nhưng có thể phản hồi các sự kiện bổ sung và hoạt động theo cách khác.

Ví dụ: trình kích hoạt mở có thể cài đặt cho Google Trang tính sẽ kích hoạt bất cứ khi nào người dùng có quyền chỉnh sửa mở bảng tính, giống như trình kích hoạt onOpen() đơn giản. Tuy nhiên, phiên bản có thể cài đặt có thể gọi các dịch vụ yêu cầu uỷ quyền. Phiên bản cài đặt được sẽ chạy theo quyền của người dùng đã tạo điều kiện kích hoạt, ngay cả khi một người dùng khác có quyền chỉnh sửa mở bảng tính.

Có một số trình kích hoạt có thể cài đặt cho ứng dụngGoogle Workspace :

  • Trình kích hoạt mở có thể cài đặt sẽ chạy khi người dùng mở một bảng tính, tài liệu hoặc biểu mẫu mà họ có quyền chỉnh sửa.
  • Trình kích hoạt chỉnh sửa có thể cài đặt sẽ chạy khi người dùng sửa đổi một giá trị trong bảng tính.
  • Trình kích hoạt thay đổi có thể cài đặt sẽ chạy khi người dùng sửa đổi cấu trúc của chính bảng tính, chẳng hạn như bằng cách thêm một trang tính mới hoặc xoá một cột.
  • Trình kích hoạt gửi biểu mẫu có thể cài đặt sẽ chạy khi người dùng phản hồi một biểu mẫu. Có hai phiên bản của điều kiện kích hoạt gửi biểu mẫu, một phiên bản dành cho chính Google Biểu mẫu và một phiên bản dành cho Trang tính nếu biểu mẫu gửi đến một bảng tính.
  • Trình kích hoạt sự kiện trên lịch có thể cài đặt sẽ chạy khi sự kiện trên lịch của người dùng được cập nhật, tạo, chỉnh sửa hoặc xoá.

Bạn có thể sử dụng trình kích hoạt có thể cài đặt trong các tập lệnh độc lập và liên kết. Ví dụ: một tập lệnh độc lập có thể tạo một trình kích hoạt có thể cài đặt cho một tệp Google Trang tính tuỳ ý theo phương thức lập trình bằng cách gọi TriggerBuilder.forSpreadsheet(key) và truyền mã nhận dạng của bảng tính.

Quản lý điều kiện kích hoạt theo cách thủ công

Để tạo một trình kích hoạt có thể cài đặt theo cách thủ công trong trình soạn thảo tập lệnh, hãy làm theo các bước sau:

  1. Mở dự án Apps Script.
  2. Ở bên trái, hãy nhấp vào biểu tượng Điều kiện kích hoạt .
  3. Ở dưới cùng bên phải, hãy nhấp vào Thêm điều kiện kích hoạt.
  4. Chọn và định cấu hình loại điều kiện kích hoạt mà bạn muốn tạo.
  5. Nhấp vào Lưu.

Quản lý điều kiện kích hoạt theo phương thức lập trình

Bạn cũng có thể tạo và xoá trình kích hoạt theo phương thức lập trình bằng Dịch vụ tập lệnh. Bắt đầu bằng cách gọi ScriptApp.newTrigger(functionName). Thao tác này sẽ trả về TriggerBuilder.

Ví dụ sau đây cho biết cách tạo hai trình kích hoạt theo thời gian – một trình kích hoạt sẽ kích hoạt 6 giờ một lần và một trình kích hoạt sẽ kích hoạt vào lúc 9 giờ sáng thứ Hai (theo múi giờ mà tập lệnh của bạn được đặt).

triggers/triggers.gs
/**
 * Creates two time-driven triggers.
 * @see https://developers.google.com/apps-script/guides/triggers/installable#time-driven_triggers
 */
function createTimeDrivenTriggers() {
  // Trigger every 6 hours.
  ScriptApp.newTrigger('myFunction')
      .timeBased()
      .everyHours(6)
      .create();
  // Trigger every Monday at 09:00.
  ScriptApp.newTrigger('myFunction')
      .timeBased()
      .onWeekDay(ScriptApp.WeekDay.MONDAY)
      .atHour(9)
      .create();
}

Ví dụ tiếp theo này cho biết cách tạo điều kiện kích hoạt mở có thể cài đặt cho một bảng tính. Xin lưu ý rằng, không giống như trình kích hoạt onOpen() đơn giản, tập lệnh cho trình kích hoạt có thể cài đặt không cần liên kết với bảng tính. Để tạo điều kiện kích hoạt này từ một tập lệnh độc lập, bạn chỉ cần thay thế SpreadsheetApp.getActive() bằng lệnh gọi đến SpreadsheetApp.openById(id).

triggers/triggers.gs
/**
 * Creates a trigger for when a spreadsheet opens.
 * @see https://developers.google.com/apps-script/guides/triggers/installable
 */
function createSpreadsheetOpenTrigger() {
  const ss = SpreadsheetApp.getActive();
  ScriptApp.newTrigger('myFunction')
      .forSpreadsheet(ss)
      .onOpen()
      .create();
}

Để sửa đổi một trình kích hoạt có thể cài đặt hiện có theo phương thức lập trình, bạn phải xoá trình kích hoạt đó rồi tạo một trình kích hoạt mới. Nếu đã lưu trữ mã của một trình kích hoạt, bạn có thể xoá mã đó bằng cách truyền mã làm đối số vào hàm bên dưới.

triggers/triggers.gs
/**
 * Deletes a trigger.
 * @param {string} triggerId The Trigger ID.
 * @see https://developers.google.com/apps-script/guides/triggers/installable
 */
function deleteTrigger(triggerId) {
  // Loop over all triggers.
  const allTriggers = ScriptApp.getProjectTriggers();
  for (let index = 0; index < allTriggers.length; index++) {
    // If the current trigger is the correct one, delete it.
    if (allTriggers[index].getUniqueId() === triggerId) {
      ScriptApp.deleteTrigger(allTriggers[index]);
      break;
    }
  }
}

Lỗi trong điều kiện kích hoạt

Khi một trình kích hoạt có thể cài đặt được kích hoạt nhưng hàm gửi một ngoại lệ hoặc không chạy thành công, bạn sẽ không thấy thông báo lỗi trên màn hình. Xét cho cùng, khi một điều kiện kích hoạt theo thời gian chạy hoặc một người dùng khác kích hoạt điều kiện kích hoạt gửi biểu mẫu, bạn thậm chí có thể không ở bên máy tính.

Thay vào đó, Apps Script sẽ gửi cho bạn một email như sau:

From: noreply-apps-scripts-notifications@google.com
Subject: Summary of failures for Google Apps Script
Your script has recently failed to finish successfully.
A summary of the failure(s) is shown below.

Email này có chứa một đường liên kết để huỷ kích hoạt hoặc định cấu hình lại điều kiện kích hoạt. Nếu tập lệnh được liên kết với tệp Google Trang tính, Tài liệu hoặc Biểu mẫu, thì email cũng sẽ chứa đường liên kết đến tệp đó. Các đường liên kết này cho phép bạn vô hiệu hoá điều kiện kích hoạt hoặc chỉnh sửa tập lệnh để khắc phục lỗi.

Để xem tất cả các điều kiện kích hoạt được liên kết với Tài khoản Google của bạn và vô hiệu hoá các điều kiện kích hoạt mà bạn không còn cần đến, hãy làm theo các bước sau:

  1. Chuyển đến script.google.com.
  2. Ở bên trái, hãy nhấp vào Điều kiện kích hoạt của tôi.

  3. Để xoá một điều kiện kích hoạt, ở bên phải điều kiện kích hoạt đó, hãy nhấp vào biểu tượng Tuỳ chọn khác > Xoá điều kiện kích hoạt.

Trình kích hoạt trong tiện ích bổ sung

Ngoài các trình kích hoạt có thể cài đặt, bạn có thể sử dụng trình kích hoạt tệp kê khai trong các tiện ích bổ sung. Để biết thêm thông tin, hãy xem phần Trình kích hoạt cho tiện ích bổ sung của Google Workspace.