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ư các điều kiện kích hoạt đơn giản, điều kiện 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 đến sự linh hoạt hơn so với 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, cung cấp một số loại sự kiện khác, bao gồm trình kích hoạt (đồng hồ) theo thời gian 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 chứa thông tin về ngữ cảnh mà sự kiện đã xảy ra.

Các quy định hạn chế

Mặc dù các điều kiện kích hoạt có thể cài đặt linh hoạt hơn so với điều kiện 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 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). Đố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 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ụ: 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 ý: Trường hợp 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 đ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. Để tránh 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 điều kiện kích hoạt mở có thể cài đặt, thì điều này 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 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, nhờ đó, mỗi tài khoản sẽ nhận được một email.
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 qua 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 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

Đ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ư 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 tiện ích bổ sung chỉ có thể sử dụng điều kiện kích hoạt theo thời gian tối đa 1 lần mỗi giờ.) Thời gian có thể được sắp xếp một chút ngẫu nhiên – ví dụ: nếu bạn tạo một điều kiện kích hoạt định kỳ 9 giờ sáng, thì Apps Script sẽ chọn thời gian từ 9 giờ sáng đến 10 giờ sáng, sau đó giữ cho 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ụ: điều kiện 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ư đ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. Phiên bản có thể cài đặt sẽ chạy theo sự cho phép 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ố điều kiện kích hoạt có thể cài đặt choGoogle 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, chẳng hạn như 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 một biểu mẫu. Trình kích hoạt gửi biểu mẫu có hai phiên bản, một phiên bản dành cho 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 điều kiện 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 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 vào 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 điều kiện 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á 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 thấy cách tạo 2 điều kiện kích hoạt theo thời gian – một điều kiện kích hoạt 6 giờ một lần và một điều kiện kích hoạt lúc 9 giờ sáng thứ Hai hằng tuần (ở múi giờ mà tập lệnh của bạn đã đặ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. Lưu ý rằng, không giống như một điều kiện kích hoạt onOpen() đơn giản, tập lệnh cho điều kiện kích hoạt có thể cài đặt không cần được 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

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ã này 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 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. Rốt cuộc, 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, thì bạn thậm chí có thể không ở trên 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 đượ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ẽ 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 đ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 lại tất cả những đ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à huỷ kích hoạt những điều kiện kích hoạt mà 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 Đ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 điều kiện kích hoạt có thể cài đặt, bạn có thể sử dụng điều kiện kích hoạt tệp kê khai trong tiện ích bổ sung. Để biết thêm thông tin, hãy xem bài viết Điều kiện kích hoạt cho tiện ích bổ sung của Google Workspace.