Halaman ini diterjemahkan oleh Cloud Translation API.

Otorisasi Add-on Editor

Pada umumnya, Anda harus mengizinkan add-on sebelum dapat menggunakannya. Untuk banyak project Apps Script seperti aplikasi web, otorisasi sudah mudah—project skrip meminta izin yang hilang yang diperlukan saat Anda mencoba menggunakannya. Setelah diotorisasi, Anda dapat menggunakan project skrip dengan bebas. Semua orang yang menggunakan project skrip tersebut akan 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 membuat Add-on Editor dengan mempertimbangkan mode otorisasi yang berbeda. Editor Google Dokumen juga menyediakan menu Add-on di UI-nya yang diisi oleh add-on yang telah diinstal—meskipun Anda belum mengizinkan add-on tersebut. Ini akan menambahkan beberapa kerumitan tambahan pada model otorisasi.

Model otorisasi

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

Setelah mendapatkan Add-on Editor dari Store, Anda akan melihatnya di menu add-on untuk setiap dokumen, formulir, presentasi, atau spreadsheet yang dibuka atau dibuat. Kolaborator tidak akan melihat add-on kecuali dalam dokumen, formulir, presentasi, atau spreadsheet tempat Anda benar-benar menggunakannya.
Setelah Anda menggunakan Add-on Editor dalam dokumen, formulir, presentasi, atau spreadsheet, kolaborator juga melihatnya di menu add-on, tetapi hanya untuk file tersebut (kecuali jika mereka juga telah 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 editor Google Dokumen terbuka, perilaku di atas menambahkan beberapa kerumitan pada aturan otorisasi Apps Script. Lagi pula, pengguna tidak akan keberatan dengan add-on yang mengakses data pribadi setiap kali mereka membuka dokumen, formulir, presentasi, atau spreadsheet. Panduan ini akan membantu Anda memahami fungsi kode dan waktu penerapannya.

Diinstal versus diaktifkan

Jika Anda melihat Add-on Editor ada di menu, keduanya akan muncul di salah satu (atau kedua) status berikut: 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, formulir, presentasi, atau spreadsheet tertentu jika digunakan di sana. Jika dua orang berkolaborasi dan salah satunya menggunakan add-on, file tersebut akan diinstal untuk satu pengguna dan diaktifkan untuk file.

Tabel di bawah ini merangkum kedua status. Perhatikan bahwa saat menguji skrip sebagai add-on, Anda dapat memilih untuk menjalankan pengujian di 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 dapat dilihat	Hanya pengguna tersebut, di semua dokumen, formulir, presentasi, atau spreadsheet yang mereka buka atau buat.	Semua kolaborator di dokumen, formulir, presentasi, atau spreadsheet tersebut
`onOpen(e)` berlari di	`AuthMode.NONE` (kecuali jika diaktifkan, dalam hal ini `AuthMode.LIMITED)`	`AuthMode.LIMITED`

Mode otorisasi

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

Secara khusus, status terinstal dan diaktifkan menentukan mode otorisasi mana yang dijalankan oleh 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, formulir, presentasi, atau spreadsheet 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 dalam tabel di bawah.

	`NONE`	`LIMITED`	`CUSTOM_FUNCTION`	`FULL`
Terjadi untuk	`onOpen(e)` (jika pengguna telah menginstal add-on, tetapi tidak mengaktifkannya di dokumen, formulir, presentasi, atau spreadsheet)	`onOpen(e)` (semua waktu) `onEdit(e)` (hanya di Spreadsheet)	Fungsi kustom	Semua waktu, termasuk: pemicu yang dapat diinstal `onInstall(e)` `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`	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 file saat ini, add-on akan dimuat di dokumen, formulir, presentasi, atau spreadsheet, 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, item tersebut 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, formulir, presentasi, atau spreadsheet sudah terbuka sehingga fungsi onOpen(e) Anda belum berjalan. Untuk memudahkan, 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, formulir, presentasi, atau spreadsheet terbuka, aplikasi akan memuat setiap Add-on Editor yang telah diinstal pengguna saat ini atau yang telah diaktifkan oleh setiap kolaborator dalam file, dan 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 tidak menjadi masalah. Contoh ini menampilkan 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, formulir, presentasi, atau spreadsheet saat ini, atau melakukan tugas lanjutan lainnya, Anda perlu 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 mengetahui apakah pengguna telah menginstal add-on, dan meminta mereka untuk melakukannya, jika tidak. Jika pengguna telah mengizinkan add-on, skrip akan menjalankan fungsi yang sesuai dengan item menu di AuthMode.FULL. Add-on ini juga diaktifkan di dokumen, formulir, presentasi, atau spreadsheet, jika belum diaktifkan.