Pemicu Apps Script menyebabkan skrip tertentu fungsi (fungsi pemicu) untuk dieksekusi setiap kali peristiwa yang ditentukan apa yang terjadi. Hanya peristiwa tertentu yang dapat menyebabkan pemicu diaktifkan, dan setiap peristiwa Aplikasi Google Workspace mendukung berbagai peristiwa.
Saat pemicu diaktifkan, objek peristiwa akan dibuat. Struktur JSON ini berisi detail tentang peristiwa yang terjadi. Informasi dalam peristiwa struktur objek disusun secara berbeda berdasarkan jenis pemicu.
Setelah objek peristiwa dibuat, Apps Script akan meneruskannya sebagai parameter ke
fungsi pemicu. Fungsi pemicu adalah fungsi callback yang harus Anda
terapkan sendiri, untuk mengambil tindakan apa pun
yang sesuai untuk menanggapi
peristiwa. Misalnya, di sebuah Add-on Editor, pemicu
digunakan untuk membuat item menu {i>
add-on<i} ketika dokumen dibuka. Dalam hal ini, Anda
terapkan pada fungsi pemicu onOpen(e)
untuk membuat item menu yang ditambahkan add-on
kebutuhan Anda, mungkin dengan menggunakan data dalam objek peristiwa.
Halaman ini memberikan panduan tentang penggunaan pemicu di editor project add-on.
Jenis pemicu Add-on Editor
Anda dapat menggunakan sebagian besar jenis pemicu umum yang tersedia untuk project Apps Script di Add-on Editor, termasuk pemicu sederhana dan sebagian besar pemicu yang dapat diinstal. Tujuan tipe pemicu yang tersedia bergantung pada aplikasi yang diperluas.
Tabel berikut menunjukkan jenis pemicu sederhana dan dapat diinstal yang Add-on Editor dapat digunakan, dan menyediakan link ke objek peristiwa yang sesuai:
Acara | Objek peristiwa | Pemicu sederhana | Pemicu yang dapat diinstal |
---|---|---|---|
Buka File editor akan terbuka. |
Objek peristiwa Docs onOpen Objek peristiwa onOpen Formulir Objek peristiwa onOpen Spreadsheet Objek peristiwa onOpen Slide |
![]() ![]() ![]() ![]()
|
![]() ![]() ![]() |
Instal Add-on akan diinstal. |
objek peristiwa onInstall |
![]() ![]() ![]() ![]()
|
|
Edit Konten sel spreadsheet diubah. |
Objek peristiwa onEdit Spreadsheet |
![]()
|
![]() |
Perubahan Konten dalam sheet diedit atau diformat. |
Objek peristiwa onChange Spreadsheet |
![]() |
|
Pengiriman formulir Formulir Google dikirim. |
Objek peristiwa pengiriman formulir Formulir Objek peristiwa pengiriman formulir Spreadsheet |
![]() ![]() |
|
Berbasis waktu (jam) Pemicu diaktifkan pada waktu atau interval yang ditentukan. |
Objek peristiwa berbasis waktu |
![]() ![]() ![]() ![]() |
* Peristiwa terbuka untuk Google Formulir tidak terjadi saat pengguna membuka formulir untuk merespons, namun saat editor membuka formulir untuk mengubahnya.
Pemicu sederhana di add-on
Pemicu sederhana menggunakan kumpulan nama fungsi, tidak dapat menggunakan layanan yang membutuhkan otorisasi, dan diaktifkan secara otomatis untuk digunakan. Dalam beberapa kasus, peristiwa pemicu yang sederhana bisa ditangani oleh pemicu yang dapat diinstal.
Anda dapat menambahkan pemicu sederhana ke add-on hanya dengan menerapkan fungsi dengan salah satu nama yang dicadangkan berikut:
onOpen(e)
dijalankan saat pengguna membuka dokumen, spreadsheet, atau presentasi.onOpen(e)
juga dapat dieksekusi saat formulir dibuka di editor (tetapi tidak saat menanggapi formulir). Fungsi ini hanya dijalankan jika pengguna memiliki izin akses untuk mengedit file yang dipertanyakan, dan yang paling sering digunakan untuk membuat item menu.onInstall(e)
dijalankan saat pengguna menginstal add-on. BiasanyaonInstall(e)
hanya digunakan untuk memanggilonOpen(e)
; Tindakan ini memastikan menu add-on muncul segera setelah penginstalan tanpa mengharuskan pengguna memuat ulang halaman.onEdit(e)
dijalankan saat pengguna mengubah nilai sel dalam spreadsheet. Pemicu ini tidak diaktifkan sebagai respons terhadap perpindahan sel, pemformatan, atau perubahan lain yang tidak mengubah nilai sel.
Pembatasan
Pemicu sederhana di add-on tunduk pada batasan yang mengatur di jenis project Apps Script lainnya. Perhatikan hal-hal berikut batasan saat mendesain add-on:
- Pemicu sederhana tidak berjalan jika file dibuka hanya-baca (lihat atau komentar). Perilaku ini mencegah menu add-on Anda diisi.
- Dalam keadaan tertentu, Add-on Editor menjalankan
onOpen(e)
danonEdit(e)
pemicu sederhana dalam mode tanpa otorisasi. Mode ini menghadirkan beberapa detail tambahan seperti yang diuraikan dalam model otorisasi add-on. - Pemicu sederhana tidak dapat menggunakan layanan atau mengambil tindakan lain yang memerlukan otorisasi, kecuali sebagai diuraikan dalam model otorisasi add-on.
- Pemicu sederhana tidak dapat berjalan lebih dari 30 detik. Pastikan untuk meminimalkan jumlah pemrosesan yang dilakukan menggunakan fungsi pemicu sederhana.
- Pemicu sederhana tunduk kepada pemicu Apps Script batas kuota.
Pemicu yang dapat diinstal di add-on
Add-on dapat
membuat dan mengubah pemicu yang dapat diinstal secara terprogram
dengan layanan Apps Script Script
. atau Gemini Enterprise
Pemicu yang dapat diinstal tidak dapat dibuat secara manual. Tidak seperti {i>trigger<i}
sederhana, {i>trigger<i}
{i>Installable trigger<i} dapat menggunakan
layanan yang memerlukan otorisasi.
Pemicu yang dapat diinstal di add-on tidak mengirim email error kepada pengguna ketika mereka menemukan {i>error<i}, karena dalam kebanyakan kasus, pengguna tidak dapat untuk mengatasi masalah tersebut. Karena itu, Anda harus merancang {i>add-on<i} untuk menangani {i>error<i} dengan baik atas nama pengguna bila memungkinkan.
Add-on dapat menggunakan pemicu yang dapat diinstal berikut:
- Pemicu Open yang dapat diinstal dijalankan saat pengguna membuka dokumen, spreadsheet, atau saat formulir dibuka di editor (tetapi tidak saat merespons pada formulir).
- Pemicu Edit yang dapat diinstal dijalankan saat pengguna mengubah nilai sel dalam {i>spreadsheet<i}. Pemicu ini tidak diaktifkan sebagai respons terhadap pemformatan atau perubahan yang tidak mengubah nilai sel.
- Pemicu perubahan yang dapat diinstal dijalankan saat pengguna membuat perubahan apa pun dalam {i>spreadsheet<i}, termasuk pemformatan dan modifikasi pada {i>spreadsheet<i} itu sendiri (seperti menambahkan baris).
Pemicu pengiriman formulir yang dapat diinstal dijalankan saat respons Formulir Google dikirimkan.
Pemicu berbasis waktu (disebut juga pemicu jam) yang dipicu pada waktu tertentu atau berulang kali pada dengan interval waktu yang teratur.
Mengizinkan pemicu yang dapat diinstal
Biasanya, jika pengembang memperbarui {i>add-on<i} untuk menggunakan layanan baru yang memerlukan otorisasi tambahan, pengguna akan diminta untuk memberikan otorisasi ulang ke add-on berapa kali mereka menggunakannya.
Namun, add-on yang menggunakan pemicu menemui tantangan otorisasi khusus. Bayangkan add-on yang menggunakan pemicu untuk memantau pengiriman formulir: sebuah formulir kreator dapat mengizinkan add-on ini saat pertama kali menggunakannya, lalu menyerahkannya kepada berjalan selama berbulan-bulan atau bertahun-tahun tanpa pernah membuka kembali formulir. Jika developer add-on mengupdate add-on untuk menggunakan layanan baru yang memerlukan otorisasi tambahan, pembuat formulir tidak akan pernah melihat dialog otorisasi ulang karena mereka tidak pernah membuka kembali formulir, dan add-on akan berhenti berfungsi.
Tidak seperti pemicu di project Apps Script reguler, pemicu di
add-on terus aktif meskipun perlu otorisasi ulang. Namun, skrip
tetap gagal jika menemukan baris kode
yang membutuhkan otorisasi skrip
tidak dimiliki oleh Google. Untuk menghindari situasi ini, developer dapat menggunakan metode ini
ScriptApp.getAuthorizationInfo()
untuk membuka akses ke bagian kode yang telah berubah di antara versi yang dipublikasikan
add-on ini.
Di bawah ini adalah contoh struktur yang direkomendasikan untuk digunakan dalam fungsi pemicu untuk menghindari kesalahan otorisasi. Contoh fungsi pemicu merespons peristiwa pengiriman formulir dalam add-on Google Spreadsheet dan, jika otorisasi ulang diperlukan, mengirim email pemberitahuan kepada pengguna add-on menggunakan HTML dengan template.
Code.gs
authorizationemail.html
Pembatasan
Pemicu yang dapat diinstal di add-on tunduk pada pembatasan yang mengatur pemicu yang dapat diinstal di jenis project Apps Script lainnya.
Selain pembatasan ini, beberapa pembatasan berlaku untuk di add-on, khususnya:
- Setiap add-on hanya dapat memiliki satu pemicu dari setiap jenis, per pengguna, per dokumen. Misalnya, dalam {i>spreadsheet<i} tertentu, pengguna tertentu hanya dapat memiliki satu edit meskipun pengguna juga dapat memiliki pemicu pengiriman formulir berbasis waktu dalam {i>spreadsheet<i} yang sama. Pengguna lain yang memiliki akses ke {i>spreadsheet<i} yang sama bisa saja memiliki kumpulan {i>trigger<i} yang terpisah.
- Add-on hanya dapat membuat pemicu untuk file yang menggunakan add-on tersebut. Artinya, add-on yang digunakan di Google Dokumen A tidak dapat membuat pemicu untuk memantau kapan Google Dokumen B dibuka.
- Pemicu berbasis waktu tidak dapat berjalan lebih dari sekali per jam.
- Add-on tidak secara otomatis mengirim email kepada pengguna bila kode dijalankan oleh yang dapat diinstal akan menampilkan pengecualian. Terserah pengembang untuk memeriksa dan menangani kasus kegagalan dengan baik.
- Pemicu add-on berhenti diaktifkan dalam salah satu situasi berikut:
- Jika add-on di-uninstal oleh pengguna,
- Jika add-on dinonaktifkan dalam dokumen (jika diaktifkan kembali, pemicu beroperasi kembali), atau
- Jika developer membatalkan publikasi add-on atau mengirimkan versi yang rusak ke add-on store.
- Fungsi pemicu add-on dijalankan hingga mencapai kode yang menggunakan layanan tidak sah, di mana mereka berhenti. Hal ini hanya berlaku jika add-on dipublikasikan; pemicu yang sama dalam project Apps Script reguler atau add-on yang tidak dipublikasikan tidak akan dijalankan sama sekali jika ada bagian skrip yang memerlukan otorisasi.
- Pemicu yang dapat diinstal tunduk kepada pemicu Apps Script batas kuota.