Pemicu yang Dapat Diinstal

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Seperti pemicu sederhana, pemicu yang dapat diinstal memungkinkan 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, pemicu tersebut menawarkan beberapa jenis peristiwa tambahan termasuk pemicu berbasis waktu (jam), dan dapat dikontrol secara terprogram. Untuk pemicu yang sederhana dan dapat diinstal, Apps Script meneruskan fungsi objek peristiwa yang dipicu, yang berisi informasi tentang konteks terjadinya peristiwa tersebut.

Batasan

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

  • Layanan ini tidak berjalan jika file dibuka dalam mode hanya baca (lihat atau komentar). Untuk skrip mandiri, pengguna memerlukan setidaknya akses lihat ke file skrip agar pemicu dapat berjalan dengan baik.
  • Eksekusi skrip dan permintaan API tidak menyebabkan pemicu dijalankan. Misalnya, memanggil FormResponse.submit() untuk mengirimkan respons formulir baru tidak akan memicu pemicu pengiriman formulir untuk dijalankan.

  • Pemicu yang dapat diinstal selalu berjalan di bawah 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 Anda memiliki akses edit), tetapi akan berjalan sebagai akun Anda. Artinya, jika Anda membuat pemicu untuk mengirim email saat dokumen dibuka, email selalu dikirim dari akun Anda, tidak harus akun yang membuka dokumen. Namun, Anda dapat membuat pemicu yang dapat diinstal untuk setiap akun, yang akan 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 berdasarkan waktu

Pemicu berdasarkan waktu (juga disebut pemicu jam) mirip dengan cron job di Unix. Pemicu berdasarkan waktu memungkinkan skrip dieksekusi pada waktu tertentu atau pada interval yang berulang, sesering setiap menit, atau jarang per bulan. (Perhatikan bahwa add-on dapat menggunakan pemicu berbasis waktu paling banyak sekali per jam.) Waktu mungkin sedikit acak — misalnya, jika Anda membuat pemicu berulang pukul 9 pagi, Apps Script akan memilih waktu antara pukul 09.00 dan 10.00, lalu menjaga waktu tersebut konsisten dari hari ke hari sehingga 24 jam berlalu sebelum pemicu diaktifkan lagi.

Pemicu berdasarkan peristiwa

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

Misalnya, pemicu terbuka yang dapat diinstal untuk Google Spreadsheet akan 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 Google Workspace aplikasi:

  • Pemicu buka yang dapat diinstal berjalan saat pengguna membuka spreadsheet, dokumen, atau formulir yang izinnya mereka miliki untuk diedit.
  • 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.

Anda dapat menggunakan pemicu yang dapat diinstal dalam skrip mandiri dan terikat. Misalnya, skrip mandiri dapat secara terprogram membuat pemicu yang dapat diinstal 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:

Editor baru

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

Editor lama

  1. Dari editor skrip, pilih Edit > Pemicu project saat ini.
  2. Klik link yang bertuliskan: Tidak ada pemicu yang disiapkan. Klik di sini untuk menambahkannya sekarang.
  3. Di bagian Run, pilih nama fungsi yang ingin dipicu.
  4. Di bagian Peristiwa, pilih Berbasis waktu atau Aplikasi Google yang diikat dengan skrip (misalnya, Dari spreadsheet).
  5. Pilih dan konfigurasikan jenis pemicu yang ingin Anda buat (misalnya, Timer jam yang menjalankan Setiap jam atau pemicu Saat terbuka).
  6. Secara opsional, klik Notifikasi untuk mengonfigurasi cara dan waktu Anda dihubungi melalui email jika fungsi yang dipicu gagal.
  7. Klik Simpan.

Mengelola pemicu secara terprogram

Anda juga dapat membuat dan menghapus pemicu secara terprogram dengan Layanan skrip. Mulai dengan memanggil ScriptApp.newTrigger(functionName), yang menampilkan TriggerBuilder.

Contoh berikut menunjukkan cara membuat dua pemicu berbasis waktu, yaitu pemicu yang diaktifkan setiap 6 jam, dan pemicu yang diaktifkan setiap hari Senin pada pukul 09.00 (dalam zona waktu tempat skrip ditetapkan).

pemicu/pemicu.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. Perhatikan bahwa, tidak seperti pemicu onOpen() sederhana, skrip untuk pemicu yang dapat diinstal tidak perlu terikat ke spreadsheet. Untuk membuat pemicu ini dari skrip mandiri, cukup ganti SpreadsheetApp.getActive() dengan panggilan ke SpreadsheetApp.openById(id).

pemicu/pemicu.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 secara terprogram, Anda harus menghapusnya dan membuat yang baru. Jika sebelumnya telah menyimpan ID pemicu, Anda dapat menghapusnya dengan meneruskan ID tersebut sebagai argumen ke fungsi di bawah ini.

pemicu/pemicu.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;
    }
  }
}

Error pada pemicu

Saat pemicu yang dapat diinstal diaktifkan, tetapi fungsi memunculkan pengecualian atau gagal dijalankan, Anda tidak akan melihat pesan error di layar. Lagi pula, saat pemicu berbasis waktu berjalan atau pengguna lain mengaktifkan pemicu pengiriman formulir, Anda bahkan mungkin tidak menggunakan komputer.

Sebagai gantinya, Apps Script akan mengirimkan email kepada Anda seperti berikut:

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

Email tersebut berisi link untuk menonaktifkan atau mengonfigurasi ulang pemicu. Jika skrip terikat dengan 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 meninjau semua pemicu yang terkait dengan Akun Google Anda dan menonaktifkan pemicu yang tidak diperlukan lagi, ikuti langkah-langkah berikut:

Editor baru

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

Editor lama

  1. Buka editor skrip dengan membuka skrip apa pun atau membuka script.google.com.
  2. Klik Edit > Semua pemicu Anda. Jika Anda baru saja membuat skrip baru, editor skrip akan meminta Anda untuk memberikan nama pada skrip terlebih dahulu.
  3. Dialog akan mencantumkan setiap pemicu sederhana atau yang dapat diinstal yang terkait dengan akun Anda. Dari dialog ini, Anda tidak dapat menentukan skrip mana yang menggunakan pemicu tertentu, tetapi jika Anda mengenali nama fungsi untuk pemicu yang dapat diinstal dan mengetahui bahwa Anda tidak memerlukan pemicu lagi, Anda dapat menghapus pemicu tersebut dengan mengklik ikon X di sebelah kiri nama fungsi. Pemicu sederhana seperti onOpen() tidak dapat dinonaktifkan dari dialog ini. Sebagai gantinya, Anda harus mengedit skrip yang sesuai dan menghapus atau mengganti nama fungsi onOpen().

Pemicu yang dapat diinstal dalam add-on

Untuk informasi selengkapnya tentang penggunaan pemicu yang dapat diinstal dalam add-on, lihat Pemicu add-on.