Pemicu yang Dapat Diinstal

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

Pembatasan

Meskipun pemicu yang dapat diinstal menawarkan lebih banyak fleksibilitas daripada pemicu sederhana, pengguna tetap harus mematuhi beberapa batasan:

  • Perintah ini tidak berjalan jika file dibuka dalam mode hanya baca (lihat atau komentar). Sebagai skrip mandiri, pengguna membutuhkan setidaknya akses melihat ke file {i>script <i}di agar {i>trigger<i} dapat berjalan dengan baik.

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

  • Pemicu yang dapat diinstal selalu berjalan di bawah akun pengguna yang membuat mereka. Misalnya, jika Anda membuat pemicu terbuka yang dapat diinstal, pemicu tersebut akan saat rekan kerja membuka dokumen (jika rekan kerja memiliki akses edit), tapi akun ini beroperasi sebagai akun Anda. Artinya, jika Anda membuat pemicu untuk mengirim email ketika dokumen dibuka, email akan selalu dikirim dari akun Anda, bukan akun yang membuka dokumen. Namun, Anda dapat membuat pemicu yang dapat diinstal untuk setiap akun, yang akan menghasilkan dalam satu email yang dikirim dari setiap akun.

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

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

Pemicu berbasis waktu

Pemicu berbasis waktu (disebut juga pemicu jam) mirip dengan cron job di Unix. Pemicu berbasis waktu memungkinkan skrip dijalankan pada waktu tertentu atau pada interval yang berulang, sesering yang sering setiap menit atau jarang sekali sebulan. (Perhatikan bahwa add-on dapat menggunakan pemicu berbasis waktu maksimal sekali per jam.) Waktunya mungkin sedikit diacak—misalnya, jika Anda membuat pemicu yang berulang pada pukul 09.00, Apps Script memilih waktu antara pukul 09.00 dan 10.00, lalu waktu tersebut konsisten dari hari ke hari sehingga 24 jam berlalu sebelum pemicu diaktifkan kembali.

Berikut ini adalah contoh Aplikasi Google Chat yang memposting pesan setiap menit ke setiap ruang tempat aplikasi berada:

// Example app for Google Chat that demonstrates app-initiated messages
// by spamming the user every minute.
//
// This app makes use of the Apps Script OAuth2 library at:
//     https://github.com/googlesamples/apps-script-oauth2
//
// Follow the instructions there to add the library to your script.

// When added to a space, we store the space's ID in ScriptProperties.
function onAddToSpace(e) {
  PropertiesService.getScriptProperties()
      .setProperty(e.space.name, '');
  return {
    'text': 'Hi! I\'ll post a message here every minute. ' +
            'Please remove me after testing or I\'ll keep spamming you!'
  };
}

// When removed from a space, we remove the space's ID from ScriptProperties.
function onRemoveFromSpace(e) {
  PropertiesService.getScriptProperties()
      .deleteProperty(e.space.name);
}

// Add a trigger that invokes this function every minute in the
// "Edit > Current Project's Triggers" menu. When it runs, it
// posts in each space the app was added to.
function onTrigger() {
  var spaceIds = PropertiesService.getScriptProperties()
      .getKeys();
  var message = { 'text': 'Hi! It\'s now ' + (new Date()) };
  for (var i = 0; i < spaceIds.length; ++i) {
    postMessage(spaceIds[i], message);
  }
}
var SCOPE = 'https://www.googleapis.com/auth/chat.bot';
// The values below are copied from the JSON file downloaded upon
// service account creation.
// For SERVICE_ACCOUNT_PRIVATE_KEY, remember to include the BEGIN and END lines
// of the private key
var SERVICE_ACCOUNT_PRIVATE_KEY = '...';
var SERVICE_ACCOUNT_EMAIL = 'service-account@project-id.iam.gserviceaccount.com';

// Posts a message into the given space ID via the API, using
// service account authentication.
function postMessage(spaceId, message) {
  var service = OAuth2.createService('chat')
      .setTokenUrl('https://accounts.google.com/o/oauth2/token')
      .setPrivateKey(SERVICE_ACCOUNT_PRIVATE_KEY)
      .setClientId(SERVICE_ACCOUNT_EMAIL)
      .setPropertyStore(PropertiesService.getUserProperties())
      .setScope(SCOPE);
  if (!service.hasAccess()) {
    Logger.log('Authentication error: %s', service.getLastError());
    return;
  }
  var url = 'https://chat.googleapis.com/v1/' + spaceId + '/messages';
  UrlFetchApp.fetch(url, {
    method: 'post',
    headers: { 'Authorization': 'Bearer ' + service.getAccessToken() },
    contentType: 'application/json',
    payload: JSON.stringify(message),
  });
}

Pemicu berbasis peristiwa

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

Misalnya, pemicu terbuka yang dapat diinstal untuk Google Spreadsheet diaktifkan setiap kali {i>spreadsheet<i} dibuka oleh pengguna yang memiliki akses edit, seperti pemicu onOpen() sederhana. Namun, versi yang dapat diinstal dapat memanggil layanan yang memerlukan otorisasi. Aplikasi versi berjalan dengan otorisasi dari pengguna yang membuat pemicu, bahkan jika pengguna lain yang memiliki akses edit membuka {i>spreadsheet<i}.

Ada beberapa pemicu yang dapat diinstal untuk Google Workspace aplikasi:

  • Pemicu open yang dapat diinstal berjalan saat pengguna membuka spreadsheet, dokumen, atau formulir yang dapat mereka edit.
  • Pemicu edit yang dapat diinstal berjalan saat pengguna mengubah nilai di {i>spreadsheet<i}.
  • Pemicu perubahan yang dapat diinstal berjalan saat pengguna mengubah struktur {i>spreadsheet<i} itu sendiri—misalnya, dengan menambahkan {i>sheet<i} baru atau menghapus .
  • 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 dikirim 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 bisa secara terprogram membuat pemicu yang dapat diinstal untuk sebuah file Google Spreadsheet arbitrer dengan memanggil TriggerBuilder.forSpreadsheet(key) dan meneruskan ID spreadsheet.

Mengelola pemicu secara manual

Untuk membuat pemicu yang dapat diinstal di editor skrip secara manual, 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 konfigurasikan jenis pemicu yang ingin Anda buat.
  5. 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 mengembalikan TriggerBuilder.

Contoh berikut menunjukkan cara membuat dua pemicu berbasis waktu—satu pemicu yang menyala setiap 6 jam, dan satu kebakaran yang dipicu setiap hari Senin pukul 09.00 (dalam zona waktu yang ditetapkan ke 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 {i>spreadsheet<i}. Perhatikan bahwa, tidak seperti pemicu onOpen() sederhana, skrip untuk pemicu yang dapat diinstal tidak perlu terikat pada {i>spreadsheet<i}. Untuk membuat pemicu ini dari skrip mandiri, cukup 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 secara terprogram, Anda harus menghapusnya dan membuat yang baru. Jika sebelumnya Anda telah menyimpan ID pemicu, Anda dapat menghapusnya dengan meneruskan ID sebagai argumen ke fungsi di bawah ini.

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;
    }
  }
}

Error dalam pemicu

Saat pemicu yang dapat diinstal diaktifkan, tetapi fungsi menampilkan pengecualian atau jika tidak, gagal dijalankan, Anda tidak akan melihat pesan {i>error<i} pada layar. Lagi pula, ketika pemicu berbasis waktu berjalan atau pengguna lain teraktivasi pemicu pengiriman formulir, Anda bahkan mungkin tidak berada di depan komputer.

Sebagai gantinya, Apps Script mengirimkan email seperti berikut:

From: noreply-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 menyertakan link untuk menonaktifkan atau mengonfigurasi ulang pemicu. Jika skrip adalah terikat ke Google Spreadsheet, Dokumen, atau Formulir {i>file<i} tersebut, email juga akan menyertakan tautan ke {i>file<i} tersebut. Link ini memungkinkan Anda menonaktifkan pemicu atau mengedit skrip untuk memperbaiki {i>bug<i}.

Untuk meninjau semua pemicu yang terkait dengan Akun Google Anda dan menonaktifkan pemicu yang tidak lagi Anda butuhkan, 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.

Pemicu di add-on

Selain pemicu yang dapat diinstal, Anda bisa menggunakan pemicu manifes di {i>add-on<i}. Untuk informasi selengkapnya, lihat Pemicu untuk Add-on Google Workspace.