Cakupan otorisasi untuk Add-on Editor

Pengguna harus memberikan otorisasi pada add-on dan aplikasi lain yang mengakses data mereka atau bertindak atas nama mereka. Saat pengguna menjalankan add-on untuk pertama kalinya, UI add-on akan menampilkan perintah otorisasi untuk memulai alur otorisasi.

Selama alur ini, perintah akan memberi tahu pengguna tindakan yang ingin dilakukan aplikasi dengan izin tersebut. Misalnya, add-on mungkin ingin izin untuk membaca pesan email pengguna atau membuat acara di kalendernya. Project skrip add-on menentukan izin individual ini sebagai cakupan OAuth.

Anda mendeklarasikan cakupan di manifest menggunakan string URL. Selama alur otorisasi, Apps Script menampilkan deskripsi cakupan yang dapat dibaca manusia kepada pengguna. Misalnya, add-on Anda mungkin menggunakan cakupan "Baca dokumen saat ini", yang ditulis dalam manifes sebagai https://www.googleapis.com/auth/documents.currentonly. Selama alur otorisasi, add-on dengan cakupan ini meminta pengguna untuk mengizinkan add-on untuk: Melihat dan mengelola dokumen tempat aplikasi ini diinstal.

Catatan: Cakupan currentonly hanya tersedia dalam Layanan Apps Script. Hal ini tidak mencakup Layanan Lanjutan Apps Script atau panggilan langsung ke Google Workspace API.

Catatan: Cakupan yang digunakan Apps Script untuk berbagai layanannya tumpang-tindih dengan cakupan yang digunakan oleh API terkait. Misalnya, layanan Kalender Apps Script menggunakan banyak cakupan yang sama dengan Calendar API. Anda dapat mencari cakupan yang diperlukan metode layanan Apps Script tertentu di dokumentasi referensi Apps Script.

Melihat cakupan

Anda dapat melihat cakupan yang saat ini diperlukan project skrip dengan melakukan langkah-langkah berikut:

1. Buka project skrip.
2. Di sebelah kiri, klik Ringkasan .
3. Lihat cakupan di bagian "Cakupan OAuth Project".

Anda juga dapat melihat cakupan project skrip saat ini dalam manifes project, di kolom oauthScopes, tetapi hanya jika Anda telah menetapkan cakupan tersebut secara eksplisit.

Menetapkan cakupan eksplisit

Apps Script secara otomatis menentukan cakupan yang diperlukan skrip dengan memindai kodenya untuk menemukan panggilan fungsi yang memerlukannya. Untuk sebagian besar skrip, hal ini cukup dan menghemat waktu Anda, tetapi untuk add-on yang dipublikasikan, Anda harus menerapkan kontrol yang lebih langsung terhadap cakupan.

Misalnya, Apps Script dapat memberikan cakupan https://mail.google.com yang sangat permisif ke project skrip add-on secara default. Saat pengguna memberikan otorisasi ke project skrip dengan cakupan ini, project akan diberi akses penuh ke akun Gmail pengguna. Untuk add-on yang dipublikasikan, Anda harus mengganti cakupan ini dengan kumpulan yang lebih terbatas yang mencakup kebutuhan add-on dan tidak lebih.

Peringatan: Selalu gunakan cakupan yang paling sedikit permisif. Untuk melindungi informasi pengguna, add-on dan aplikasi yang dipublikasikan lainnya tidak boleh meminta izin cakupan yang lebih dari yang benar-benar diperlukan. Cakupan yang diperlukan add-on Anda akan diperiksa selama proses peninjauan add-on publikasi; jika add-on menggunakan cakupan yang terlalu luas, add-on tersebut tidak dapat lulus peninjauan.

Anda dapat menetapkan cakupan yang digunakan project skrip secara eksplisit dengan mengedit file manifest-nya. Kolom manifes oauthScopes adalah array dari semua cakupan yang digunakan oleh add-on. Untuk menetapkan cakupan project, lakukan hal berikut:

1. Lihat cakupan yang saat ini digunakan add-on Anda. Tentukan perubahan yang perlu dilakukan, seperti menggunakan cakupan yang lebih sempit.
2. Buka file manifes add-on.
3. Temukan kolom tingkat teratas berlabel oauthScopes. Jika tidak ada, Anda dapat menambahkannya.

4. Kolom oauthScopes menentukan array string. Untuk menetapkan cakupan yang digunakan project Anda, ganti konten array ini dengan cakupan yang ingin Anda gunakan. Misalnya, untuk Add-on Editor yang memperluas Spreadsheet, Anda mungkin memiliki hal berikut:

   {
     ...
     "oauthScopes": [
       "https://www.googleapis.com/auth/script.container.ui",
       "https://www.googleapis.com/auth/spreadsheets"
     ],
     ...
   }
   

5. Simpan perubahan file manifes.

Verifikasi OAuth

Penggunaan cakupan OAuth sensitif tertentu mungkin mengharuskan add-on Anda melalui verifikasi klien OAuth sebelum Anda dapat memublikasikannya. Untuk informasi selengkapnya, lihat panduan berikut:

• Verifikasi klien OAuth untuk Apps Script
• Aplikasi yang belum diverifikasi
• FAQ verifikasi OAuth
• Layanan Google API: Kebijakan Data Pengguna

Cakupan yang dibatasi

Cakupan tertentu dibatasi dan tunduk pada aturan tambahan yang membantu melindungi data pengguna. Jika Anda ingin memublikasikan Add-on Gmail atau Editor yang menggunakan satu atau beberapa cakupan yang dibatasi, add-on tersebut harus mematuhi semua pembatasan yang ditentukan sebelum dapat dipublikasikan.

Tinjau daftar lengkap cakupan yang dibatasi sebelum Anda mencoba memublikasikan. Jika add-on Anda menggunakan salah satunya, Anda harus mematuhi Persyaratan tambahan untuk cakupan API tertentu sebelum memublikasikannya.

Catatan: Hindari penggunaan cakupan terbatas di add-on jika memungkinkan—akan lebih mudah untuk lulus peninjauan add-on untuk publikasi publik jika Anda tidak menggunakannya. Anda dapat menggunakan cakupan terbatas secara bebas untuk add-on non-publik.

Cakupan Add-on Editor

Saat Anda mem-build Add-on Editor, cakupan yang diperlukan ditentukan oleh layanan dan metode Apps Script yang digunakan kode add-on. Misalnya, add-on Spreadsheet mungkin memerlukan cakupan https://www.googleapis.com/auth/spreadsheets.readonly untuk membaca informasi dari Google Spreadsheet yang berbeda.

Apps Script secara otomatis menentukan cakupan yang diperlukan oleh layanan yang Anda gunakan saat menambahkan kode ke project skrip. Untuk Add-on Editor, Anda sering kali dapat hanya mengandalkan pengumpulan cakupan otomatis ini, bukan menentukan cakupan sendiri dan menetapkannya secara eksplisit.

Jika Anda tidak menetapkan cakupan secara eksplisit dan Add-on Editor hanya membaca atau menulis ke file editor yang terbuka, tambahkan komentar berikut ke salah satu file project skrip Anda:

  /**
   * @OnlyCurrentDoc
   */

Komentar ini memberi tahu Apps Script untuk mempersempit cakupan file editor yang ditetapkan ke currentonly. Misalnya, jika Anda menambahkan komentar ini ke file project skrip add-on Google Spreadsheet, Anda menentukan bahwa add-on hanya memerlukan izin untuk beroperasi di Spreadsheet yang saat ini terbuka, dan bukan Spreadsheet lain yang mungkin dimiliki pengguna di Google Drive. Sebaliknya, Anda tidak boleh menggunakan komentar ini jika add-on Spreadsheet Anda perlu membaca atau menulis data di Spreadsheet yang saat ini belum dibuka oleh pengguna.

Catatan: Cakupan currentonly hanya tersedia dalam Layanan Apps Script. Hal ini tidak mencakup Layanan Lanjutan Apps Script atau panggilan langsung ke Google Workspace API.