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, 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 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 meminta pengguna untuk mengizinkan add-on: Melihat pesan email Anda saat add-on sedang dijalankan.

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 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 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 Google Workspace yang memperluas Gmail, Anda dapat memiliki kode 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 mendapatkan 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.

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

Cakupan yang sering digunakan berikut untuk add-on Google Workspace memperluas Google Dokumen, Google Spreadsheet, dan Google Slide.

Gmail

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

Tabel berikut mencantumkan cakupan yang sering digunakan untuk add-on Google Workspace yang memperluas Gmail. Jika add-on Anda memperluas Gmail, Anda harus menambahkan cakupan apa pun yang berlabel Wajib ke manifes add-on Google Workspace Anda.

Ganti cakupan https://mail.google.com yang luas dengan serangkaian cakupan yang lebih sempit yang memungkinkan interaksi yang dibutuhkan add-on Anda.

Cakupan Google Kalender

Tabel berikut mencantumkan cakupan yang sering digunakan untuk add-on Google Workspace yang memperluas Google Kalender.

Cakupan Google Chat

Untuk memanggil Google Chat API, lakukan autentikasi sebagai pengguna Google Chat atau sebagai aplikasi Google 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 Ringkasan autentikasi dan otorisasi di Chat API.

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

Cakupan Google Drive

Tabel berikut mencantumkan 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 memberikan akses sementara ke data pengguna. Untuk mengaktifkan akses sementara, panggil GmailApp.setCurrentMessageAccessToken menggunakan token akses dari objek peristiwa tindakan.

Token akses yang mengaktifkan cakupan Gmail tidak sama dengan token akses yang ditampilkan oleh ScriptApp.getOAuthToken. Gunakan token yang diberikan dalam 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. Dalam kebanyakan kasus, 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 sempit.

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