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 memberi tahu pengguna tindakan yang ingin dilakukan aplikasi dengan izin yang diberikan. 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.

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 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 melakukan kontrol yang lebih langsung terhadap cakupan.

Misalnya, Apps Script dapat memberikan cakupan yang sangat permisif https://mail.google.com secara default kepada project skrip add-on. Jika pengguna mengizinkan 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.

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. Lihat cakupan yang 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 mendapatkan informasi selengkapnya, lihat panduan berikut:

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.

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 Google Apps Script yang digunakan oleh kode add-on. Misalnya, add-on Google Spreadsheet mungkin memerlukan cakupan https://www.googleapis.com/auth/spreadsheets.readonly untuk membaca informasi dari 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 dapat mengandalkan pengumpulan cakupan otomatis ini, bukan menentukan cakupan sendiri dan menyetelnya secara eksplisit.

Jika Anda tidak menetapkan 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 Spreadsheet, Anda menentukan bahwa add-on hanya memerlukan izin untuk beroperasi di Spreadsheet yang terbuka, dan bukan Spreadsheet lain yang mungkin dimiliki pengguna di Google Drive. Sebaliknya, Anda tidak boleh menggunakan komentar ini jika add-on Spreadsheet perlu membaca atau menulis data di Spreadsheet yang tidak dibuka pengguna.