Halaman ini diterjemahkan oleh Cloud Translation API.

Otorisasi add-on editor

Otorisasi untuk banyak aplikasi berbasis Apps Script sangat mudah karena project skrip meminta izin yang diperlukan yang belum diberikan 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 dicantumkan di menu Ekstensi, meskipun pengguna belum mengizinkan add-on tersebut.
Add-on ini berfungsi pada file di Google Drive yang dapat dibagikan kepada kolaborator. Kolaborator yang tidak menginstal add-on Editor akan melihatnya di dokumen tempat pembuat file menggunakannya.
Add-on Editor otomatis menjalankan fungsi onOpen() saat dokumen dibuka.

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 Ekstensi diinstal, diaktifkan, atau keduanya.

Add-on diinstal untuk pengguna tertentu setelah pengguna atau administratornya mendapatkannya dari Google Workspace Marketplace dan memberikan otorisasi untuk mengakses data Google mereka.
Add-on diaktifkan dalam dokumen, formulir, presentasi, atau spreadsheet saat siapa pun menggunakannya di sana.
Saat orang berkolaborasi pada file dan salah satu dari mereka menggunakan add-on, add-on tersebut akan diinstal untuk satu pengguna, dan diaktifkan untuk file.

Tabel berikut merangkum perbedaan antara terinstal dan diaktifkan. Perhatikan bahwa saat Anda menguji skrip sebagai add-on, Anda dapat menjalankan pengujian dalam salah satu atau kedua status ini.

	Diinstal	Aktif
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 sebelumnya diinstal di 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 dalam dokumen, formulir, presentasi, atau spreadsheet tersebut
Mode otorisasi untuk `onOpen()`	`AuthMode.NONE` (kecuali jika diaktifkan juga, dalam hal ini `AuthMode.LIMITED)`	`AuthMode.LIMITED`

Mode otorisasi

Fungsi onOpen() add-on Editor berjalan secara otomatis saat pengguna membuka dokumen, formulir, presentasi, atau spreadsheet. Untuk melindungi data pengguna, Apps Script membatasi kemampuan fungsi onOpen(). Status add-on Editor menentukan mode otorisasi yang digunakan fungsi onOpen() saat 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() 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 cakupan onOpen(), onInstall(), atau global, izin akan gagal dan panggilan lainnya, seperti mengisi menu, akan berhenti. Help 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 pengguna.

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.

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 sebagai hasil dari pemicu seperti onOpen(), onEdit() atau onInstall(). Fungsi kustom di Google Spreadsheet menggunakan mode otorisasi sendiri, AuthMode.CUSTOM_FUNCTION, yang mirip dengan LIMITED, tetapi memiliki batasan yang sedikit berbeda. Untuk semua kasus lainnya, skrip berjalan 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()` (waktu lainnya) `onEdit()` (hanya di Spreadsheet)	Fungsi kustom	Pada waktu lainnya, termasuk: pemicu yang dapat diinstal `onInstall()` `google.script.run`
Akses ke data pengguna	Khusus lokalitas	Khusus lokalitas	Khusus lokalitas	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`	Layanan apa pun yang tidak mengakses data pengguna	Layanan apa pun yang tidak mengakses data pengguna	Semua layanan

Siklus proses otorisasi add-on Editor

Jika add-on diinstal untuk pengguna saat ini atau diaktifkan di 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 diinstal

Saat add-on Editor diinstal dari toko, fungsi onInstall()-nya berjalan di AuthMode.FULL. Dalam mode otorisasi ini, add-on dapat menjalankan rutin 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 dibuka

Saat dokumen, formulir, presentasi, atau spreadsheet terbuka, setiap add-on Editor yang telah diinstal pengguna saat ini atau yang telah diaktifkan oleh kolaborator mana pun dalam file, akan dimuat, dan setiap fungsi onOpen()-nya akan dipanggil. 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 disimpan, untuk membaca konten file saat ini, atau untuk 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 dieksekusi di AuthMode.LIMITED. Anda dapat menggunakan item menu untuk membuka sidebar dan dialog karena 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 sesuai dengan item menu di AuthMode.FULL. Add-on diaktifkan di dokumen, formulir, presentasi, atau spreadsheet jika belum diaktifkan.

Memecahkan masalah menu add-on yang tidak dirender

Menu add-on Anda mungkin tidak dirender jika kode Anda tidak mengelola mode otorisasi dengan benar. Contoh:

Add-on mencoba menjalankan layanan Apps Script yang tidak didukung oleh mode otorisasi saat ini.
Add-on 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 temukan fungsi onOpen().
Telusuri fungsi onOpen() untuk menemukan penyebutan layanan atau objek Apps Script yang terkait dengannya, seperti PropertiesService, SpreadsheetApp, atau GmailApp.
Jika layanan digunakan untuk hal lain selain membuat elemen UI, hapus atau bungkus dalam blok komentar. Hanya sisakan metode ini: .getUi(), .createMenu(), .addItem(), dan .addToUi(). Temukan dan hapus juga layanan apa pun yang berada di luar fungsi.
Identifikasi fungsi yang dapat berisi baris kode yang dikomentari atau dihapus pada langkah sebelumnya, terutama yang menggunakan informasi yang dihasilkan, dan pindahkan panggilan layanan ke fungsi yang memerlukannya. Atur ulang atau tulis ulang kode Anda untuk mengakomodasi perubahan yang dilakukan 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 Config bertuliskan Uji di AuthMode.None
Luncurkan deployment pengujian dan buka menu Ekstensi.
Jika semua item menu ditampilkan, masalah telah diperbaiki. Jika Anda hanya melihat menu Bantuan, kembali ke langkah 1. Anda mungkin melewatkan panggilan layanan.