Pemicu Sederhana

Pemicu memungkinkan Apps Script menjalankan fungsi secara otomatis saat peristiwa tertentu, seperti membuka dokumen. Pemicu sederhana adalah serangkaian fungsi cadangan yang dibangun di 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 dibandingkan pemicu sederhana, tetapi harus diaktifkan sebelum digunakan. Untuk keduanya jenis pemicu, Apps Script akan meneruskan fungsi yang dipicu ke objek peristiwa yang berisi informasi tentang konteks di mana peristiwa tersebut terjadi.

Memulai

Untuk menggunakan pemicu sederhana, cukup buat fungsi yang menggunakan salah satu nama fungsi yang dicadangkan:

• onOpen(e) dijalankan saat pengguna membuka spreadsheet, dokumen, presentasi, atau formulir yang dapat diedit pengguna.
• onInstall(e) dijalankan 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 di spreadsheet.
• doGet(e) berjalan 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.

Parameter e dalam nama fungsi di atas adalah objek peristiwa yang diteruskan ke fungsi tersebut. Objek ini berisi informasi tentang konteks yang menyebabkan pemicu untuk diaktifkan, tetapi penggunaannya bersifat opsional.

Pembatasan

Karena {i>trigger<i} sederhana diaktifkan secara otomatis, tanpa meminta pengguna untuk otorisasi, mereka tunduk pada beberapa batasan:

• Skrip harus terikat dengan File Spreadsheet, Slide, Dokumen, atau Formulir, atau berupa add-on yang memperluas salah satu aplikasi tersebut.
• Fitur ini 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() mengedit sel tidak menyebabkan pemicu onEdit spreadsheet dijalankan.
• Admin tersebut 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.
• Pengguna dapat mengubah file yang terikat dengannya, tetapi tidak dapat mengakses file lain karena akan membutuhkan otorisasi.
• Mereka mungkin dapat atau tidak dapat menentukan identitas pengguna saat ini, bergantung pada serangkaian pembatasan keamanan yang kompleks.
• Iklan tidak boleh berjalan lebih dari 30 detik.
• Dalam keadaan tertentu, Add-on Editor menjalankan onOpen(e) dan onEdit(e) pemicu sederhana dalam mode tanpa otorisasi yang menampilkan beberapa detail tambahan. Untuk informasi selengkapnya, lihat panduan siklus proses otorisasi add-on.
• Pemicu sederhana tunduk kepada pemicu Apps Script batas kuota.

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. ( tidak berjalan saat merespons formulir, hanya saat membuka formulir untuk mengeditnya.) onOpen(e) paling umum digunakan untuk menambahkan item menu ke Google Spreadsheet, Slide, Dokumen, atau Formulir.

/**
 * The event handler triggered when opening the spreadsheet.
 * @param {Event} e The onOpen event.
 * @see https://developers.google.com/apps-script/guides/triggers#onopene
 */
function onOpen(e) {
  // Add a custom menu to the spreadsheet.
  SpreadsheetApp.getUi() // Or DocumentApp, SlidesApp, or FormApp.
      .createMenu('Custom Menu')
      .addItem('First item', 'menuItem1')
      .addToUi();
}

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 Google Workspace Marketplace situs Anda. Perlu diketahui bahwa ada batasan tertentu tentang hal yang dapat dilakukan onInstall(e), pelajari lebih lanjut otorisasi. Penggunaan onInstall(e) yang paling umum adalah cukup memanggil onOpen(e) untuk menambahkan menu kustom. Bagaimanapun, ketika add-on diinstal, file sudah terbuka, sehingga onOpen(e) tidak berjalan sendiri kecuali jika file dibuka kembali.

/**
 * The event handler triggered when installing the add-on.
 * @param {Event} e The onInstall event.
 * @see https://developers.google.com/apps-script/guides/triggers#oninstalle
 */
function onInstall(e) {
  onOpen(e);
}

onEdit(e)

Pemicu onEdit(e) berjalan secara otomatis saat pengguna mengubah nilai sel di {i>spreadsheet<i}. Sebagian besar pemicu onEdit(e) menggunakan informasi di objek peristiwa agar dapat merespons dengan tepat. Misalnya, fungsi onEdit(e) di bawah ini menetapkan komentar pada sel yang mencatat terakhir kali diedit.

/**
 * The event handler triggered when editing the spreadsheet.
 * @param {Event} e The onEdit event.
 * @see https://developers.google.com/apps-script/guides/triggers#onedite
 */
function onEdit(e) {
  // Set a comment on the edited cell to indicate when it was changed.
  const range = e.range;
  range.setNote('Last modified: ' + new Date());
}

onSelectionChange(e)

Pemicu onSelectionChange(e) berjalan secara otomatis saat pengguna mengubah pilihan di {i>spreadsheet<i}. Untuk mengaktifkan pemicu ini, Anda harus me-refresh halaman {i>spreadsheet<i} setelah pemicu ditambahkan dan setiap kali {i>spreadsheet<i} dibuka.

Jika pilihan berpindah di antara beberapa sel dalam waktu singkat, beberapa sel peristiwa perubahan mungkin dilewati untuk mengurangi latensi. Misalnya, jika ada banyak pilihan perubahan dibuat dalam waktu dua detik dari satu sama lain, hanya perubahan pertama dan terakhir perubahan pilihan akan mengaktifkan pemicu onSelectionChange(e).

Dalam contoh di bawah ini, jika sel kosong dipilih, fungsi onSelectionChange(e) akan menetapkan latar belakang menjadi merah.

/**
 * The event handler triggered when the selection changes in the spreadsheet.
 * @param {Event} e The onSelectionChange event.
 * @see https://developers.google.com/apps-script/guides/triggers#onselectionchangee
 */
function onSelectionChange(e) {
  // Set background to red if a single empty cell is selected.
  const range = e.range;
  if (range.getNumRows() === 1 &&
    range.getNumColumns() === 1 &&
    range.getCell(1, 1).getValue() === '') {
    range.setBackground('red');
  }
}

doGet(e) dan doPost(e)

Pemicu doGet(e) berjalan secara otomatis saat pengguna mengunjungi aplikasi web atau program mengirimkan permintaan GET HTTP menjadi aplikasi web. doPost(e) berjalan saat program mengirim permintaan POST HTTP ke aplikasi web Anda. Pemicu ini ditunjukkan lebih banyak dalam panduan untuk aplikasi web, layanan HTML, dan Layanan konten. Perhatikan bahwa doGet(e) dan doPost(e) tidak tunduk kepada batasan yang tercantum di atas.

Jenis pemicu yang tersedia

Jika pembatasan pada pemicu sederhana membuat mereka tidak dapat memenuhi kebutuhan Anda, pemicu yang dapat diinstal mungkin bisa berfungsi. Tabel di bawah ini meringkas jenis pemicu yang tersedia untuk setiap jenis acara. Misalnya, Google Spreadsheet, Slide, Formulir, dan Semua Dokumen mendukung pemicu terbuka sederhana, tetapi hanya yang mendukung Spreadsheet, Dokumen, dan Formulir pemicu terbuka yang dapat diinstal.

Acara	Pemicu sederhana	Pemicu yang dapat diinstal
Buka	function onOpen(e)
Edit	function onEdit(e)
Perubahan pilihan	function onSelectionChange(e)
Instal	function onInstall(e)
Ubah
Pengiriman formulir
Berdasarkan waktu (jam)
Dapatkan	function doGet(e)
Posting	function doPost(e)

* Peristiwa terbuka untuk Google Formulir tidak terjadi saat pengguna membuka formulir untuk merespons, namun saat editor membuka formulir untuk mengubahnya.