Pemicu untuk Add-on Editor

Pemicu Apps Script menyebabkan skrip tertentu fungsi (fungsi pemicu) untuk dieksekusi setiap kali peristiwa yang ditentukan apa yang terjadi. Hanya peristiwa tertentu yang dapat menyebabkan pemicu diaktifkan, dan setiap peristiwa Aplikasi Google Workspace mendukung berbagai peristiwa.

Saat pemicu diaktifkan, objek peristiwa akan dibuat. Struktur JSON ini berisi detail tentang peristiwa yang terjadi. Informasi dalam peristiwa struktur objek disusun 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 terapkan sendiri, untuk mengambil tindakan apa pun yang sesuai untuk menanggapi peristiwa. Misalnya, di sebuah Add-on Editor, pemicu digunakan untuk membuat item menu {i> add-on<i} ketika dokumen dibuka. Dalam hal ini, Anda terapkan pada fungsi pemicu onOpen(e) untuk membuat item menu yang ditambahkan add-on kebutuhan Anda, mungkin dengan menggunakan data dalam objek peristiwa.

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

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

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

Acara	Objek peristiwa	Pemicu sederhana	Pemicu yang dapat diinstal
Buka File editor akan terbuka.	Objek peristiwa Docs onOpen 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 akan 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
Perubahan Konten dalam sheet diedit atau diformat.	Objek peristiwa onChange Spreadsheet		Spreadsheet
Pengiriman formulir Formulir Google dikirim.	Objek peristiwa pengiriman formulir Formulir Objek peristiwa pengiriman formulir Spreadsheet		Formulir Spreadsheet
Berbasis 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, namun saat editor membuka formulir untuk mengubahnya.

Pemicu sederhana di add-on

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

Pembatasan

Pemicu sederhana di add-on tunduk pada batasan yang mengatur di jenis project Apps Script lainnya. Perhatikan hal-hal berikut batasan saat mendesain add-on:

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

Pemicu yang dapat diinstal di add-on

Add-on dapat membuat dan mengubah pemicu yang dapat diinstal secara terprogram dengan layanan Apps Script Script. atau Gemini Enterprise Pemicu yang dapat diinstal tidak dapat dibuat secara manual. Tidak seperti {i>trigger<i} sederhana, {i>trigger<i} {i>Installable trigger<i} dapat menggunakan layanan yang memerlukan otorisasi.

Pemicu yang dapat diinstal di add-on tidak mengirim email error kepada pengguna ketika mereka menemukan {i>error<i}, karena dalam kebanyakan kasus, pengguna tidak dapat untuk mengatasi masalah tersebut. Karena itu, Anda harus merancang {i>add-on<i} untuk menangani {i>error<i} dengan baik atas nama pengguna bila memungkinkan.

Add-on dapat menggunakan pemicu yang dapat diinstal berikut:

• Pemicu Open yang dapat diinstal dijalankan saat pengguna membuka dokumen, spreadsheet, atau saat formulir dibuka di editor (tetapi tidak saat merespons pada formulir).
• Pemicu Edit yang dapat diinstal dijalankan saat pengguna mengubah nilai sel dalam pada {i>spreadsheet<i}. Pemicu ini tidak diaktifkan sebagai respons terhadap pemformatan atau perubahan yang tidak mengubah nilai sel.
• Pemicu perubahan yang dapat diinstal dijalankan saat pengguna membuat perubahan apa pun dalam {i>spreadsheet<i}, termasuk pemformatan dan modifikasi pada {i>spreadsheet<i} itu sendiri (seperti menambahkan baris).

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

• Pemicu berbasis waktu (disebut juga pemicu jam) yang dipicu pada waktu tertentu atau berulang kali pada dengan interval waktu yang teratur.

Mengizinkan pemicu yang dapat diinstal

Biasanya, jika pengembang memperbarui {i>add-on<i} untuk menggunakan layanan baru yang memerlukan otorisasi tambahan, pengguna akan diminta untuk memberikan otorisasi ulang ke add-on berapa kali mereka menggunakannya.

Namun, add-on yang menggunakan pemicu menemui tantangan otorisasi khusus. Bayangkan add-on yang menggunakan pemicu untuk memantau pengiriman formulir: sebuah formulir kreator dapat mengizinkan add-on ini saat pertama kali menggunakannya, lalu menyerahkannya kepada 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 di project Apps Script reguler, pemicu di add-on terus aktif meskipun perlu otorisasi ulang. Namun, skrip tetap gagal jika menemukan baris kode yang membutuhkan otorisasi skrip tidak dimiliki oleh Google. Untuk menghindari situasi ini, developer dapat menggunakan metode ini ScriptApp.getAuthorizationInfo() untuk membuka akses ke bagian kode yang telah berubah di antara versi yang dipublikasikan add-on ini.

Di bawah ini adalah contoh struktur yang direkomendasikan untuk digunakan dalam fungsi pemicu untuk menghindari kesalahan 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 pembatasan yang mengatur pemicu yang dapat diinstal di jenis project Apps Script lainnya.

Selain pembatasan ini, beberapa pembatasan berlaku untuk di add-on, khususnya:

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