Otorisasi untuk banyak aplikasi berbasis Apps Script bersifat mudah karena project skrip meminta izin yang tidak ada yang diperlukan saat seseorang mencoba menggunakannya.
Model otorisasi untuk Add-on Editor lebih kompleks karena beberapa alasan:
Saat pengguna membuat file, semua add-on yang diinstal pengguna akan tercantum di menu Ekstensi, meskipun pengguna belum mengizinkan add-on tersebut.
Add-on ini mengerjakan file di Google Drive yang dapat dibagikan kepada kolaborator. Kolaborator yang belum menginstal Add-on Editor akan melihatnya di dokumen tempat pembuat file menggunakannya.
Add-on Editor secara otomatis menjalankan fungsi
onOpen()
saat dokumen terbuka.
Untuk melindungi data pengguna, mode otorisasi diterapkan yang membuat beberapa layanan
tidak tersedia untuk onOpen()
. Panduan ini dapat membantu Anda memahami apa yang
dapat dilakukan kode Anda dan kapan.
Model otorisasi
Mode otorisasi Add-on Editor bergantung pada statusnya, yang bergantung pada siapa yang menggunakannya: pengguna yang menginstal add-on atau kolaborator.
Status Add-on Editor
Add-on Editor di menu Extensions diinstal, diaktifkan, atau keduanya.
- Add-on diinstal untuk pengguna tertentu setelah mereka atau administrator mendapatkannya dari Google Workspace Marketplace dan memberinya otorisasi untuk mengakses data Google mereka.
- Add-on diaktifkan di dokumen, formulir, presentasi, atau spreadsheet jika semua orang menggunakannya di sana.
- Saat orang berkolaborasi pada sebuah file dan salah satunya menggunakan add-on, file tersebut akan diinstal untuk satu pengguna, dan diaktifkan untuk file tersebut.
Tabel berikut merangkum perbedaan antara diinstal dan diaktifkan. Perlu diperhatikan bahwa saat menguji skrip sebagai add-on, Anda dapat menjalankan pengujian dalam salah satu atau kedua status ini.
Diinstal | Diaktifkan | |
---|---|---|
Berlaku untuk | Pengguna | Dokumen, formulir, presentasi, atau spreadsheet |
Disebabkan oleh | Mendapatkan add-on dari toko | Mendapatkan add-on dari toko saat menggunakan
dokumen, formulir, presentasi, atau spreadsheet tersebut, atau Menggunakan add-on yang telah diinstal sebelumnya dalam dokumen, formulir, presentasi, atau spreadsheet tersebut |
Menu terlihat oleh | Hanya pengguna tersebut, di semua dokumen, formulir, presentasi, atau spreadsheet yang mereka buka atau buat | Semua kolaborator pada dokumen, formulir, presentasi, atau spreadsheet tersebut |
Mode otorisasi untuk onOpen() |
AuthMode.NONE (kecuali jika perangkat juga diaktifkan, dalam hal ini AuthMode.LIMITED) |
AuthMode.LIMITED |
Mode otorisasi
Fungsi onOpen()
Add-on Editor akan otomatis berjalan
saat pengguna membuka dokumen, formulir, presentasi, atau spreadsheet.
Untuk melindungi data pengguna, Apps Script membatasi apa yang dapat dilakukan
fungsi onOpen()
. Status Add-on Editor
menentukan mode otorisasi tempat fungsi onOpen()
dijalankan.
Jika Add-on Editor diaktifkan dalam file,
formulir, presentasi, atau spreadsheet, onOpen()
akan berjalan di
AuthMode.LIMITED
. Jika add-on tidak diaktifkan dan
hanya diinstal, onOpen()
akan berjalan di AuthMode.NONE
.
Di AuthMode.NONE
, add-on tidak dapat menjalankan layanan
tertentu hingga pengguna berinteraksi dengan add-on dengan
mengklik atau menjalankan fungsi kustom. Jika add-on Anda mencoba menggunakan layanan ini dalam onOpen()
, onInstall()
, atau cakupan global, izin akan gagal dan panggilan lainnya, seperti mengisi menu, berhenti. Bantuan adalah satu-satunya opsi yang didukung.
Untuk menjalankan panggilan layanan yang dibatasi, Anda harus menggunakan mode
otorisasi AuthMode.FULL
. Fungsi interaksi pengguna, seperti mengklik opsi menu,
hanya berjalan dalam mode ini. Setelah kode dijalankan dalam mode AuthMode.FULL
, add-on
dapat menggunakan semua cakupan yang diizinkan oleh pengguna.
Apps Script meneruskan mode otorisasi sebagai properti authMode
dari parameter peristiwa Apps Script, e
; nilai e.authMode
sesuai dengan konstanta di enum ScriptApp.AuthMode
Apps Script.
Mode otorisasi berlaku untuk semua metode eksekusi Apps Script,
termasuk menjalankan dari editor skrip, dari item menu, atau dari panggilan
google.script.run
Apps Script. Namun,
properti e.authMode
hanya dapat diperiksa jika skrip berjalan karena
pemicu seperti onOpen()
, onEdit()
,
atau onInstall()
. Fungsi kustom di Google Spreadsheet menggunakan mode otorisasinya sendiri, AuthMode.CUSTOM_FUNCTION
, yang mirip dengan LIMITED
tetapi memiliki batasan yang sedikit berbeda. Untuk kasus
lainnya, skrip dijalankan di AuthMode.FULL
, seperti yang dijelaskan dalam tabel
berikut.
NONE |
LIMITED |
CUSTOM_FUNCTION |
FULL |
|
---|---|---|---|---|
Terjadi untuk | onOpen() (jika pengguna telah menginstal add-on tetapi belum mengaktifkannya di dokumen, formulir, presentasi, atau spreadsheet) |
onOpen() (di lain waktu)onEdit() (hanya di Spreadsheet) |
Fungsi kustom | Semua waktu lainnya, termasuk: pemicu yang dapat diinstal onInstall() google.script.run |
Akses ke data pengguna | Hanya lokal | Hanya lokal | Hanya lokal | Ya |
Akses ke dokumen, formulir, presentasi, atau spreadsheet | 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 |
Semua layanan yang tidak mengakses data pengguna | Semua layanan yang tidak mengakses data pengguna | Semua layanan |
Siklus proses otorisasi Add-on Editor
Jika add-on diinstal untuk pengguna saat ini
atau diaktifkan dalam file saat ini, add-on
akan dimuat untuk dokumen, formulir, presentasi,
atau spreadsheet saat file tersebut dibuka. Add-on
tercantum di menu Ekstensi dan mulai memproses
pemicu sederhana onInstall()
,
onOpen()
, dan onEdit()
. Jika pengguna mengklik
item menu Ekstensi, item tersebut akan dijalankan.
Add-on Editor terinstal
Saat Add-on Editor diinstal dari app store, fungsi
onInstall()
-nya akan berjalan di AuthMode.FULL
. Dalam mode otorisasi ini, add-on dapat menjalankan rutinitas penyiapan yang kompleks. Anda juga harus
menggunakan onInstall()
untuk membuat item menu, karena dokumen, formulir, presentasi,
atau spreadsheet sudah terbuka dan fungsi onOpen()
Anda belum berjalan.
Contoh berikut menunjukkan cara memanggil fungsi onOpen()
dari fungsi onInstall()
:
function onInstall(e) {
onOpen(e);
// Perform additional setup as needed.
}
Add-on Editor terbuka
Saat dokumen, formulir, presentasi, atau spreadsheet terbuka, setiap
Add-on Editor yang telah diinstal pengguna saat ini atau
yang telah diaktifkan oleh kolaborator dalam file tersebut akan dimuat, dan memanggil
setiap fungsi onOpen()
mereka. Mode otorisasi yang dijalankan onOpen()
bergantung pada apakah add-on
diinstal atau diaktifkan.
Jika add-on hanya membuat menu dasar, mode
tidak menjadi masalah. Contoh berikut menunjukkan fungsi onOpen()
dasar:
function onOpen(e) {
SpreadsheetApp.getUi().createAddonMenu() // Or DocumentApp.
.addItem('Insert chart', 'insertChart')
.addItem('Update charts', 'updateCharts')
.addToUi();
}
Untuk menambahkan item menu dinamis berdasarkan properti Apps Script yang tersimpan, membaca konten file saat ini, atau melakukan tugas lanjutan lainnya, Anda harus mengidentifikasi mode otorisasi dan menanganinya dengan tepat.
Contoh berikut menunjukkan fungsi onOpen()
lanjutan yang mengubah tindakannya 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();
}
Perhatikan bahwa add-on tidak dapat membuka sidebar atau dialog saat mengeksekusi di
AuthMode.LIMITED
. Anda dapat menggunakan item menu
untuk membuka sidebar dan dialog karena opsi ini berjalan di AuthMode.FULL
.
Pengguna menjalankan Add-on Editor
Saat pengguna mengklik item menu Ekstensi, Apps Script akan memeriksa terlebih dahulu apakah pengguna telah menginstal add-on, dan meminta mereka untuk melakukannya jika belum. Jika pengguna telah mengizinkan
add-on, skrip akan menjalankan fungsi yang
terkait dengan item menu di AuthMode.FULL
. Add-on ini diaktifkan dalam dokumen, formulir, presentasi, atau spreadsheet jika belum aktif.
Memecahkan masalah menu add-on yang tidak dirender
Menu add-on mungkin tidak dirender jika kode tidak mengelola mode otorisasi dengan benar. Contoh:
Add-on akan mencoba menjalankan layanan Apps Script yang tidak didukung oleh mode otorisasi saat ini.
Add-on akan mencoba menjalankan panggilan layanan sebelum pengguna berinteraksi dengannya.
Untuk menghapus atau mengatur ulang panggilan layanan yang menyebabkan error izin di
AuthMode.NONE
, coba tindakan berikut:
- Buka project Apps Script untuk add-on Anda dan cari
fungsi
onOpen()
. - Telusuri fungsi
onOpen()
untuk menemukan penyebutan layanan atau objek Apps Script yang terkait dengannya, sepertiPropertiesService
,SpreadsheetApp
, atauGmailApp
. - Jika layanan digunakan untuk hal selain membuat elemen UI,
hapus atau gabungkan ke dalam blok komentar.
Hanya biarkan metode ini:
.getUi()
,.createMenu()
,.addItem()
, dan.addToUi()
. Juga temukan dan hapus layanan apa pun yang berada di luar fungsi. - Identifikasi fungsi yang dapat berisi baris kode yang dikomentari atau dihapus di langkah sebelumnya, terutama yang menggunakan informasi yang dihasilkannya, dan pindahkan panggilan layanan ke fungsi yang membutuhkannya. Susun ulang atau tulis ulang codebase Anda untuk mengakomodasi perubahan yang dibuat pada langkah sebelumnya.
Simpan kode dan buat deployment pengujian.
Saat Anda membuat deployment pengujian, pastikan kolom Config adalah Diinstal untuk pengguna saat ini dan teks di bawah kotak Konfigurasi bertuliskan Test in
AuthMode.None
Luncurkan deployment pengujian dan buka menu Extensions.
Jika semua item menu ditampilkan, masalah telah diperbaiki. Jika Anda hanya melihat menu Bantuan, kembali ke langkah 1. Anda mungkin melewatkan panggilan layanan.