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

Quy định hạn chế

Mặc dù điều kiện kích hoạt có thể cài đặt mang lại tính linh hoạt cao 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ế:

Chúng không chạy nếu bạn mở tệp ở 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 nhất người dùng cần có quyền xem tệp tập lệnh để điều kiện kích hoạt chạy đúng cách.
Các yêu cầu API và việc thực thi tập lệnh 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 biểu mẫu mới không khiến trình kích hoạt gửi biểu mẫu chạy.

Lưu ý: Một 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 ra 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 này 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 này 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ở, 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 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 những điều kiện kích hoạt đó.
Các điều kiện kích hoạt có thể cài đặt phải tuân theo giới hạn 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 dựa trên thời gian (còn gọi là trình kích hoạt đồng hồ) tương tự như công việc chạy theo thời gian 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 một khoảng thời gian định kỳ, với tần suất mỗi phút một lần hoặc không thường xuyên như 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ể được sắp xếp ngẫu nhiên một chút – ví dụ: nếu bạn tạo điều kiện kích hoạt định kỳ lúc 9 giờ sáng, 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 cho từng ngày sao cho 24 giờ trôi qua trước khi điều kiện kích hoạt lại kích hoạt.

Sau đây là ví dụ về ứng dụng Google Chat. Ứng dụng này sẽ đă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ư 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 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 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 những 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 đ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 cho các ứ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 một bảng tính, ví dụ: bằng cách thêm 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ó 2 phiên bản của điều kiện 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 được 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 các trình 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 đ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 đ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 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á đ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. Hãy bắt đầu bằng cách gọi ScriptApp.newTrigger(functionName) để trả về TriggerBuilder.

Ví dụ sau đây cho biết cách tạo hai điều kiện kích hoạt theo thời gian – một điều kiện kích hoạt sau mỗi 6 giờ và một điều kiện kích hoạt kích hoạt mỗi 6 giờ sáng thứ Hai (theo 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 thấy 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ư 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).

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 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á và tạo một trình kích hoạt mới. Nếu đã lưu trữ mã điều kiện kích hoạt trước đây, bạn có thể xoá 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

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 này trả về một ngoại lệ hoặc nếu không sẽ không chạy thành công, thì bạn sẽ không thấy thông báo lỗi trên màn hình. Suy cho cùng thì khi một trình kích hoạt theo 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 của bạn, thậm chí bạn 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 có dạng 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ó đườ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 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 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 để khắc phục lỗi.

Để xem lại 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à 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 tới 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 Xem 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().

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 các điều kiện kích hoạt có thể cài đặt trong tiện ích bổ sung, hãy xem bài viết Điều kiện kích hoạt tiện ích bổ sung.