Pemicu memungkinkan Apps Script menjalankan fungsi secara otomatis saat peristiwa tertentu, seperti membuka dokumen, terjadi. Pemicu sederhana adalah serangkaian
fungsi khusus yang dibuat ke dalam Apps Script, seperti fungsi onOpen(e)
,
yang dijalankan saat pengguna membuka file Google Dokumen, Spreadsheet, Slide, atau Formulir.
Pemicu yang dapat diinstal menawarkan lebih banyak
kemampuan daripada pemicu sederhana, tetapi harus diaktifkan sebelum digunakan. Untuk kedua jenis pemicu, Apps Script meneruskan objek peristiwa ke fungsi yang dipicu yang berisi informasi tentang konteks terjadinya peristiwa.
Memulai
Untuk menggunakan pemicu sederhana, cukup buat fungsi yang menggunakan salah satu nama fungsi yang dicadangkan ini:
onOpen(e)
berjalan saat pengguna membuka spreadsheet, dokumen, presentasi, atau formulir yang izin pengeditannya dimiliki pengguna.onInstall(e)
berjalan saat pengguna menginstal add-on Editor dari dalam Google Dokumen, Spreadsheet, Slide, atau Formulir.onEdit(e)
berjalan saat pengguna mengubah nilai dalam spreadsheet.onSelectionChange(e)
berjalan saat pengguna mengubah pilihan dalam spreadsheet.doGet(e)
berjalan saat pengguna mengunjungi aplikasi web atau program mengirim permintaan HTTPGET
ke aplikasi web.doPost(e)
berjalan saat program mengirim permintaanPOST
HTTP ke aplikasi web.
Parameter e
dalam nama fungsi di atas adalah
objek peristiwa yang diteruskan ke
fungsi. Objek ini berisi informasi tentang konteks yang menyebabkan
pemicu diaktifkan, tetapi penggunaannya bersifat opsional.
Pembatasan
Karena pemicu sederhana diaktifkan secara otomatis, tanpa meminta otorisasi pengguna, pemicu ini tunduk pada beberapa batasan:
- Skrip harus terikat ke file Google Spreadsheet, Slide, Dokumen, atau Formulir, atau berupa add-on yang memperluas salah satu aplikasi tersebut.
- Add-on tidak berjalan jika file dibuka dalam mode hanya baca (lihat atau komentar).
- Eksekusi skrip dan permintaan API tidak menyebabkan pemicu berjalan. Misalnya,
memanggil
Range.setValue()
untuk mengedit sel tidak akan menyebabkan pemicuonEdit
spreadsheet berjalan. - Mereka tidak dapat mengakses layanan yang memerlukan otorisasi. Misalnya, pemicu sederhana tidak dapat mengirim email karena layanan Gmail memerlukan otorisasi, tetapi pemicu sederhana dapat menerjemahkan frasa dengan layanan Bahasa, yang bersifat anonim.
- Mereka dapat mengubah file yang terikat dengan mereka, tetapi tidak dapat mengakses file lain karena memerlukan otorisasi.
- Mereka mungkin dapat atau tidak dapat menentukan identitas pengguna saat ini, bergantung pada kumpulan batasan keamanan yang kompleks.
- Iklan ini tidak dapat berjalan lebih dari 30 detik.
- Dalam keadaan tertentu, add-on Editor menjalankan pemicu sederhana
onOpen(e)
danonEdit(e)
dalam mode tanpa otorisasi yang menimbulkan beberapa komplikasi tambahan. Untuk mengetahui informasi selengkapnya, lihat panduan siklus proses otorisasi add-on. - Pemicu sederhana tunduk pada batas kuota pemicu Apps Script.
Pembatasan ini tidak berlaku untuk doGet(e)
atau doPost(e)
.
onOpen(e)
Pemicu onOpen(e)
berjalan secara otomatis saat pengguna membuka spreadsheet, dokumen, presentasi, atau formulir yang izin pengeditannya dimiliki oleh pengguna tersebut. (Pemicu
tidak berjalan saat merespons formulir, hanya saat membuka formulir untuk
mengeditnya.) onOpen(e)
paling umum digunakan untuk menambahkan
item menu kustom ke Google Spreadsheet, Slide, Dokumen, atau
Formulir.
onInstall(e)
Pemicu onInstall(e)
berjalan secara otomatis saat pengguna menginstal
add-on Editor dari dalam
Google Dokumen, Spreadsheet, Slide, atau Formulir. Pemicu tidak akan berjalan saat pengguna menginstal add-on dari situs Google Workspace Marketplace. Perhatikan bahwa
ada batasan tertentu terkait hal yang dapat dilakukan onInstall(e)
, pelajari lebih lanjut
otorisasi.
Penggunaan onInstall(e)
yang paling umum adalah dengan memanggil onOpen(e)
untuk menambahkan menu kustom. Bagaimanapun, saat add-on diinstal, file sudah terbuka,
sehingga onOpen(e)
tidak berjalan dengan sendirinya kecuali file dibuka kembali.
onEdit(e)
Pemicu onEdit(e)
berjalan secara otomatis saat pengguna mengubah nilai sel mana pun dalam spreadsheet. Sebagian besar pemicu onEdit(e)
menggunakan informasi dalam
objek peristiwa untuk merespons dengan tepat.
Misalnya, fungsi onEdit(e)
di bawah menetapkan komentar pada sel yang
mencatat waktu terakhir kali sel tersebut diedit.
onSelectionChange(e)
Pemicu onSelectionChange(e)
berjalan secara otomatis saat pengguna mengubah
pilihan dalam spreadsheet. Untuk mengaktifkan pemicu ini, Anda harus memuat ulang
spreadsheet setelah pemicu ditambahkan dan setiap kali spreadsheet dibuka.
Jika pilihan berpindah di antara beberapa sel dalam waktu singkat, beberapa peristiwa
perubahan pilihan mungkin dilewati untuk mengurangi latensi. Misalnya, jika banyak perubahan
pemilihan dilakukan dalam waktu dua detik satu sama lain, hanya perubahan
pemilihan pertama dan terakhir yang akan mengaktifkan pemicu onSelectionChange(e)
.
Dalam contoh di bawah,
jika sel kosong dipilih, fungsi onSelectionChange(e)
akan menyetel latar belakang sel ke merah.
doGet(e)
dan doPost(e)
Pemicu doGet(e)
berjalan secara otomatis saat pengguna mengunjungi
aplikasi web atau program mengirim permintaan HTTP GET
ke aplikasi web. doPost(e)
berjalan saat program mengirim permintaan HTTP POST
ke
aplikasi web. Pemicu ini dijelaskan lebih lanjut dalam panduan untuk
aplikasi web, layanan HTML,
dan layanan Konten. Perhatikan bahwa doGet(e)
dan
doPost(e)
tidak tunduk pada batasan yang tercantum di atas.
Jenis pemicu yang tersedia
Jika pembatasan pada pemicu sederhana mencegahnya memenuhi kebutuhan Anda, pemicu yang dapat diinstal mungkin dapat digunakan. Tabel di bawah meringkas jenis pemicu yang tersedia untuk setiap jenis peristiwa. Misalnya, Google Spreadsheet, Slide, Formulir, dan Dokumen semuanya mendukung pemicu pembukaan sederhana, tetapi hanya Spreadsheet, Dokumen, dan Formulir yang mendukung pemicu pembukaan yang dapat diinstal.
Acara | Pemicu sederhana | Pemicu yang dapat diinstal |
---|---|---|
Buka |
![]() ![]() ![]() ![]()
|
![]() ![]() ![]() |
Edit |
![]()
|
![]() |
Perubahan pilihan |
![]()
|
|
Instal |
![]() ![]() ![]() ![]()
|
|
Ubah |
![]() |
|
Kirim formulir |
![]() ![]() |
|
Berdasarkan waktu (jam) |
![]() ![]() ![]() ![]() ![]() |
|
Dapatkan |
![]()
|
|
Posting |
![]()
|
* Peristiwa buka untuk Google Formulir tidak terjadi saat pengguna membuka formulir untuk merespons, melainkan saat editor membuka formulir untuk mengubahnya.