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

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ở một tài liệu, xảy ra. Tuy nhiên, trình kích hoạt có thể cài đặt cho phép bạn linh hoạt hơn so với các 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 như sự kiện kích hoạt theo thời gian (đồng hồ) và có thể được kiểm soát bằng lập trình. Đối với cả trình kích hoạt đơn giản và có thể cài đặt, Apps Script sẽ truyền cho hàm đã kích hoạt một đối tượng sự kiện chứa thông tin về ngữ cảnh diễn ra sự kiện.

Quy tắc hạn chế

Mặc dù trình kích hoạt có thể cài đặt cho phép bạn linh hoạt hơn so với 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ế:

Chúng không chạy nếu tệp được mở ở chế độ chỉ đọc (xem hoặc nhận xét). Đối với các tập lệnh độc lập, ít nhất người dùng cần quyền xem tệp tập lệnh để trình kích hoạt chạy đúng cách.
Việc thực thi tập lệnh và các yêu cầu API không khiến trình kích hoạt chạy. Ví dụ: việc gọi FormResponse.submit() để gửi phản hồi biểu mẫu mới không làm cho trình kích hoạt gửi biểu mẫu chạy.

Lưu ý: Một ngoại lệ đối với quy định hạn chế này là Form.submitGrades(). Nếu mã của bạn sử dụng trình kích hoạt onFormSubmit, thì việc gọi Form.submitGrades() sẽ kích hoạt điều kiện onFormSubmit và gây ra một vòng lặp vô hạn. Để ngăn vòng lặp vô hạn, hãy thêm mã kiểm tra xem điểm số đã tồn tại chưa trước khi gọi submitGrades().
Các 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, nó sẽ chạy khi đồng nghiệp mở tài liệu (nếu đồng nghiệp của bạn có quyền chỉnh sửa), nhưng nó 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 trình kích hoạt để gửi email khi mở một tài liệu, thì email đó 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, dẫn đến 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ừ mộ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 đó.
Các trình kích hoạt có thể cài đặt phải tuân theo giới hạn định mức của trình kích hoạt Apps.

Trình 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 cần làm 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 định kỳ, với tần suất cứ mỗi phút hoặc không thường xuyên một lần mỗi tháng. (Lưu ý rằng tiện ích bổ sung có thể sử dụng trình kích hoạt theo thời gian tối đa một lần mỗi giờ.) Thời gian có thể ngẫu nhiên một chút — ví dụ: nếu bạn tạo một trình kích hoạt 9 giờ sáng định kỳ, Apps Script sẽ chọn thời gian 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 kích hoạt lại.

Trình kích hoạt theo sự kiện

Về mặt lý thuyết, trình kích hoạt theo sự kiện có thể cài đặt cũng 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 khác nhau.

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 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 sẽ 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 Google Workspace ứng dụng:

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 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—ví dụ: bằng cách thêm trang tính mới hoặc xoá 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 trả lời biểu mẫu. Có hai phiên bản trình kích hoạt gửi biểu mẫu, một cho chính Google Biểu mẫu và một cho Trang tính nếu biểu mẫu gửi tới 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 xóa.

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à các 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 theo cách lập trình cho một tệp Google Trang tính tuỳ ý bằng cách gọi TriggerBuilder.forSpreadsheet(key) và chuyển mã nhận dạng của bảng tính.

Quản lý trình 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:

Mở dự án Apps Script của bạn.
Ở bên trái, hãy nhấp vào biểu tượng Trình kích hoạt .
Ở dưới cùng bên phải, hãy nhấp vào Thêm trình kích hoạt.
Chọn và định cấu hình loại trình kích hoạt bạn muốn tạo.
Nhấp vào Save (Lưu).

Quản lý trình 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 trình kích hoạt theo cách 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) để trả về TriggerBuilder.

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

trình kích hoạt/trình kích hoạt.gs

Xem trên GitHub

/**
 * 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 cho biết cách tạo trình kích hoạt mở có thể cài đặt cho bảng tính. 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 phải được liên kết với bảng tính. Để tạo trình 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).

trình kích hoạt/trình kích hoạt.gs

Xem trên GitHub

/**
 * 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 trình 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á trình kích hoạt đó và tạo một trình kích hoạt mới. Nếu trước đây bạn đã lưu trữ mã nhận dạng của một trình kích hoạt, bạn có thể xoá mã đó bằng cách truyền mã nhận dạng đó làm đối số cho hàm bên dưới.

trình kích hoạt/trình kích hoạt.gs

Xem trên GitHub

/**
 * 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 trình kích hoạt có thể cài đặt kích hoạt nhưng hàm gửi một ngoại lệ hoặc không chạy được, bạn sẽ không thấy thông báo lỗi trên màn hình. Rốt cuộc, khi trình kích hoạt theo thời gian chạy hoặc 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 ở trên máy tính.

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

From: 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 trình 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 bao gồm một đườ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 trình kích hoạt hoặc chỉnh sửa tập lệnh để sửa lỗi.

Để xem lại tất cả các trình kích hoạt được liên kết với tài khoản Google của bạn và hủy kích hoạt các trình kích hoạt bạn không cần nữa, hãy làm theo các bước sau:

Chuyển đến script.google.com.
Ở bên trái, hãy nhấp vào Trình kích hoạt của tôi.
Để xoá một trình kích hoạt, ở bên phải trình kích hoạt, hãy nhấp vào biểu tượng Thêm > Xoá trình kích hoạt.

Lưu ý: Bạn không thể hủy kích hoạt các trình kích hoạt đơn giản như onOpen() trên trang này. Thay vào đó, bạn phải chỉnh sửa tập lệnh thích hợp và xoá hoặc đổi tên hàm onOpen().

Trình kích hoạt có thể cài đặt trong tiện ích bổ sung

Để biết thêm thông tin về cách sử dụng trình kích hoạt có thể cài đặt trong tiện ích bổ sung, hãy xem bài viết Trình kích hoạt tiện ích bổ sung.