Dengan pemicu, Apps Script dapat menjalankan fungsi secara otomatis saat peristiwa tertentu, seperti membuka dokumen, terjadi. Pemicu sederhana adalah sekumpulan fungsi yang dicadangkan dan telah terintegrasi 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 fungsi objek peristiwa yang berisi informasi tentang konteks tempat peristiwa terjadi ke fungsi yang dipicu.
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 di spreadsheet.onSelectionChange(e)
berjalan saat pengguna mengubah pilihan di spreadsheet.doGet(e)
berjalan saat pengguna mengunjungi aplikasi web atau program mengirimkan permintaanGET
HTTP 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.
Batasan
Karena pemicu sederhana diaktifkan secara otomatis, tanpa meminta izin kepada pengguna, pemicu tersebut tunduk pada beberapa batasan:
- Skrip harus terikat dengan file Google Spreadsheet, Slide, Dokumen, atau Formulir, atau berupa add-on yang memperluas salah satu aplikasi tersebut.
- Kedua tugas tersebut 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 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 dengannya, tetapi tidak dapat mengakses file lain karena hal itu akan memerlukan otorisasi.
- Mereka mungkin dapat atau tidak dapat menentukan identitas pengguna saat ini, tergantung pada kumpulan pembatasan keamanan yang kompleks.
- Iklan Display responsif tidak dapat berjalan lebih dari 30 detik.
- Dalam situasi tertentu,
Add-on Editor menjalankan pemicu sederhana
onOpen(e)
danonEdit(e)
dalam mode tanpa otorisasi yang menyajikan beberapa detail tambahan. Untuk mengetahui informasi selengkapnya, lihat panduan siklus proses otorisasi add-on. - Pemicu sederhana bergantung pada batas kuota pemicu Apps Script.
Batasan 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 dapat mereka edit. (Pemicu tidak berjalan saat merespons formulir, hanya saat membuka formulir untuk mengeditnya.) onOpen(e)
paling sering 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. Perlu diperhatikan bahwa
ada batasan tertentu yang dapat dilakukan onInstall(e)
, pelajari
otorisasi lebih lanjut.
Penggunaan onInstall(e)
yang paling umum adalah dengan memanggil onOpen(e)
untuk menambahkan
menu kustom. Lagi pula, saat add-on diinstal, file tersebut akan terbuka
sehingga onOpen(e)
tidak akan berjalan sendiri kecuali jika file dibuka kembali.
onEdit(e)
Pemicu onEdit(e)
berjalan secara otomatis saat pengguna mengubah nilai sel di spreadsheet. Sebagian besar pemicu onEdit(e)
menggunakan informasi di
objek peristiwa untuk merespons dengan tepat.
Misalnya, fungsi onEdit(e)
di bawah ini menetapkan komentar pada sel yang merekam saat terakhir kali 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 antara beberapa sel dalam waktu singkat, beberapa peristiwa perubahan
pilihan mungkin dilewati untuk mengurangi latensi. Misalnya, jika banyak perubahan
pilihan dilakukan dalam waktu dua detik dari satu sama lain, hanya perubahan pilihan
pertama dan terakhir yang akan mengaktifkan pemicu onSelectionChange(e)
.
Pada contoh di bawah, jika sel kosong dipilih, fungsi onSelectionChange(e)
menetapkan latar belakang sel menjadi merah.
doGet(e)
dan doPost(e)
Pemicu doGet(e)
berjalan secara otomatis saat pengguna mengunjungi aplikasi web atau program mengirimkan permintaan GET
HTTP ke aplikasi web. doPost(e)
berjalan saat program mengirimkan permintaan POST
HTTP ke aplikasi web. Pemicu ini ditunjukkan lebih banyak di 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 batasan pada pemicu sederhana mencegahnya memenuhi kebutuhan Anda, pemicu yang dapat diinstal mungkin berfungsi sebagai gantinya. Tabel di bawah ini meringkas jenis pemicu yang tersedia untuk setiap jenis peristiwa. Misalnya, Google Spreadsheet, Slide, Formulir, dan Dokumen mendukung pemicu terbuka sederhana, tetapi hanya Spreadsheet, Dokumen, dan Formulir yang mendukung pemicu terbuka yang dapat diinstal.
Peristiwa | Pemicu sederhana | Pemicu yang dapat diinstal |
---|---|---|
Buka |
![]() ![]() ![]() ![]()
|
![]() ![]() ![]() |
Edit |
![]()
|
![]() |
Perubahan pilihan |
![]()
|
|
Menginstal |
![]() ![]() ![]() ![]()
|
|
Transfer |
![]() |
|
Pengiriman formulir |
![]() ![]() |
|
Berdasarkan waktu (jam) |
![]() ![]() ![]() ![]() ![]() ![]() |
|
Dapatkan |
![]() ![]()
|
|
Komunitas |
![]() ![]()
|
* Peristiwa terbuka untuk Google Formulir tidak terjadi saat pengguna membuka formulir untuk merespons, melainkan ketika editor membuka formulir untuk mengubahnya.