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 menampilkan prompt otorisasi untuk memulai alur otorisasi.

Selama alur ini, prompt memberi tahu pengguna apa yang diinginkan aplikasi izin untuk melakukannya. Misalnya, add-on mungkin meminta izin untuk membaca sebuah pesan email pengguna atau membuat acara di kalender mereka. Skrip add-on project menentukan izin individual 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 manifes 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 untuk: Melihat pesan email Anda saat add-on sedang berjalan.

Melihat cakupan

Anda dapat melihat cakupan yang saat ini dibutuhkan project skrip Anda dengan melakukan berikut ini:

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

Anda juga bisa melihat cakupan project skrip saat ini dalam manifes project, berdasarkan oauthScopes default, tetapi hanya jika Anda telah menetapkan cakupan tersebut secara eksplisit.

Menetapkan cakupan eksplisit

Apps Script secara otomatis menentukan cakupan yang diperlukan skrip dengan memindai kodenya untuk panggilan fungsi yang memerlukannya. Untuk sebagian besar skrip, memadai dan menghemat waktu Anda, tetapi untuk add-on yang dipublikasikan, Anda harus memiliki kontrol yang lebih besar atas cakupannya.

Misalnya, Apps Script mungkin memberikan cakupan https://mail.google.com yang sangat permisif ke project skrip add-on secara default. Saat pengguna mengizinkan skrip dengan cakupan ini, project tersebut diberi akses penuh ke akun Gmail pengguna menggunakan akun layanan. Untuk add-on yang dipublikasikan, Anda harus mengganti cakupan ini dengan add-on set terbatas yang dapat memenuhi 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 proyek, lakukan metode berikut ini:

  1. Lihat cakupan yang saat ini digunakan add-on Anda. Menentukan apa perlu dilakukan perubahan, seperti menggunakan ruang lingkup yang lebih sempit.
  2. Buka file manifes add-on Anda.
  3. Temukan kolom tingkat teratas berlabel oauthScopes. Jika tidak ada, Anda dapat menambahkannya.

  4. oauthScopes menentukan array string. Untuk menetapkan cakupan yang digunakan project, ganti konten array ini dengan cakupan yang ingin menggunakannya. 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 melalui verifikasi klien OAuth sebelum Anda dapat memublikasikannya. Untuk informasi selengkapnya, lihat panduan berikut:

Cakupan yang dibatasi

Cakupan tertentu dibatasi dan tunduk pada aturan tambahan yang membantu melindungi data pengguna. Jika Anda ingin menerbitkan Add-on Gmail atau Editor yang menggunakan satu atau beberapa cakupan yang dibatasi, add-on harus mematuhi semua batasan sebelum dapat dipublikasikan.

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

Cakupan kalender

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

Cakupan
Mengakses metadata peristiwa https://www.googleapis.com/auth/calendar.addons.execute

Wajib jika add-on mengakses metadata acara Kalender. Mengizinkan add-on mengakses metadata peristiwa.

Membaca data peristiwa buatan pengguna https://www.googleapis.com/auth/calendar.addons.current.event.read

Wajib jika add-on perlu membaca data peristiwa yang dibuat pengguna. Mengizinkan add-on mengakses data peristiwa yang dibuat pengguna. Data ini hanya tersedia jika Kolom manifes addOns.calendar.eventAccess disetel ke READ atau READ_WRITE.

Menulis data peristiwa buatan pengguna https://www.googleapis.com/auth/calendar.addons.current.event.write

Wajib jika add-on perlu menulis data peristiwa yang dibuat pengguna. Mengizinkan add-on mengedit data peristiwa yang dibuat pengguna. Data ini hanya tersedia jika kolom manifes addOns.calendar.eventAccess ditetapkan ke WRITE atau READ_WRITE.

Cakupan Drive

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

Cakupan
Membaca metadata item yang dipilih https://www.googleapis.com/auth/drive.addons.metadata.readonly

Wajib ada jika add-on menerapkan antarmuka kontekstual yang dipicu saat pengguna memilih item di Drive. Mengizinkan add-on membaca metadata terbatas tentang item yang telah dipilih pengguna di Google Drive. Metadata dibatasi untuk ID, judul, jenis MIME, URL ikon item, dan apakah add-on memiliki izin untuk mengakses item.

Akses per file https://www.googleapis.com/auth/drive.file

Direkomendasikan jika add-on perlu mengakses setiap file Drive. Memberikan akses per file ke file yang dibuat atau dibuka oleh aplikasi, menggunakan Apps Script Drive Lanjutan Layanan. Namun, hal ini tidak mengizinkan penggunaan tindakan serupa menggunakan layanan Drive dasar. Otorisasi file diberikan berdasarkan per file dan dicabut saat pengguna mencabut otorisasi aplikasi.

Lihat Contoh permintaan akses file untuk file yang dipilih.

Cakupan add-on Gmail

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

Berikut adalah cakupan yang sering digunakan untuk Add-on Google Workspace yang memperluas Gmail; yang berlabel Wajib harus ditambahkan ke manifes Add-on Google Workspace jika add-on Anda memperluas Gmail.

Pastikan juga untuk mengganti cakupan https://mail.google.com yang sangat luas di tambahan dengan cakupan cakupan yang lebih sempit, yang memungkinkan interaksi dengan add-on dan tidak lebih dari itu.

Cakupan
Membuat draf baru https://www.googleapis.com/auth/gmail.addons.current.action.compose

Wajib diisi jika add-on menggunakan menulis pemicu tindakan. Izinkan add-on membuat pesan draf baru untuk sementara waktu dan balasan. Lihat Menulis pesan draf untuk mengetahui detailnya; cakupan ini juga sering digunakan dengan tindakan compose. Memerlukan token akses.

Membaca metadata pesan yang terbuka https://www.googleapis.com/auth/gmail.addons.current.message.metadata

Memberikan akses sementara ke metadata pesan terbuka (seperti subjek atau penerima). Tidak mengizinkan pembacaan konten pesan dan memerlukan token akses.

Wajib jika add-on menggunakan metadata dalam tindakan compose pemicu. Untuk tindakan compose, cakupan ini diperlukan jika pemicu compose memerlukan akses ke metadata. Dalam praktiknya, cakupan ini memungkinkan penulis memicu akses daftar penerima (kepada:, cc:, dan bcc:) dari draf email balasan.

Membaca konten pesan terbuka https://www.googleapis.com/auth/gmail.addons.current.message.action

Memberikan akses ke konten pesan yang terbuka setelah interaksi pengguna, seperti saat item menu add-on dipilih. Memerlukan token akses.

Membaca konten rangkaian pesan terbuka https://www.googleapis.com/auth/gmail.addons.current.message.readonly

Memberikan akses sementara ke metadata dan konten pesan terbuka. Juga memberikan akses ke konten pesan lain di ruang terbuka . Memerlukan token akses.

Membaca metadata dan konten pesan apa pun https://www.googleapis.com/auth/gmail.readonly

Membaca metadata dan konten email apa pun, termasuk pesan yang dibuka. Diperlukan jika Anda perlu membaca informasi tentang pesan lain, seperti saat melakukan kueri penelusuran atau membaca seluruh rangkaian pesan email.

Token akses

Untuk melindungi data pengguna, cakupan Gmail yang digunakan di 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 adalah contoh penetapan token akses untuk mengizinkan akses ke metadata pesan. Satu-satunya ruang lingkup 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 editor

Berikut adalah cakupan yang sering digunakan untuk Add-on Google Workspace yang memperluas Dokumen, Spreadsheet, dan Slide.

Cakupan
Akses file Dokumen saat ini https://www.googleapis.com/auth/documents.currentonly

Diperlukan jika add-on mengakses Apps Script Docs API. Memberikan akses sementara ke konten dokumen yang terbuka.

Akses file Spreadsheet saat ini https://www.googleapis.com/auth/spreadsheets.currentonly

Wajib ada jika add-on mengakses Apps Script Sheets API. Memberikan akses sementara ke konten spreadsheet yang terbuka.

Akses file Slide Saat Ini https://www.googleapis.com/auth/presentations.currentonly

Diperlukan jika add-on mengakses Apps Script Slides API. Memberikan akses sementara ke konten presentasi terbuka.

Akses per file https://www.googleapis.com/auth/drive.file

Wajib agar add-on dapat menggunakan onFileScopeGrantedTrigger dan apakah add-on mengakses Dokumen, Spreadsheet, Slide, atau Drive API. Memberikan akses per file ke file yang dibuat atau dibuka oleh aplikasi, menggunakan Layanan Drive Lanjutan Apps Script. Hal ini tidak mengizinkan penggunaan tindakan serupa menggunakan layanan Drive dasar, . Otorisasi file diberikan berdasarkan per file dan dicabut saat pengguna mencabut otorisasi aplikasi.

Cakupan lainnya

Add-on Anda mungkin memerlukan cakupan tambahan jika menggunakan layanan Apps Script lainnya. Dalam sebagian besar kasus, Anda dapat mengizinkan Apps Script mendeteksi cakupan tersebut 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.

Sebagai referensi, berikut adalah daftar cakupan Apps Script yang sering digunakan dalam bersama dengan Add-on Google Workspace:

Cakupan
Membaca alamat email pengguna https://www.googleapis.com/auth/userinfo.email

Mengizinkan project membaca alamat email pengguna saat ini.

Mengizinkan panggilan ke layanan eksternal https://www.googleapis.com/auth/script.external_request

Memungkinkan project membuat permintaan UrlFetch. Hal ini juga diperlukan jika proyek menggunakan OAuth2 untuk Apps Script.

Membaca zona waktu dan lokalitas pengguna https://www.googleapis.com/auth/script.locale

Memungkinkan project mempelajari lokalitas dan zona waktu pengguna saat ini. Lihat Mengakses lokalitas dan zona waktu pengguna untuk mengetahui detailnya.

Membuat pemicu https://www.googleapis.com/auth/script.scriptapp

Memungkinkan project membuat pemicu.

Pratinjau link pihak ketiga https://www.googleapis.com/auth/workspace.linkpreview

Wajib jika add-on menampilkan pratinjau link dari layanan pihak ketiga. Mengizinkan project melihat link dalam aplikasi Google Workspace saat pengguna berinteraksi dengannya. Untuk mempelajari lebih lanjut, lihat Melihat pratinjau link dengan smart chip.

Membuat resource pihak ketiga https://www.googleapis.com/auth/workspace.linkcreate

Wajib diisi jika add-on membuat resource di layanan pihak ketiga. Izinkan project untuk membaca informasi yang dikirimkan pengguna formulir pembuatan sumber daya dan sisipkan link ke referensi dalam aplikasi Google Workspace. Untuk mempelajari lebih lanjut, lihat Buat resource pihak ketiga dari menu @.