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 xảy ra, chẳng hạn như mở một tài liệu. Tuy nhiên, trình kích hoạt có thể cài đặt linh hoạt hơn trình kích hoạt đơn giản: chúng có thể gọi các dịch vụ yêu cầu uỷ quyền, chúng cung cấp một số loại sự kiện bổ sung, bao gồm cả trình kích hoạt dựa trên 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 cho 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ù các trình kích hoạt có thể cài đặt linh hoạt hơn các trình kích hoạt đơn giản, nhưng chúng vẫn phải tuân theo một số hạn chế:

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

  • Việc thực thi tập lệnh và yêu cầu API không khiến các trình kích hoạt chạy. Ví dụ: việc gọi FormResponse.submit() để gửi một câu trả lời mới qua 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 có thể cài đặt, trình kích hoạt đó sẽ chạy khi đồng nghiệp mở tài liệu (nếu đồng nghiệp 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 đó sẽ luôn được gửi từ tài khoản của bạn, chứ 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. Điều này sẽ dẫn đến việc mỗi tài khoản gửi một email.

  • Một tài khoản nhất định không thể thấy các điều kiện 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 điều kiện đó.

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

Trình kích hoạt dựa trên thời gian

Trình kích hoạt dựa trên thời gian (còn gọi là trình kích hoạt đồng hồ) tương tự như cron job trong Unix. Trình kích hoạt dựa trên thời gian cho phép tập lệnh thực thi vào 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ất là mỗi phút hoặc ít thường xuyên nhất là mỗi tháng một lần. (Xin lưu ý rằng tiện ích bổ sung có thể sử dụng 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 chọn ngẫu nhiên một chút. Ví dụ: nếu bạn tạo một trình kích hoạt định kỳ 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 trình kích hoạt hoạt động lại.

Trình kích hoạt dựa trên sự kiện

Về mặt khái niệm, trình kích hoạt dựa trên sự kiện có thể cài đặt tương tự như trình 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à hoạt động theo cách khác.

Ví dụ: trình kích hoạt có thể cài đặt khi mở cho Google Trang tính sẽ kích hoạt bất cứ khi nào bảng tính được mở bởi người dùng có quyền chỉnh sửa, 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ó thể cài đặt chạy với sự uỷ quyền của người dùng đã tạo trình 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 các ứng dụngGoogle Workspace :

  • Trình kích hoạt open (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 trình 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.
  • Một 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 (được 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 tập lệnh độc lập và tập lệnh 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 cách 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 chỉnh tập tập lệnh, hãy làm theo các bước sau:

  1. Mở dự án Apps Script của bạn.
  2. Ở bên trái, hãy nhấp vào Đ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à thiết lập 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á các đ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 cho biết cách tạo hai trình kích hoạt dựa trên thời gian: một trình kích hoạt cứ 6 giờ sẽ kích hoạt một lần và một trình kích hoạt cứ 9 giờ sáng thứ Hai sẽ kích hoạt một lần (theo múi giờ mà bạn đặt cho tập lệnh).

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 một điều kiện kích hoạt có thể cài đặt để mở bảng tính. Xin lưu ý rằng không giống như đối với một 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 phải được liên kết với bảng tính. Để tạo sự 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 một 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 đó và tạo một trình kích hoạt mới. Nếu đã lưu trữ mã nhận dạng của một điều kiện kích hoạt trước đó, bạn có thể xoá mã nhận dạng đó bằng cách truyền mã nhận dạng làm đối số cho 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;
    }
  }
}

Trước khi tạo một điều kiện kích hoạt, bạn nên xác minh rằng hàm được liên kết có tất cả các quyền OAuth cần thiết.

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

Khi một sự kiện kích hoạt có thể cài đặt được kích hoạt nhưng hàm đó gặp 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. Sau tất cả, khi một trình kích hoạt dựa trên thời gian chạy hoặc một người dùng khác kích hoạt trình 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 để tắ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 một tệp Google Trang tính, Tài liệu hoặc Biểu mẫu, thì email cũng sẽ có đường liên kết đến tệp đó. Các đường liên kết này cho phép bạn huỷ kích hoạt đ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á những đ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 Google Workspace.