Otorisasi add-on editor

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

Pada umumnya, Anda harus mengizinkan add-on sebelum dapat menggunakannya. Untuk banyak project Apps Script seperti aplikasi web, otorisasi dapat dilakukan dengan mudah—project skrip meminta izin yang tidak ada yang diperlukan saat Anda mencoba menggunakannya. Setelah diberi otorisasi, Anda dapat menggunakan project skrip dengan bebas. Semua orang yang menggunakan project skrip akan memberinya otorisasi secara terpisah.

Model otorisasi untuk add-on editor lebih kompleks. Karena add-on ini berfungsi pada file yang berada di Google Drive—file yang dapat dibagikan dengan orang lain—Anda harus membuat add-on editor dengan mempertimbangkan berbagai mode otorisasi. Aplikasi editor Google Workspace juga menyediakan menu Add-on di UI-nya yang diisi oleh add-on yang telah Anda instal—meskipun Anda belum memberi otorisasi add-on tersebut. Hal ini menambahkan beberapa kerumitan tambahan ke model otorisasi.

Model otorisasi

Dua properti add-on editor akan sangat mudah 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 di 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 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) untuk menambahkan item menu saat dokumen terbuka, perilaku di atas menambahkan beberapa kerumitan pada aturan otorisasi Apps Script. Lagi pula, pengguna tidak akan keberatan dengan add-on mengakses data pribadi setiap kali mereka membuka dokumen. Panduan ini akan membantu Anda memahami fungsi kode dan waktunya.

Diinstal versus diaktifkan

Jika Anda melihat add-on editor di menu, berarti add-on ada di salah satu (atau keduanya) dari dua status: terinstal dan diaktifkan. Add-on editor diinstal untuk pengguna tertentu setelah mereka memilih add-on di toko dan mengizinkannya mengakses data Google mereka. Sebaliknya, add-on diaktifkan di dokumen tertentu saat siapa pun menggunakannya di sana. Jika dua orang berkolaborasi di dokumen, dan salah satunya menggunakan add-on, dokumen tersebut akan diinstal untuk satu pengguna dan diaktifkan untuk dokumen.

Tabel di bawah meringkas kedua status tersebut. Perlu diketahui bahwa saat menguji skrip sebagai add-on, Anda dapat memilih untuk menjalankan pengujian dalam salah satu atau kedua status ini.

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

Mode otorisasi

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

Secara khusus, status terinstal dan diaktifkan menentukan mode otorisasi untuk 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 dalam dokumen saat ini, onOpen(e) akan berjalan dalam AuthMode.LIMITED. Jika add-on tidak diaktifkan dan hanya diinstal, onOpen(e) akan berjalan dalam 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 otorisasinya sendiri, AuthMode.CUSTOM_FUNCTION, yang mirip dengan LIMITED tetapi memiliki batasan yang sedikit berbeda. Sisa waktu, skrip berjalan di AuthMode.FULL, seperti yang dijelaskan dalam tabel di bawah.

NONE LIMITED CUSTOM_FUNCTION FULL
Terjadi untuk onOpen(e) (jika pengguna telah menginstal add-on tetapi tidak mengaktifkannya di 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 akan 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, aplikasi akan berjalan.

Menginstal

Saat add-on editor diinstal dari penyimpanan, fungsi onInstall(e) 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 cukup memanggil onOpen(e) dari onInstall(e), seperti ditunjukkan dalam contoh ini:

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

Pembukaan

Saat dibuka, dokumen akan memuat setiap add-on editor yang telah diinstal pengguna saat ini atau yang telah diaktifkan oleh kolaborator dalam dokumen, dan akan memanggil setiap fungsi onOpen(e). Mode otorisasi yang dijalankan onOpen(e) bergantung pada apakah add-on diinstal atau diaktifkan.

Jika add-on hanya membuat menu dasar, mode tidak menjadi masalah. 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 Anda ingin menambahkan item menu dinamis berdasarkan properti Apps Script yang disimpan, membaca konten dokumen saat ini, atau melakukan tugas lanjutan lainnya, Anda perlu mendeteksi mode otorisasi dan menanganinya dengan benar. 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 mengetahui apakah pengguna telah menginstal add-on, dan meminta pengguna untuk melakukannya jika tidak. Jika pengguna telah mengizinkan add-on, skrip akan menjalankan fungsi yang sesuai dengan item menu di AuthMode.FULL. Add-on juga diaktifkan dalam dokumen jika sebelumnya belum.