Halaman ini diterjemahkan oleh Cloud Translation API.

Otorisasi Add-on Editor

Otorisasi untuk banyak aplikasi berbasis Apps Script mudah dilakukan karena proyek skrip meminta izin apa pun yang hilang yang diperlukan ketika seseorang mencoba untuk menggunakannya.

Model otorisasi untuk Add-on Editor kini lebih kompleks karena beberapa alasan:

Saat pengguna membuat file, semua add-on yang diinstal pengguna tercantum di menu Ekstensi, bahkan jika pengguna belum memberikan otorisasi pada add-on tersebut.
Add-on ini bekerja pada file di Google Drive yang dapat dibagikan dengan kolaborator. Kolaborator yang tidak menginstal Add-on Editor dan melihatnya di dokumen di mana pembuat file menggunakannya.
Add-on Editor secara otomatis menjalankan onOpen() fungsi ketika dokumen terbuka.

Untuk melindungi data pengguna, mode otorisasi diterapkan yang membuat beberapa layanan tidak tersedia untuk onOpen(). Panduan ini dapat membantu Anda memahami apa kode Anda dapat dilakukan dan kapan.

Model otorisasi

Mode otorisasi Add-on Editor bergantung pada statusnya, yang bergantung pada pengguna yang menggunakannya: pengguna yang menginstal add-on tersebut atau kolaborator.

Status Add-on Editor

Add-on Editor di menu Ekstensi diinstal, diaktifkan, atau keduanya.

Add-on diinstal untuk pengguna setelah mereka atau administrator mereka mendapatkannya dari Google Workspace Marketplace dan memberinya otorisasi untuk mengakses data Google mereka.
Add-on diaktifkan di dokumen, formulir, presentasi, atau {i>spreadsheet <i}saat siapa pun menggunakannya.
Saat orang berkolaborasi pada sebuah file dan salah satunya menggunakan add-on, add-on ini diinstal untuk satu pengguna, dan diaktifkan untuk file tersebut.

Tabel berikut meringkas perbedaan antara terinstal dan diaktifkan. Perhatikan bahwa ketika Anda menguji skrip sebagai add-on Anda dapat menjalankan pengujian dengan 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 itu, atau Menggunakan {i>add-on<i} yang sebelumnya dipasang di dokumen, formulir, presentasi, atau spreadsheet
Menu dapat dilihat	Hanya pengguna itu, di semua dokumen, formulir, presentasi, atau {i>spreadsheet <i}yang mereka buka atau buat	Semua kolaborator pada dokumen, formulir, presentasi, atau spreadsheet
Mode otorisasi untuk `onOpen()`	`AuthMode.NONE` (kecuali jika diaktifkan, dalam hal ini `AuthMode.LIMITED)`	`AuthMode.LIMITED`

Mode otorisasi

Fungsi onOpen() dari Add-on Editor berjalan secara otomatis saat pengguna membuka dokumen, formulir, presentasi, atau {i>spreadsheet<i}. Untuk melindungi data, Apps Script membatasi dapat dilakukan oleh fungsi onOpen(). Status Add-on Editor menentukan mode otorisasi mana yang digunakan untuk menjalankan fungsi onOpen().

Jika Add-on Editor diaktifkan dalam file, formulir, presentasi, atau spreadsheet, onOpen() berjalan dalam AuthMode.LIMITED. Jika add-on tidak diaktifkan dan hanya diinstal, onOpen() berjalan di AuthMode.NONE.

Di AuthMode.NONE, add-on tidak dapat dijalankan layanan hingga pengguna berinteraksi dengan add-on dengan mengklik atau menjalankan fungsi kustom. Jika add-on akan mencoba menggunakan layanan ini di onOpen(), onInstall(), atau lingkup global, izin gagal dan panggilan lainnya, seperti mengisi menu, berhenti. Bantuan adalah satu-satunya opsi yang didukung.

Untuk menjalankan panggilan layanan yang dibatasi, Anda harus menggunakan otorisasi AuthMode.FULL mode. Fungsi interaksi pengguna, seperti mengklik opsi menu, hanya dapat dijalankan dalam mode ini. Setelah kode dijalankan dalam mode AuthMode.FULL, add-on ini dapat menggunakan semua cakupan yang diizinkan oleh pengguna.

Apps Script meneruskan mode otorisasi sebagai properti authMode dari Apps Script parameter peristiwa, e; nilai dari e.authMode sesuai dengan konstanta di Apps Script enum ScriptApp.AuthMode.

Mode otorisasi berlaku untuk semua metode eksekusi Apps Script, termasuk menjalankan dari editor skrip, dari item menu, atau dari Apps Script Panggilan google.script.run. Namun, properti e.authMode hanya dapat diperiksa jika skrip berjalan sebagai hasilnya dari pemicu seperti onOpen(), onEdit() atau onInstall(). Fungsi kustom di Google Spreadsheet menggunakan mode otorisasi mereka sendiri, AuthMode.CUSTOM_FUNCTION, yang mirip dengan LIMITED tetapi memiliki batasan yang sedikit berbeda. Untuk semua dalam kasus lain, skrip berjalan di AuthMode.FULL, seperti yang dijelaskan dalam tabel sementara.

	`NONE`	`LIMITED`	`CUSTOM_FUNCTION`	`FULL`
Terjadi selama	`onOpen()` (jika pengguna telah menginstal tetapi tidak mengaktifkannya dalam dokumen, formulir, presentasi, atau {i>spreadsheet<i})	`onOpen()` (lainnya) `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`	Setiap layanan yang tidak mengakses data pengguna	Setiap layanan yang tidak mengakses data pengguna	Semua layanan

Siklus proses otorisasi Add-on Editor

Saat add-on diinstal untuk pengguna saat ini atau diaktifkan dalam file saat ini, add-on dimuat untuk dokumen, formulir, presentasi, atau {i>spreadsheet<i} ketika file itu dibuka. Add-onnya adalah yang tercantum di menu Ekstensi dan mulai mendengarkan pemicu sederhana onInstall(), onOpen(), dan onEdit(). Jika pengguna mengklik Item menu Extensions, sistem ini berjalan.

Add-on Editor telah diinstal

Ketika Add-on Editor diinstal dari toko, Fungsi onInstall() berjalan di AuthMode.FULL. Dalam mode otorisasi ini, {i>add-on <i}dapat menjalankan rutinitas pengaturan yang rumit. Anda juga harus gunakan 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 {i>spreadsheet<i} terbuka, semuanya akan dimuat Add-on Editor yang telah diinstal oleh pengguna saat ini atau yang telah diaktifkan oleh kolaborator mana pun dalam file tersebut, dan memanggil setiap fungsi onOpen()-nya. Mode otorisasi yang onOpen() bergantung pada apakah add-on diinstal atau diaktifkan.

Jika add-on hanya membuat menu dasar, mode ini tidak 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 Apps Script yang disimpan properties, 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 tindakan 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();
}

Perlu diketahui bahwa add-on tidak dapat membuka sidebar atau dialog saat dijalankan di AuthMode.LIMITED. Anda dapat menggunakan item menu untuk membuka sidebar dan dialog karena keduanya berjalan di AuthMode.FULL.

Pengguna menjalankan Add-on Editor

Saat pengguna mengklik item menu Ekstensi, Apps Script terlebih dahulu memeriksa apakah pengguna telah menginstal {i>add-on<i}, dan meminta mereka untuk melakukannya jika belum. Jika pengguna telah memberikan otorisasi {i>add-on<i}, skrip menjalankan fungsi yang sesuai dengan item menu di AuthMode.FULL. Tujuan {i>add-on<i} diaktifkan dalam dokumen, formulir, presentasi, atau {i>spreadsheet <i}jika belum dilakukan.

Memecahkan masalah menu add-on yang tidak dirender

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

Add-on mencoba menjalankan Apps Script layanan 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 penyebutan Apps Script layanan atau objek yang terkait dengannya, seperti PropertiesService, SpreadsheetApp atau GmailApp.
Jika layanan digunakan untuk hal lain selain membuat elemen UI, menghapusnya atau melipatnya dalam blok komentar. Hanya tersisa metode ini: .getUi(), .createMenu(), .addItem(), dan .addToUi(). Selain itu, temukan dan hapus layanan apa pun yang berada di luar fungsi.
Mengidentifikasi fungsi yang dapat berisi baris kode yang diberi komentar atau dihapus pada langkah sebelumnya, terutama mereka yang menggunakan informasi yang dihasilkan, dan memindahkan panggilan layanan ke fungsi yang membutuhkannya. Atur 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 Diinstal untuk pengguna saat ini dan teks di bawah kotak Konfigurasi menyatakan 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 telah melewatkan panggilan layanan.