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ở 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ả điều kiện kích hoạt đơn giản và có thể cài đặt, Apps Script sẽ truyền hàm được kích hoạt vào một đối tượng sự kiện có chứa thông tin về ngữ 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, 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, tối thiểu người dùng cần có quyền xem vào tệp tập lệnh để điều kiện 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 cho biểu mẫu không làm cho trình kích hoạt gửi biểu mẫu chạy.

Lưu ý: Form.submitGrades() là trường hợp ngoại lệ đối với quy định hạn chế này. Nếu mã của bạn sử dụng điều kiện kích hoạt onFormSubmit, thì việc gọi Form.submitGrades() sẽ kích hoạt điều kiện onFormSubmit và tạo 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 đã tồn tại hay chưa trước khi gọi submitGrades().
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 các điều kiện 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, 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 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 điều kiện kích hoạt để gửi email khi tài liệu được mở, thì 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 đ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 đó.
Đ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 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. Điều kiện 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 khoảng thời gian định kỳ, với tần suất là mỗi phút hoặc không thường xuyên là 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 tin nhắn mỗi phút lên mọi không gian có chứa ứ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ư điều kiện kích hoạt đơn giản như onOpen(), nhưng có thể phản hồi vớ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ở 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 đ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ể lập trình để tạo một điều kiện kích hoạt có thể cài đặt cho một tệp Google Trang tính tuỳ ý bằng cách gọi TriggerBuilder.forSpreadsheet(key) rồi truyền mã nhận dạng của bảng tính vào.

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 sửa tập lệnh, hãy làm theo các bước sau:

Mở dự án Apps Script.
Ở bên trái, hãy nhấp vào biểu tượng Điều kiện kích hoạt .
Ở dưới cùng bên phải, hãy nhấp vào Thêm điều kiện kích hoạt.
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.
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). Hàm 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

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 một đ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).

kích hoạt/triggers.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 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 đó và tạo một điều kiện kích hoạt mới. Nếu trước đây đã lưu trữ mã nhận dạng 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ã nhận dạng đó dưới dạng một đối số cho hàm bên dưới.

triggers/triggers.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 đ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 không thể 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:

Chuyển đến script.google.com.
Ở bên trái, hãy nhấp vào Điều kiện kích hoạt của tôi.
Để 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 Thêm > Xoá điều kiện kích hoạt.

Lưu ý: Bạn không thể huỷ kích hoạt các điều kiện 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().

Điều kiện 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.