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. Tuy nhiên, trình kích hoạt có thể cài đặt sẽ cung cấp nhiều 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 uỷ quyền, chúng cung cấp một số loại sự kiện khác, bao gồm cả sự kiện theo thời gian (đồng hồ) trình kích hoạt và chúng có thể được kiểm soát theo cách lập trình. Đối với cả đơn giản và điều kiện kích hoạt có thể cài đặt, Apps Script 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 mà sự kiện đã xảy ra.

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, chúng vẫn phải tuân theo một số hạn chế:

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

  • Các quá trì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ụ: đang gọi FormResponse.submit() để gửi một phản hồi biểu mẫu mới thì điều này không làm cho trình kích hoạt gửi biểu mẫu chạy.

  • Các điều kiện kích hoạt có thể cài đặt luôn chạy trong tài khoản của người đã tạo chúng. Ví dụ: nếu bạn tạo một trình kích hoạt mở có thể cài đặt, thì 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 ứng dụng vẫn hoạt động 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 tài liệu được mở, email sẽ 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 trình kích hoạt có thể cài đặt cho mỗi tài khoản, việc này sẽ dẫn đến kết quả trong một email gửi từ mỗi tài khoản.

  • Một tài khoản nhất định không thể xem các điều kiện kích hoạt được cài đặt từ tài khoản thứ hai, thậm chí 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 đó.

  • Các điều kiện kích hoạt có thể cài đặt phải tuân theo điều kiện kích hoạt Apps Script hạn mức.

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

Điều kiện kích hoạt theo thời gian (còn gọi là điều kiện kích hoạt đồng hồ) tương tự như cron Job 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 trong một khoảng thời gian định kỳ (theo tần suất) hằng phút hoặc thậm chí là không thường xuyên như mỗi tháng một lần. (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ề Ứng dụng Google Chat đăng tin nhắn mỗi phút ở mọi không gian có ứng dụng:

// 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 theo sự kiện

Về mặt lý thuyết, điều kiện kích hoạt dựa trên sự kiện có thể cài đặt tương tự như những yếu tố kích hoạt đơn giản như onOpen(), nhưng chúng có thể phản hồi các sự kiện bổ sung và chúng 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 bảng tính được mở bởi bất kỳ người dùng nào có quyền truy cập chỉnh sửa, giống như điều kiện 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. Ứng dụng có thể cài đặt phiên bản chạy có sự cho phép của người dùng đã tạo điều kiện kích hoạt, thậm chí nếu 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ở 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 một 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 bảng tính—ví dụ: bằng cách thêm trang tính mới hoặc xoá mộ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 trả lờ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 các 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 xóa.

Bạn có thể sử dụng điều kiện kích hoạt có thể cài đặt trong các tập lệnh độc lập và tập lệnh ràng buộc. 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 trình kích hoạt có thể cài đặt theo cách thủ công trong trình chỉnh sửa 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á điều kiện 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 minh hoạ cách tạo hai điều kiện kích hoạt theo thời gian, trong đó một điều kiện kích hoạt sẽ kích hoạt 6 giờ một lần và một chuông báo cháy lúc 9 giờ sáng thứ Hai hằng tuần (theo múi giờ tập lệnh của bạn).

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. Lưu ý rằng, không giống với một điều kiện 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() với cuộc 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 điều kiện kích hoạt hiện có thể cài đặt theo phương thức lập trình, bạn phải xoá điều kiện kích hoạt đó rồi tạo một tài khoản mới. Nếu đã lưu trữ mã của một điều kiện 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 trình kích hoạt

Khi một điều kiện kích hoạt có thể cài đặt kích hoạt nhưng hàm đó gửi ra một ngoại lệ hoặc nếu không thì sẽ không chạy thành công, bạn sẽ không thấy thông báo lỗi trên trang web màn hình. Rốt cuộc, khi một điều kiện kích hoạt theo thời gian chạy hoặc khi một người dùng khác kích hoạt trình kích hoạt gửi biểu mẫu, thậm chí bạn có thể không sử dụng máy tính của mì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 là ràng buộc vào một tệp Google Trang tính, Tài liệu hoặc Biểu mẫu thì email cũng sẽ bao gồm đường liên kết đến tệp đó. Các liên kết này cho phép bạn tắt trình kích hoạt hoặc chỉnh sửa tập lệnh để khắc phục lỗi.

Để xem xét tất cả các yếu tố kích hoạt được liên kết với Tài khoản Google của bạn và tắt những điều kiện kích hoạt bạn không cần nữa, 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, hãy nhấp vào biểu tượng Thêm ở bên phải điều kiện kích hoạt đó > Xoá điều kiện kích hoạt.

Điều kiện kích hoạt trong tiện ích bổ sung

Ngoài 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 tiện ích bổ sung. Để biết thêm thông tin, xem Điều kiện kích hoạt cho tiện ích bổ sung của Google Workspace.