Cakupan otorisasi untuk add-on Editor

Pengguna harus mengotorisasi 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 tentang izin yang ingin diminta oleh aplikasi. Misalnya, add-on mungkin ingin meminta 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 dalam manifes menggunakan string URL. Selama alur otorisasi, Apps Script akan menampilkan deskripsi cakupan yang dapat dibaca manusia kepada pengguna. Misalnya, add-on Anda mungkin menggunakan cakupan "Read current document", yang ditulis dalam manifes Anda sebagai https://www.googleapis.com/auth/documents.currentonly. Selama alur otorisasi, add-on dengan cakupan ini akan meminta pengguna untuk mengizinkan add-on: Melihat dan mengelola dokumen tempat aplikasi ini diinstal.

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 oleh project skrip dengan melakukan hal 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 bagian kolom oauthScopes, tetapi hanya jika Anda telah menetapkan cakupan tersebut secara eksplisit.

Menetapkan cakupan eksplisit

Apps Script otomatis menentukan cakupan yang diperlukan 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 cakupan yang lebih langsung.

Misalnya, Apps Script mungkin memberikan cakupan https://mail.google.com yang sangat permisif ke project skrip add-on secara default. Saat pengguna mengotorisasi 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, 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 atas yang diberi label 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 menjalani verifikasi klien OAuth sebelum dapat dipublikasikan. 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 ingin memublikasikan add-on Gmail atau Editor yang menggunakan satu atau beberapa cakupan yang dibatasi, 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 cakupan 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 otomatis menentukan cakupan yang diperlukan oleh layanan yang Anda gunakan saat menambahkan kode ke project skrip. Untuk add-on Editor, Anda sering kali dapat mengandalkan pengumpulan cakupan otomatis ini, bukan menentukan cakupan sendiri dan menetapkannya secara eksplisit.

Jika Anda tidak menetapkan cakupan secara eksplisit dan add-on Editor Anda hanya membaca atau menulis ke file editor 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 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 tidak dibuka oleh pengguna.