Pemicu yang Dapat Diinstal

Seperti pemicu sederhana, pemicu yang dapat diinstal memungkinkan Google Apps Script menjalankan fungsi secara otomatis saat peristiwa tertentu, seperti membuka dokumen, terjadi. Namun, pemicu yang dapat diinstal menawarkan lebih banyak fleksibilitas daripada pemicu sederhana: pemicu ini dapat memanggil layanan yang memerlukan otorisasi, menawarkan beberapa jenis peristiwa tambahan termasuk pemicu berbasis waktu (jam), dan dapat dikontrol secara terprogram. Untuk pemicu sederhana dan yang dapat diinstal, Apps Script meneruskan fungsi yang dipicu objek peristiwa yang berisi informasi tentang konteks terjadinya peristiwa.

Untuk mengetahui informasi selengkapnya tentang cara menggunakan pemicu di add-on, lihat Pemicu untuk add-on Google Workspace.

Pembatasan

Meskipun pemicu yang dapat diinstal menawarkan lebih banyak fleksibilitas daripada pemicu sederhana, pemicu ini tetap tunduk pada beberapa batasan:

  • Makro tidak berjalan jika file dibuka dalam mode hanya baca (lihat atau beri komentar). Untuk skrip mandiri, pengguna memerlukan setidaknya akses lihat ke file skrip agar pemicu dapat berjalan dengan benar.

  • Eksekusi skrip dan permintaan API tidak menyebabkan pemicu berjalan. Misalnya, memanggil FormResponse.submit() untuk mengirimkan respons formulir baru tidak akan menyebabkan pemicu pengiriman formulir berjalan.

    Pengecualian untuk pembatasan ini adalah Form.submitGrades(). Jika kode Anda menggunakan pemicu onFormSubmit, memanggil Form.submitGrades() akan memicu kondisi onFormSubmit dan menyebabkan infinite loop. Untuk mencegah loop tak terbatas, tambahkan kode yang memeriksa apakah nilai sudah ada sebelum memanggil submitGrades().

  • Pemicu yang dapat diinstal selalu berjalan di akun orang yang membuatnya. Misalnya, jika Anda membuat pemicu terbuka yang dapat diinstal, pemicu tersebut akan berjalan saat rekan kerja Anda membuka dokumen (jika rekan kerja Anda memiliki akses edit), tetapi pemicu tersebut berjalan sebagai akun Anda. Artinya, jika Anda membuat pemicu untuk mengirim email saat dokumen dibuka, email akan selalu dikirim dari akun Anda, bukan dari akun yang membuka dokumen. Namun, Anda dapat membuat pemicu yang dapat diinstal untuk setiap akun, yang menghasilkan satu email yang dikirim dari setiap akun.

  • Akun tertentu tidak dapat melihat pemicu yang diinstal dari akun kedua, meskipun akun pertama masih dapat mengaktifkan pemicu tersebut.

  • Pemicu yang dapat diinstal tunduk pada batas kuota pemicu Apps Script.

Pemicu berbasis waktu

Pemicu yang digerakkan waktu (juga disebut pemicu jam) mirip dengan cron job di Unix. Pemicu berbasis waktu memungkinkan skrip dieksekusi pada waktu tertentu atau pada interval berulang, sesering setiap menit atau sesedikit sekali sebulan. (Add-on dapat menggunakan pemicu berbasis waktu paling banyak sekali per jam.) Waktu mungkin sedikit diacak—misalnya, jika Anda membuat pemicu berulang pukul 09.00, Apps Script akan memilih waktu antara pukul 09.00 dan 10.00, lalu mempertahankan waktu tersebut dari hari ke hari sehingga 24 jam berlalu sebelum pemicu diaktifkan lagi.

Pemicu berbasis peristiwa

Pemicu berbasis peristiwa yang dapat diinstal secara konseptual mirip dengan pemicu sederhana seperti onOpen(), tetapi pemicu ini dapat merespons peristiwa tambahan, dan berperilaku secara berbeda.

Misalnya, pemicu terbuka yang dapat diinstal untuk Google Spreadsheet diaktifkan setiap kali spreadsheet dibuka oleh pengguna mana pun yang memiliki akses edit, seperti pemicu onOpen() sederhana. Namun, versi yang dapat diinstal dapat memanggil layanan yang memerlukan otorisasi. Versi yang dapat diinstal berjalan dengan otorisasi pengguna yang membuat pemicu, meskipun pengguna lain dengan akses edit membuka spreadsheet.

Ada beberapa pemicu yang dapat diinstal untuk aplikasi Google Workspace:

  • Pemicu open yang dapat diinstal berjalan saat pengguna membuka spreadsheet, dokumen, atau formulir yang izin pengeditannya telah diberikan kepada mereka.
  • Pemicu edit yang dapat diinstal berjalan saat pengguna mengubah nilai dalam spreadsheet.
  • Pemicu perubahan yang dapat diinstal berjalan saat pengguna mengubah struktur spreadsheet itu sendiri—misalnya, dengan menambahkan sheet baru atau menghapus kolom.
  • Pemicu pengiriman formulir yang dapat diinstal berjalan saat pengguna merespons formulir. Ada dua versi pemicu pengiriman formulir, satu untuk Google Formulir itu sendiri dan satu untuk Spreadsheet jika formulir dikirimkan ke spreadsheet.
  • Pemicu acara kalender yang dapat diinstal berjalan saat acara kalender pengguna diperbarui—dibuat, diedit, atau dihapus.

Pemicu yang dapat diinstal tersedia di skrip mandiri dan terikat. Misalnya, skrip mandiri dapat membuat pemicu yang dapat diinstal secara terprogram untuk file Google Spreadsheet arbitrer dengan memanggil TriggerBuilder.forSpreadsheet(key) dan meneruskan ID spreadsheet.

Mengelola pemicu secara manual

Untuk membuat pemicu yang dapat diinstal secara manual di editor skrip, ikuti langkah-langkah berikut:

  1. Buka project Apps Script Anda.
  2. Di sebelah kiri, klik Pemicu .
  3. Di kanan bawah, klik Tambahkan Pemicu.
  4. Pilih dan konfigurasi jenis pemicu yang ingin Anda buat.
  5. Klik Simpan.

Mengelola pemicu secara terprogram

Buat dan hapus pemicu secara terprogram dengan layanan Skrip. Mulai dengan memanggil ScriptApp.newTrigger(functionName), yang akan menampilkan TriggerBuilder.

Contoh berikut menunjukkan cara membuat dua pemicu berbasis waktu—satu yang diaktifkan setiap 6 jam, dan satu yang diaktifkan setiap hari Senin pukul 09.00 (di zona waktu yang ditetapkan untuk skrip Anda).

triggers/triggers.gs
/**
 * Creates two time-driven triggers.
 * @see https://developers.google.com/apps-script/guides/triggers/installable#time-driven_triggers
 */
function createTimeDrivenTriggers() {
  // Trigger every 6 hours.
  ScriptApp.newTrigger("myFunction").timeBased().everyHours(6).create();
  // Trigger every Monday at 09:00.
  ScriptApp.newTrigger("myFunction")
    .timeBased()
    .onWeekDay(ScriptApp.WeekDay.MONDAY)
    .atHour(9)
    .create();
}

Contoh berikutnya menunjukkan cara membuat pemicu terbuka yang dapat diinstal untuk spreadsheet. Tidak seperti pemicu onOpen() sederhana, skrip untuk pemicu yang dapat diinstal tidak perlu terikat ke spreadsheet. Untuk membuat pemicu ini dari skrip mandiri, ganti SpreadsheetApp.getActive() dengan panggilan ke SpreadsheetApp.openById(id).

triggers/triggers.gs
/**
 * Creates a trigger for when a spreadsheet opens.
 * @see https://developers.google.com/apps-script/guides/triggers/installable
 */
function createSpreadsheetOpenTrigger() {
  const ss = SpreadsheetApp.getActive();
  ScriptApp.newTrigger("myFunction").forSpreadsheet(ss).onOpen().create();
}

Untuk mengubah pemicu yang dapat diinstal yang ada secara terprogram, Anda harus menghapusnya dan membuat yang baru. Jika Anda telah menyimpan ID pemicu sebelumnya, hapus ID tersebut dengan meneruskannya sebagai argumen ke fungsi berikut.

triggers/triggers.gs
/**
 * Deletes a trigger.
 * @param {string} triggerId The Trigger ID.
 * @see https://developers.google.com/apps-script/guides/triggers/installable
 */
function deleteTrigger(triggerId) {
  // Loop over all triggers.
  const allTriggers = ScriptApp.getProjectTriggers();
  for (let index = 0; index < allTriggers.length; index++) {
    // If the current trigger is the correct one, delete it.
    if (allTriggers[index].getUniqueId() === triggerId) {
      ScriptApp.deleteTrigger(allTriggers[index]);
      break;
    }
  }
}

Sebelum membuat pemicu, pastikan fungsi terkait memiliki semua izin OAuth yang diperlukan.

Error dalam pemicu

Saat pemicu yang dapat diinstal diaktifkan, tetapi fungsi menampilkan pengecualian atau gagal dijalankan dengan berhasil, pesan error tidak akan muncul di layar Anda. Bagaimanapun, saat pemicu berbasis waktu berjalan atau pengguna lain mengaktifkan pemicu pengiriman formulir Anda, Anda mungkin tidak sedang berada di depan komputer.

Sebagai gantinya, Apps Script akan mengirim email seperti berikut:

From: noreply-apps-scripts-notifications@google.com
Subject: Summary of failures for Apps Script
Your script has recently failed to finish successfully.
A summary of the failure(s) is shown below.

Email tersebut menyertakan link untuk menonaktifkan atau mengonfigurasi ulang pemicu. Jika skrip terikat ke file Google Spreadsheet, Dokumen, atau Formulir, email juga menyertakan link ke file tersebut. Dengan link ini, Anda dapat menonaktifkan pemicu atau mengedit skrip untuk memperbaiki bug.

Untuk memecahkan masalah error dalam skrip, klik link di email notifikasi untuk membuka project skrip Anda. Setelah project terbuka, lihat log eksekusi dengan mengklik Eksekusi di panel navigasi kiri. Log menunjukkan eksekusi mana yang gagal dan menyertakan pesan error untuk membantu Anda mendiagnosis dan memperbaiki masalah.

Pemicu yang dapat diinstal yang dibuat oleh add-on tidak mengirimkan pemberitahuan email ini kepada pengguna.

Untuk meninjau semua pemicu yang terkait dengan Akun Google Anda dan menonaktifkan pemicu yang tidak lagi Anda perlukan, ikuti langkah-langkah berikut:

  1. Buka script.google.com.
  2. Di sebelah kiri, klik Pemicu Saya.
  3. Untuk menghapus pemicu, di sebelah kanan pemicu, klik Lainnya > Hapus pemicu.

Jika pemicu dinonaktifkan, notifikasi kegagalan yang sesuai juga akan dinonaktifkan. Notifikasi kegagalan adalah bagian yang melekat pada pemicu aktif. Oleh karena itu, untuk berhenti menerima semua notifikasi kegagalan untuk pemicu tertentu, nonaktifkan atau hapus pemicunya. Saat pemicu aktif, Anda hanya dapat menyesuaikan frekuensi notifikasi ini.

 Simple triggers like `onOpen()` can't be deactivated from this
 page; instead, edit the appropriate script and remove or rename
 the `onOpen()` function.

Pemicu di add-on

Selain pemicu yang dapat diinstal, gunakan pemicu manifes di add-on. Untuk mengetahui informasi selengkapnya, lihat Pemicu untuk add-on Google Workspace.