Cakupan

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 Google Workspace Anda mungkin menggunakan cakupan "Baca pesan saat ini", yang ditulis dalam file manifes Anda sebagai https://www.googleapis.com/auth/gmail.addons.current.message.readonly. Selama alur otorisasi, add-on dengan cakupan ini akan meminta pengguna untuk mengizinkan add-on untuk: Melihat pesan email Anda saat add-on sedang berjalan.

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 info_outline.
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.

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 Google Workspace yang memperluas Gmail, Anda mungkin memiliki hal berikut:

   {
     ...
     "oauthScopes": [
       "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
       "https://www.googleapis.com/auth/userinfo.email"
     ],
     ...
   }
   

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.

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.

Memilih cakupan untuk add-on Google Workspace

Bagian berikut memberikan cakupan yang umum digunakan untuk add-on Google Workspace.

Cakupan editor

Di bawah ini adalah cakupan yang sering digunakan untuk add-on Google Workspace yang memperluas Dokumen, Spreadsheet, dan Slide.

Gmail

Ada beberapa cakupan yang dibuat khusus untuk add-on Google Workspace guna membantu melindungi data Gmail pengguna. Anda harus menambahkan cakupan ini secara eksplisit ke manifes add-on, beserta cakupan lain yang diperlukan oleh kode add-on Anda.

Berikut adalah cakupan yang sering digunakan untuk add-on Google Workspace yang memperluas Gmail; cakupan yang diberi label Wajib harus ditambahkan ke manifest add-on Google Workspace jika add-on Anda memperluas Gmail.

Pastikan Anda juga mengganti cakupan https://mail.google.com yang sangat luas di add-on dengan serangkaian cakupan yang lebih sempit yang memungkinkan interaksi yang dibutuhkan add-on Anda dan tidak lebih.

Cakupan Google Kalender

Berikut adalah cakupan yang sering digunakan untuk add-on Google Workspace yang memperluas Google Kalender.

Cakupan Google Chat

Untuk memanggil Chat API, Anda harus mengautentikasi sebagai pengguna Google Chat atau sebagai aplikasi Chat. Setiap jenis autentikasi memerlukan cakupan yang berbeda, dan tidak semua metode Chat API mendukung autentikasi aplikasi.

Untuk mempelajari lebih lanjut cakupan dan jenis autentikasi Chat, lihat API Chat Ringkasan autentikasi dan otorisasi

Tabel berikut menampilkan metode dan cakupan Chat API yang sering digunakan berdasarkan jenis autentikasi yang didukung:

Cakupan Google Drive

Berikut adalah cakupan yang sering digunakan untuk add-on Google Workspace yang memperluas Google Drive.

Token akses

Untuk melindungi data pengguna, cakupan Gmail yang digunakan dalam add-on Google Workspace hanya memberikan akses sementara ke data pengguna. Untuk mengaktifkan akses sementara, Anda harus memanggil fungsi GmailApp.setCurrentMessageAccessToken(accessToken) menggunakan token akses sebagai argumen. Anda harus mendapatkan token akses dari objek peristiwa tindakan.

Berikut ini contoh cara menyetel token akses untuk mengizinkan akses ke metadata pesan. Satu-satunya cakupan yang diperlukan untuk contoh ini adalah https://www.googleapis.com/auth/gmail.addons.current.message.metadata.

function readSender(e) {
  var accessToken = e.gmail.accessToken;
  var messageId = e.gmail.messageId;

  // The following function enables short-lived access to the current
  // message in Gmail. Access to other Gmail messages or data isn't
  // permitted.
  GmailApp.setCurrentMessageAccessToken(accessToken);
  var mailMessage = GmailApp.getMessageById(messageId);
  return mailMessage.getFrom();
}

Cakupan Google Workspace lainnya

Add-on Anda mungkin memerlukan cakupan tambahan jika menggunakan layanan Google Workspace atau Apps Script lainnya. Biasanya, Anda dapat membiarkan Apps Script mendeteksi cakupan ini dan memperbarui manifes secara otomatis. Saat mengedit daftar cakupan manifes, jangan hapus cakupan apa pun kecuali jika Anda menggantinya dengan alternatif yang lebih sesuai, seperti cakupan yang lebih sempit.

Tabel berikut menunjukkan daftar cakupan yang sering digunakan add-on Google Workspace: