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, dialog akan memberi tahu pengguna tentang izin yang ingin dilakukan aplikasi. Misalnya, add-on mungkin menginginkan izin untuk membaca pesan email pengguna atau membuat acara di kalendernya. Project skrip add-on menentukan setiap izin ini sebagai cakupan OAuth.

Anda mendeklarasikan cakupan dalam manifes menggunakan string URL. Selama alur otorisasi, Apps Script menampilkan deskripsi cakupan yang dapat dibaca manusia kepada pengguna. Misalnya, add-on Anda dapat menggunakan cakupan "Baca dokumen saat ini", yang ditulis dalam manifes Anda 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 dipasang.

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 oleh metode layanan Apps Script tertentu dalam dokumentasi referensi Apps Script.

Melihat cakupan

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

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

Anda juga dapat melihat cakupan saat ini project skrip 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 dibutuhkan skrip dengan memindai kode untuk panggilan fungsi yang memerlukannya. Untuk sebagian besar skrip, hal ini sudah cukup dan menghemat waktu Anda, tetapi untuk add-on yang dipublikasikan, Anda harus menggunakan kontrol yang lebih langsung atas cakupan.

Misalnya, Apps Script mungkin memberikan cakupan https://mail.google.com yang sangat permisif secara default ke project skrip add-on. Saat pengguna mengizinkan project skrip dengan cakupan ini, project tersebut 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 setelan cakupan dengan izin paling rendah yang memungkinkan. Untuk melindungi informasi pengguna, add-on dan aplikasi lain yang dipublikasikan tidak boleh meminta izin cakupan yang lebih banyak daripada yang benar-benar dibutuhkan. Cakupan yang diperlukan add-on Anda diperiksa selama proses peninjauan add-on publikasi; jika add-on menggunakan cakupan yang terlalu luas, add-on tidak dapat lulus peninjauan.

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

1. Melihat 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 Anda.
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 kode 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 menjalani 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 berniat memublikasikan add-on Gmail atau Editor yang menggunakan satu atau beberapa cakupan terbatas, add-on tersebut harus mematuhi semua batasan yang ditentukan sebelum dapat dipublikasikan.

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

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

Ekstensi Alat Developer Google Workspace untuk Visual Studio Code memberikan informasi diagnostik untuk semua cakupan, termasuk deskripsi cakupan dan apakah cakupan tersebut sensitif atau dibatasi.

Cakupan add-on editor

Saat Anda membuat add-on Editor, cakupan yang diperlukan ditentukan oleh layanan dan metode Apps Script yang digunakan oleh 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 Anda menambahkan kode ke project skrip. Untuk add-on Editor, Anda sering kali hanya mengandalkan pengumpulan cakupan otomatis ini, bukan menentukan cakupan sendiri dan menyetelnya secara eksplisit.

Jika Anda tidak menyetel cakupan secara eksplisit dan add-on Editor Anda 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 sedang 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 dalam 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.