Pemicu untuk add-on Editor

Pemicu Apps Script menyebabkan fungsi skrip yang ditentukan (fungsi pemicu) dijalankan setiap kali peristiwa yang ditentukan terjadi. Hanya peristiwa tertentu yang dapat menyebabkan pemicu diaktifkan, dan setiap aplikasi Google Workspace mendukung kumpulan peristiwa yang berbeda.

Saat pemicu diaktifkan, objek peristiwa akan dibuat. Struktur JSON ini berisi detail tentang peristiwa yang terjadi. Informasi dalam struktur objek peristiwa diatur 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 implementasikan sendiri, untuk mengambil tindakan apa pun yang sesuai untuk merespons peristiwa. Misalnya, di add-on Editor, pemicu digunakan untuk membuat item menu add-on saat dokumen dibuka. Dalam hal ini, Anda menerapkan fungsi pemicu onOpen(e) untuk membuat item menu yang diperlukan add-on, mungkin menggunakan data dalam objek peristiwa.

Halaman ini memberikan panduan tentang penggunaan pemicu dalam project add-on editor.

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. Kumpulan jenis pemicu yang tersedia bergantung pada aplikasi yang diperluas.

Tabel berikut menunjukkan jenis pemicu sederhana dan yang dapat diinstal yang dapat digunakan oleh add-on Editor, dan memberikan link ke objek peristiwa yang sesuai:

Acara	Objek peristiwa	Pemicu sederhana	Pemicu yang dapat diinstal
Buka File editor akan terbuka.	Objek peristiwa onOpen Dokumen Objek peristiwa onOpen Formulir Objek peristiwa onOpen Spreadsheet Objek peristiwa onOpen Slide	Dokumen Formulir* Spreadsheet Slide function onOpen(e)	Dokumen Formulir Spreadsheet
Instal Add-on diinstal.	objek peristiwa onInstall	Dokumen Formulir Spreadsheet Slide function onInstall(e)
Edit Konten sel spreadsheet diubah.	Objek peristiwa onEdit Spreadsheet	Spreadsheet function onEdit(e)	Spreadsheet
Change Konten dalam sheet diedit atau diformat.	Objek peristiwa onChange Spreadsheet		Spreadsheet
Form-submit Google Formulir dikirim.	objek peristiwa pengiriman formulir Formulir objek peristiwa pengiriman formulir Spreadsheet		Formulir Spreadsheet
Ditujukan waktu (jam) Pemicu diaktifkan pada waktu atau interval yang ditentukan.	Objek peristiwa berbasis waktu		Dokumen Formulir Spreadsheet Slide

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

Pemicu sederhana di add-on

Pemicu sederhana menggunakan kumpulan nama fungsi yang direservasi, tidak dapat menggunakan layanan yang memerlukan otorisasi, dan otomatis diaktifkan untuk digunakan. Dalam beberapa kasus, peristiwa pemicu sederhana dapat 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) dieksekusi saat pengguna membuka dokumen, spreadsheet, atau presentasi. onOpen(e) juga dapat dieksekusi saat formulir dibuka di editor (tetapi tidak saat merespons formulir). Fungsi ini hanya dieksekusi jika pengguna memiliki izin untuk mengedit file yang dimaksud, dan paling sering digunakan untuk membuat item menu.
• onInstall(e) dieksekusi saat pengguna menginstal add-on. Biasanya onInstall(e) hanya digunakan untuk memanggil onOpen(e); hal ini memastikan bahwa menu add-on muncul segera setelah penginstalan tanpa mengharuskan pengguna memuat ulang halaman.
• onEdit(e) dieksekusi saat pengguna mengubah nilai sel di spreadsheet. Pemicu ini tidak diaktifkan sebagai respons terhadap pemindahan sel, pemformatan, atau perubahan lainnya yang tidak mengubah nilai sel.

Pembatasan

Pemicu sederhana di add-on tunduk pada batasan yang sama dengan yang mengatur pemicu sederhana dalam jenis project Apps Script lainnya. Perhatikan dengan cermat batasan ini saat mendesain add-on:

• Pemicu sederhana tidak berjalan jika file dibuka dalam mode hanya baca (lihat atau komentar). Perilaku ini mencegah menu add-on Anda diisi.
• Dalam situasi tertentu, add-on Editor menjalankan pemicu sederhana onOpen(e) dan onEdit(e) dalam mode tanpa otorisasi. Mode ini menghadirkan beberapa komplikasi tambahan seperti yang diuraikan dalam model otorisasi add-on.
• Pemicu sederhana tidak dapat menggunakan layanan atau melakukan tindakan lain yang memerlukan otorisasi, kecuali seperti yang diuraikan dalam model otorisasi add-on.
• Pemicu sederhana tidak dapat berjalan lebih dari 30 detik. Perhatikan untuk meminimalkan jumlah pemrosesan yang dilakukan dalam fungsi pemicu sederhana.
• Pemicu sederhana tunduk pada batas kuota pemicu Apps Script.

Pemicu yang dapat diinstal di add-on

Add-on dapat membuat dan mengubah pemicu yang dapat diinstal secara terprogram dengan layanan Script Apps Script. pemicu yang dapat diinstal add-on tidak dapat dibuat secara manual. Tidak seperti pemicu sederhana, pemicu yang dapat diinstal dapat menggunakan layanan yang memerlukan otorisasi.

Pemicu yang dapat diinstal di add-on tidak mengirim email error kepada pengguna saat mereka mengalami error, karena dalam sebagian besar kasus, pengguna tidak dapat menangani masalah tersebut. Oleh karena itu, Anda harus mendesain add-on untuk menangani error dengan baik atas nama pengguna jika memungkinkan.

Add-on dapat menggunakan pemicu yang dapat diinstal berikut:

• Pemicu yang dapat diinstal Open dijalankan saat pengguna membuka dokumen, spreadsheet, atau saat formulir dibuka di editor (tetapi tidak saat merespons formulir).
• Edit pemicu yang dapat diinstal dijalankan saat pengguna mengubah nilai sel di spreadsheet. Pemicu ini tidak diaktifkan sebagai respons terhadap pemformatan atau perubahan lain yang tidak mengubah nilai sel.
• Pemicu yang dapat diinstal Change dijalankan saat pengguna melakukan perubahan apa pun dalam spreadsheet, termasuk pengeditan dan perubahan format pada spreadsheet itu sendiri (seperti menambahkan baris).

• Pemicu yang dapat diinstal Pengiriman formulir dijalankan saat respons Google Formulir dikirimkan.

• Pemicu berbasis waktu (juga disebut pemicu jam) diaktifkan pada waktu tertentu atau berulang kali pada interval waktu reguler.

Memberi otorisasi pemicu yang dapat diinstal

Biasanya, jika developer mengupdate add-on untuk menggunakan layanan baru yang memerlukan otorisasi tambahan, pengguna akan diminta untuk memberikan otorisasi ulang pada add-on tersebut saat menggunakannya lagi.

Namun, add-on yang menggunakan pemicu mengalami tantangan otorisasi khusus. Bayangkan add-on yang menggunakan pemicu untuk memantau pengiriman formulir: pembuat formulir mungkin mengizinkan add-on saat pertama kali menggunakannya, lalu membiarkannya 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 dalam project Apps Script reguler, pemicu dalam add-on terus diaktifkan meskipun memerlukan otorisasi ulang. Namun, skrip masih gagal jika mencapai baris kode yang memerlukan otorisasi yang tidak dimiliki skrip. Untuk menghindari situasi ini, developer dapat menggunakan metode ScriptApp.getAuthorizationInfo() untuk mengontrol akses ke bagian kode yang telah berubah di antara versi add-on yang dipublikasikan.

Berikut adalah contoh struktur yang direkomendasikan untuk digunakan dalam fungsi pemicu guna menghindari masalah 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.

/**
 * Responds to a form when submitted.
 * @param {event} e The Form submit event.
 */
function respondToFormSubmit(e) {
  const addonTitle = 'My Add-on Title';
  const props = PropertiesService.getDocumentProperties();
  const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL);

  // Check if the actions of the trigger requires authorization that has not
  // been granted yet; if so, warn the user via email. This check is required
  // when using triggers with add-ons to maintain functional triggers.
  if (authInfo.getAuthorizationStatus() ===
    ScriptApp.AuthorizationStatus.REQUIRED) {
    // Re-authorization is required. In this case, the user needs to be alerted
    // that they need to re-authorize; the normal trigger action is not
    // conducted, since it requires authorization first. Send at most one
    // "Authorization Required" email per day to avoid spamming users.
    const lastAuthEmailDate = props.getProperty('lastAuthEmailDate');
    const today = new Date().toDateString();
    if (lastAuthEmailDate !== today) {
      if (MailApp.getRemainingDailyQuota() > 0) {
        const html = HtmlService.createTemplateFromFile('AuthorizationEmail');
        html.url = authInfo.getAuthorizationUrl();
        html.addonTitle = addonTitle;
        const message = html.evaluate();
        MailApp.sendEmail(Session.getEffectiveUser().getEmail(),
            'Authorization Required',
            message.getContent(), {
              name: addonTitle,
              htmlBody: message.getContent()
            }
        );
      }
      props.setProperty('lastAuthEmailDate', today);
    }
  } else {
    // Authorization has been granted, so continue to respond to the trigger.
    // Main trigger logic here.
  }
}

<p>The Google Sheets add-on <i><?= addonTitle ?></i> is set to run automatically
    whenever a form is submitted. The add-on was recently updated and it needs you
    to re-authorize it to run on your behalf.</p>

<p>The add-on's automatic functions are temporarily disabled until you
    re-authorize it. To do so, open Google Sheets and run the add-on from the
    Add-ons menu. Alternatively, you can click this link to authorize it:</p>

<p><a href="<?= url ?>">Re-authorize the add-on.</a></p>

<p>This notification email will be sent to you at most once per day until the
    add-on is re-authorized.</p>

Pembatasan

Pemicu yang dapat diinstal di add-on tunduk pada batasan yang sama yang mengatur pemicu yang dapat diinstal di jenis project Apps Script lainnya.

Selain batasan ini, beberapa batasan berlaku untuk pemicu yang dapat diinstal di add-on secara khusus:

• Setiap add-on hanya dapat memiliki satu pemicu dari setiap jenis, per pengguna, per dokumen. Misalnya, dalam spreadsheet tertentu, pengguna tertentu hanya dapat memiliki satu pemicu pengeditan, meskipun pengguna juga dapat memiliki pemicu pengiriman formulir atau pemicu berbasis waktu di spreadsheet yang sama. Pengguna lain yang memiliki akses ke spreadsheet yang sama dapat memiliki kumpulan pemicu terpisah.
• Add-on hanya dapat membuat pemicu untuk file tempat add-on digunakan. Artinya, add-on yang digunakan di Dokumen Google A tidak dapat membuat pemicu untuk memantau saat Dokumen Google B dibuka.
• Pemicu berbasis waktu tidak dapat berjalan lebih dari sekali per jam.
• Add-on tidak otomatis mengirim email kepada pengguna saat kode yang dijalankan oleh pemicu yang dapat diinstal menampilkan pengecualian. Developer dapat 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 akan beroperasi kembali), atau
  • Jika developer membatalkan publikasi add-on atau mengirimkan versi yang rusak ke toko add-on.
• Fungsi pemicu add-on dijalankan hingga mencapai kode yang menggunakan layanan tidak sah, dan pada saat itu fungsi tersebut akan 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 dieksekusi sama sekali jika ada bagian skrip yang memerlukan otorisasi.
• Pemicu yang dapat diinstal tunduk pada batas kuota pemicu Apps Script.