Đối tượng sự kiện

Trình kích hoạt đơn giản và trình kích hoạt có thể cài đặt cho phép Apps Script tự động chạy một hàm nếu một sự kiện nhất định xảy ra. Khi một điều kiện kích hoạt được kích hoạt, Apps Script sẽ truyền cho hàm một đối tượng sự kiện dưới dạng đối số, thường được gọi là e. Đối tượng sự kiện chứa thông tin về ngữ cảnh đã kích hoạt điều kiện kích hoạt. Ví dụ: mã mẫu bên dưới cho thấy một trình kích hoạt onEdit(e) đơn giản cho tập lệnh Google Trang tính sử dụng đối tượng sự kiện để xác định ô nào đã được chỉnh sửa.

function onEdit(e){
  // Set a comment on the edited cell to indicate when it was changed.
  var range = e.range;
  range.setNote('Last modified: ' + new Date());
}

Trang này trình bày chi tiết về các trường trong đối tượng sự kiện cho nhiều loại trình kích hoạt.

Các sự kiện do trình kích hoạt có thể cài đặt tạo ra chứa một triggerUid xác định trình kích hoạt đã tạo sự kiện. Điều này hữu ích cho các tập lệnh có nhiều trình kích hoạt có thể cài đặt.

Sự kiện trên Google Trang tính

Các trình kích hoạt dành riêng cho Google Trang tính cho phép tập lệnh phản hồi các thao tác của người dùng trong bảng tính.

Đang mở (đơn giản và có thể cài đặt)
authMode	Một giá trị từ enum ScriptApp.AuthMode. LIMITED
source	Đối tượng Spreadsheet đại diện cho tệp Google Trang tính mà tập lệnh được liên kết. Spreadsheet
triggerUid	Mã của trình kích hoạt đã tạo sự kiện này (chỉ dành cho trình kích hoạt có thể cài đặt). 4034124084959907503
user	Đối tượng User, đại diện cho người dùng đang hoạt động, nếu có (tuỳ thuộc vào một tập hợp các quy định hạn chế bảo mật phức tạp). [e-mail]

Chuyển (có thể cài đặt)
authMode	Một giá trị từ enum ScriptApp.AuthMode. FULL
changeType	Loại thay đổi (EDIT, INSERT_ROW, INSERT_COLUMN, REMOVE_ROW, REMOVE_COLUMN, INSERT_GRID, REMOVE_GRID, FORMAT hoặc OTHER). INSERT_ROW
source	Đối tượng Spreadsheet đại diện cho tệp Google Trang tính mà tập lệnh liên kết đến. Spreadsheet
triggerUid	Mã của điều kiện kích hoạt đã tạo ra sự kiện này. 4034124084959907503
user	Đối tượng User, đại diện cho người dùng đang hoạt động, nếu có (tuỳ thuộc vào một tập hợp các quy định hạn chế bảo mật phức tạp). [e-mail]

Chỉnh sửa (đơn giản và có thể cài đặt)
authMode	Một giá trị từ enum ScriptApp.AuthMode. LIMITED
oldValue	Giá trị của ô trước khi chỉnh sửa (nếu có). Chỉ có sẵn nếu dải ô đã chỉnh sửa là một ô. Sẽ không xác định được nếu ô không có nội dung trước đó. 1234
range	Đối tượng Range, đại diện cho ô hoặc dải ô đã được chỉnh sửa. Range
source	Đối tượng Spreadsheet đại diện cho tệp Google Trang tính mà tập lệnh được liên kết. Spreadsheet
triggerUid	Mã của trình kích hoạt đã tạo sự kiện này (chỉ dành cho trình kích hoạt có thể cài đặt). 4034124084959907503
user	Đối tượng User, đại diện cho người dùng đang hoạt động, nếu có (tuỳ thuộc vào một tập hợp các quy định hạn chế bảo mật phức tạp). [e-mail]
value	Giá trị mới trong ô sau khi chỉnh sửa. Chỉ có sẵn nếu dải ô đã chỉnh sửa là một ô. 10

Gửi biểu mẫu (có thể cài đặt)
Thận trọng: Hãy đảm bảo bạn sử dụng trình kích hoạt gửi biểu mẫu này với SpreadsheetTriggerBuilder.
authMode	Một giá trị từ enum ScriptApp.AuthMode. FULL
namedValues	Một đối tượng chứa tên câu hỏi và giá trị từ lượt gửi biểu mẫu. { 'First Name': ['Jane'], 'Timestamp': ['6/7/2015 20:54:13'], 'Last Name': ['Doe'] }
range	Đối tượng Range, đại diện cho ô hoặc dải ô đã được chỉnh sửa. Range
triggerUid	Mã của điều kiện kích hoạt đã tạo ra sự kiện này. 4034124084959907503
values	Mảng có các giá trị theo thứ tự xuất hiện trong bảng tính. ['2015/05/04 15:00', '[e-mail]', 'Bob', '27', 'Bill', '28', 'Susan', '25']

Sự kiện trên Google Tài liệu

Điều kiện kích hoạt cho phép Google Tài liệu phản hồi khi người dùng mở một tài liệu.

Đang mở (đơn giản và có thể cài đặt)
authMode	Một giá trị từ enum ScriptApp.AuthMode. LIMITED
source	Một đối tượng Document, đại diện cho tệp Google Tài liệu mà tập lệnh được liên kết. Document
triggerUid	Mã của trình kích hoạt đã tạo sự kiện này (chỉ dành cho trình kích hoạt có thể cài đặt). 4034124084959907503
user	Đối tượng User, đại diện cho người dùng đang hoạt động, nếu có (tuỳ thuộc vào một tập hợp các quy định hạn chế bảo mật phức tạp). [e-mail]

Sự kiện trên Google Trang trình bày

Điều kiện kích hoạt cho phép Google Trang trình bày phản hồi khi người dùng mở một bản trình bày.

Đang mở (đơn giản)
authMode	Một giá trị từ enum ScriptApp.AuthMode. LIMITED
source	Một đối tượng Presentation, đại diện cho tệp Google Trang trình bày mà tập lệnh liên kết đến. Presentation
user	Đối tượng User, đại diện cho người dùng đang hoạt động, nếu có (tuỳ thuộc vào một tập hợp các quy định hạn chế bảo mật phức tạp). [e-mail]

Sự kiện trên Google Biểu mẫu

Các trình kích hoạt dành riêng cho Google Biểu mẫu cho phép tập lệnh phản hồi khi người dùng chỉnh sửa biểu mẫu hoặc gửi phản hồi.

Đang mở * (đơn giản và có thể cài đặt)
authMode	Một giá trị từ enum ScriptApp.AuthMode. LIMITED
source	Một đối tượng Form, đại diện cho tệp Google Forms mà tập lệnh được liên kết. Form
triggerUid	Mã của trình kích hoạt đã tạo sự kiện này (chỉ dành cho trình kích hoạt có thể cài đặt). 4034124084959907503
user	Đối tượng User, đại diện cho người dùng đang hoạt động, nếu có (tuỳ thuộc vào một tập hợp các quy định hạn chế bảo mật phức tạp). [e-mail]

* Sự kiện này không xảy ra khi người dùng mở biểu mẫu để trả lời, mà là khi người chỉnh sửa mở biểu mẫu để sửa đổi biểu mẫu đó.

Gửi biểu mẫu (có thể cài đặt)
Thận trọng: Hãy đảm bảo bạn sử dụng trình kích hoạt gửi biểu mẫu này với FormTriggerBuilder.
authMode	Một giá trị từ enum ScriptApp.AuthMode. FULL
response	Đối tượng FormResponse, đại diện cho toàn bộ phản hồi của người dùng đối với biểu mẫu. FormResponse
source	Một đối tượng Form, đại diện cho tệp Google Forms mà tập lệnh được liên kết. Form
triggerUid	Mã của điều kiện kích hoạt đã tạo ra sự kiện này. 4034124084959907503

Sự kiện trên Lịch Google

Lịch kích hoạt 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á).

Các trình kích hoạt này không cho bạn biết sự kiện nào đã thay đổi hoặc cách sự kiện đó thay đổi. Thay vào đó, các sự kiện này cho biết mã của bạn cần thực hiện một thao tác đồng bộ hoá gia tăng để nhận các thay đổi gần đây đối với lịch. Để biết nội dung mô tả đầy đủ về quy trình này, hãy xem Hướng dẫn đồng bộ hoá tài nguyên cho API Lịch.

Để đồng bộ hoá với Lịch trong Apps Script, hãy thực hiện các bước sau:

1. Bật dịch vụ nâng cao của Lịch cho dự án tập lệnh. Dịch vụ Lịch tích hợp sẵn không đủ cho quy trình công việc này.
2. Xác định những lịch cần đồng bộ hoá. Đối với mỗi lịch như vậy, hãy thực hiện thao tác đồng bộ hoá ban đầu bằng phương thức Events.list() của dịch vụ nâng cao Lịch.
3. Kết quả của lần đồng bộ hoá đầu tiên sẽ trả về một nextSyncToken cho lịch đó. Lưu trữ mã thông báo này để sử dụng sau.
4. Khi điều kiện kích hoạt EventUpdated của Apps Script kích hoạt cho biết một sự kiện trong lịch đã thay đổi, hãy thực hiện đồng bộ hoá gia tăng cho lịch bị ảnh hưởng bằng cách sử dụng nextSyncToken đã lưu trữ. Về cơ bản, đây là một yêu cầu Events.list() khác, nhưng việc cung cấp nextSyncToken sẽ giới hạn phản hồi chỉ ở những sự kiện đã thay đổi kể từ lần đồng bộ hoá gần nhất.
5. Kiểm tra phản hồi của quá trình đồng bộ hoá để tìm hiểu những sự kiện đã được cập nhật và yêu cầu mã của bạn phản hồi một cách thích hợp. Ví dụ: bạn có thể ghi lại thay đổi, cập nhật bảng tính, gửi thông báo qua email hoặc thực hiện các hành động khác.
6. Cập nhật nextSyncToken mà bạn đã lưu trữ cho lịch đó bằng nextSyncToken do yêu cầu đồng bộ hoá gia tăng trả về. Thao tác này buộc thao tác đồng bộ hoá tiếp theo chỉ trả về các thay đổi mới nhất.

Thận trọng: Đôi khi, máy chủ sẽ vô hiệu hoá mã thông báo đồng bộ hoá, dẫn đến lỗi 410. Khi điều này xảy ra, mã của bạn sẽ tiến hành đồng bộ hoá đầy đủ và thay thế tất cả dữ liệu và mã thông báo đã đồng bộ hoá mà bạn có cho lịch đó.

EventUpdated (có thể cài đặt)
authMode	Một giá trị từ enum ScriptApp.AuthMode. FULL
calendarId	Mã chuỗi của lịch nơi diễn ra quá trình cập nhật sự kiện. [e-mail]
triggerUid	Mã của điều kiện kích hoạt đã tạo ra sự kiện này. 4034124084959907503

Sự kiện của tiện ích bổ sung cho Google Workspace

Trình kích hoạt onInstall() sẽ tự động chạy khi người dùng cài đặt một tiện ích bổ sung.

Cài đặt (đơn giản)
authMode	Một giá trị từ enum ScriptApp.AuthMode. FULL

Sự kiện trong ứng dụng Google Chat

Để tìm hiểu về đối tượng sự kiện trong Google Chat, hãy xem bài viết Nhận và phản hồi các lượt tương tác với ứng dụng Google Chat.

Sự kiện do thời gian điều khiển

Trình kích hoạt theo thời gian (còn gọi là trình kích hoạt đồng hồ) 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ỳ.

Dựa trên thời gian (có thể cài đặt)
authMode	Một giá trị từ enum ScriptApp.AuthMode. FULL
day-of-month	Từ 1 đến 31. Vì tên thuộc tính này chứa dấu gạch ngang nên bạn phải truy cập thông qua e['day-of-month'] thay vì ký hiệu dấu chấm. 31
day-of-week	Từ 1 (thứ Hai) đến 7 (Chủ Nhật). Vì tên thuộc tính này chứa dấu gạch ngang nên bạn phải truy cập thông qua e['day-of-week'] thay vì ký hiệu dấu chấm. 7
hour	Từ 0 đến 23. 23
minute	Từ 0 đến 59. 59
month	Từ 1 đến 12. 12
second	Từ 0 đến 59. 59
timezone	Múi giờ. UTC
triggerUid	Mã của điều kiện kích hoạt đã tạo ra sự kiện này. 4034124084959907503
week-of-year	Từ 1 đến 52. Vì tên thuộc tính này chứa dấu gạch ngang nên bạn phải truy cập thông qua e['week-of-year'] thay vì ký hiệu dấu chấm. 52
year	Năm. 2015