Otorisasi Add-on Editor

Dalam sebagian besar kasus, Anda harus mengizinkan add-on sebelum Anda dapat menggunakannya. Untuk banyak project Apps Script seperti aplikasi web, otorisasi bersifat mudah—project skrip meminta izin yang tidak ada yang diperlukan saat Anda mencoba menggunakannya. Setelah diberi otorisasi, Anda dapat menggunakan project skrip secara bebas. Semua orang yang menggunakan project skrip mengizinkannya secara terpisah.

Model otorisasi untuk Add-on Editor lebih kompleks. Karena add-on ini berfungsi pada file yang ada di Google Drive—file yang dapat dibagikan kepada orang lain—Anda harus mem-build add-on editor dengan mempertimbangkan mode otorisasi yang berbeda. Aplikasi editor Google Workspace juga menyediakan menu Add-on di UI-nya yang diisi oleh add-on yang telah Anda instal—meskipun Anda belum mengizinkan add-on tersebut. Hal ini menambahkan kompleksitas tambahan pada model otorisasi.

Model otorisasi

Dua properti Add-on Editor akan membuatnya mudah untuk dibagikan dan digunakan:

  • Setelah mendapatkan Add-on Editor dari toko, Anda akan melihatnya di menu add-on untuk setiap dokumen yang dibuka atau dibuat. Kolaborator pada dokumen tersebut tidak akan melihat add-on kecuali dalam dokumen tempat Anda benar-benar menggunakannya.
  • Setelah Anda menggunakan Add-on Editor dalam dokumen, kolaborator juga akan melihatnya di menu add-on, tetapi hanya untuk dokumen tersebut (kecuali jika mereka juga menginstal add-on tersebut).

Model berbagi ini terasa alami bagi sebagian besar pengguna. Namun, karena add-on editor otomatis menjalankan fungsi onOpen(e)-nya untuk menambahkan item menu saat dokumen terbuka, perilaku di atas menambahkan beberapa kerumitan pada aturan otorisasi Apps Script. Lagi pula, pengguna tidak akan merasa nyaman dengan add-on yang mengakses data pribadi setiap kali mereka membuka dokumen. Panduan ini akan membantu Anda memahami fungsi kode Anda dan waktunya.

Diinstal versus diaktifkan

Jika Anda melihat Add-on Editor di menu, berarti salah satu dari keduanya (atau keduanya) telah diinstal dan diinstal. Add-on Editor diinstal untuk pengguna tertentu setelah mereka memilih add-on di toko dan memberinya otorisasi untuk mengakses data Google mereka. Sebaliknya, add-on diaktifkan di dokumen tertentu saat ada yang menggunakannya. Jika dua orang berkolaborasi pada dokumen, dan salah satunya menggunakan add-on, dokumen tersebut akan diinstal untuk satu pengguna dan diaktifkan untuk dokumen.

Tabel di bawah merangkum dua status. Perhatikan bahwa saat menguji skrip sebagai add-on, Anda dapat memilih untuk menjalankan pengujian pada salah satu atau kedua status ini.

Diinstal Diaktifkan
Berlaku untuk Pengguna Dokumen
Disebabkan oleh Mendapatkan add-on dari toko Mendapatkan add-on dari toko saat menggunakan dokumen tersebut, atau
Menggunakan add-on yang diinstal sebelumnya dalam dokumen tersebut
Menu dapat dilihat oleh Hanya pengguna tersebut, di semua dokumen yang mereka buka atau buat Semua kolaborator di dokumen tersebut
onOpen(e) angka dengan AuthMode.NONE (kecuali jika diaktifkan juga, dalam hal ini AuthMode.LIMITED)) AuthMode.LIMITED

Mode otorisasi

Add-on Editor otomatis menjalankan fungsi onOpen(e)-nya untuk menambahkan item menu saat dokumen dibuka—tetapi untuk melindungi data pengguna, Apps Script membatasi fungsi onOpen(e). Jika add-on belum digunakan dalam dokumen saat ini, pembatasan ini akan menjadi lebih berat.

Secara khusus, status terinstal dan diaktifkan menentukan mode otorisasi mana yang menjalankan fungsi onOpen(e). Apps Script meneruskan mode otorisasi sebagai properti authMode dari parameter peristiwa Apps Script, e; nilai e.authMode sesuai dengan konstanta dalam enum ScriptApp.AuthMode Apps Script.

Jika Add-on Editor diaktifkan di dokumen saat ini, onOpen(e) akan berjalan di AuthMode.LIMITED. Jika add-on tidak diaktifkan dan hanya diinstal, onOpen(e) akan berjalan di AuthMode.NONE.

Konsep mode otorisasi berlaku untuk semua eksekusi Apps Script—seperti berjalan dari editor skrip, dari item menu, atau dari panggilan google.script.run Apps Script—meskipun properti e.authMode hanya dapat diperiksa jika skrip berjalan sebagai hasil dari pemicu seperti onOpen(e), onEdit(e) atau onInstall(e). Fungsi kustom di Google Spreadsheet menggunakan mode otorisasi sendiri, AuthMode.CUSTOM_FUNCTION, yang mirip dengan LIMITED tetapi memiliki batasan yang sedikit berbeda. Sisa waktu, skrip berjalan di AuthMode.FULL, seperti yang dijelaskan pada tabel di bawah.

NONE LIMITED CUSTOM_FUNCTION FULL
Terjadi untuk onOpen(e) (jika pengguna telah menginstal add-on, tetapi tidak mengaktifkannya dalam dokumen) onOpen(e) (semua waktu lainnya)
onEdit(e) (hanya di Spreadsheet)
Fungsi kustom Semua waktu lainnya, termasuk:
pemicu yang dapat diinstal
onInstall(e)
google.script.run
Akses ke data pengguna Hanya lokal Hanya lokal Hanya lokal Ya
Akses ke dokumen Tidak Ya Ya — hanya-baca Ya
Akses ke antarmuka pengguna Menambahkan item menu Menambahkan item menu Tidak Ya
Akses ke Properties Tidak Ya Ya Ya
Akses ke Jdbc, UrlFetch Tidak Tidak Ya Ya
Layanan lainnya Logger
Utilities
Layanan apa pun yang tidak mengakses data pengguna Layanan apa pun yang tidak mengakses data pengguna Semua layanan

Siklus proses lengkap

Jika add-on diinstal untuk pengguna saat ini atau diaktifkan dalam dokumen saat ini, add-on dimuat dalam dokumen, yang menyebabkannya muncul di menu add-on dan mulai memproses pemicu sederhana onInstall(e), onOpen(e), dan onEdit(e). Jika pengguna mengklik salah satu item menu add-on, itu akan berjalan.

Menginstal

Saat Add-on Editor diinstal dari toko, fungsi onInstall(e)-nya akan berjalan di AuthMode.FULL. Hal ini memungkinkan add-on menjalankan rutinitas penyiapan yang kompleks, tetapi penting juga untuk menggunakan onInstall(e) untuk membuat item menu, karena dokumen sudah terbuka sehingga fungsi onOpen(e) Anda belum berjalan. Untuk kemudahan, Anda dapat memanggil onOpen(e) dari onInstall(e), seperti yang ditunjukkan dalam contoh ini:

function onInstall(e) {
  onOpen(e);
  // Perform additional setup as needed.
}

Pembukaan

Saat dokumen terbuka, dokumen tersebut akan memuat setiap Add-on Editor yang telah diinstal pengguna saat ini atau yang telah diaktifkan oleh kolaborator dalam dokumen, lalu memanggil setiap fungsi onOpen(e)-nya. Mode otorisasi yang dijalankan oleh onOpen(e) bergantung pada apakah add-on diinstal atau diaktifkan.

Jika add-on hanya membuat menu dasar, mode tersebut tidak berpengaruh. Contoh ini menunjukkan tampilan onOpen(e) yang sederhana:

function onOpen(e) {
  SpreadsheetApp.getUi().createAddonMenu() // Or DocumentApp.
      .addItem('Insert chart', 'insertChart')
      .addItem('Update charts', 'updateCharts')
      .addToUi();
}

Namun, jika ingin menambahkan item menu dinamis berdasarkan properti Apps Script yang disimpan, membaca konten dokumen saat ini, atau melakukan tugas lanjutan lainnya, Anda harus mendeteksi mode otorisasi dan menanganinya dengan tepat. Contoh ini menunjukkan tampilan fungsi onOpen(e) lanjutan, yang mengubah perilakunya berdasarkan mode otorisasi:

function onOpen(e) {
  var menu = SpreadsheetApp.getUi().createAddonMenu(); // Or DocumentApp.
  if (e && e.authMode == ScriptApp.AuthMode.NONE) {
    // Add a normal menu item (works in all authorization modes).
    menu.addItem('Start workflow', 'startWorkflow');
  } else {
    // Add a menu item based on properties (doesn't work in AuthMode.NONE).
    var properties = PropertiesService.getDocumentProperties();
    var workflowStarted = properties.getProperty('workflowStarted');
    if (workflowStarted) {
      menu.addItem('Check workflow status', 'checkWorkflow');
    } else {
      menu.addItem('Start workflow', 'startWorkflow');
    }
  }
  menu.addToUi();
}

Lari

Saat seseorang mengklik salah satu item menu add-on, Apps Script akan memeriksa terlebih dahulu untuk melihat apakah pengguna telah menginstal add-on, dan meminta pengguna melakukannya. Jika pengguna telah mengizinkan add-on, skrip akan menjalankan fungsi yang sesuai dengan item menu di AuthMode.FULL. Add-on juga akan diaktifkan dalam dokumen jika Anda belum mengaktifkannya.