Pengguna harus mengizinkan 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 menyajikan
deskripsi ruang lingkup yang dapat dibaca
manusia kepada pengguna. Misalnya, Add-on Google Workspace Anda
mungkin menggunakan fungsi "Baca pesan saat ini" cakupan, yang ditulis dalam manifes Anda sebagai
https://www.googleapis.com/auth/gmail.addons.current.message.readonly
. Selama
dalam alur otorisasi, add-on dengan cakupan ini meminta pengguna mengizinkan
add-on: Melihat pesan email saat add-on dijalankan.
Melihat cakupan
Anda dapat melihat cakupan yang saat ini diperlukan project skrip Anda dengan melakukan berikut ini:
- Buka project skrip.
- Di sebelah kiri, klik Overview .
- 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 project skrip add-on
cakupan https://mail.google.com
secara default. Saat pengguna mengizinkan skrip
project 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 secara eksplisit menetapkan cakupan yang digunakan project skrip dengan mengedit
file manifes. Kolom manifes
oauthScopes
adalah array
semua cakupan yang digunakan oleh add-on ini. Untuk menetapkan cakupan proyek, lakukan metode
berikut ini:
- Lihat cakupan yang saat ini digunakan add-on Anda. Menentukan apa perlu dilakukan perubahan, seperti menggunakan ruang lingkup yang lebih sempit.
- Buka file manifes add-on Anda.
- Temukan kolom tingkat teratas berlabel
oauthScopes
. Jika tidak ada, Anda dapat menambahkannya. 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" ], ... }
Simpan perubahan file manifes.
Verifikasi OAuth
Penggunaan cakupan OAuth sensitif tertentu mungkin mengharuskan add-on melalui 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 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 dengan Persyaratan tambahan untuk cakupan API tertentu sebelum dipublikasikan.
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
Diperlukan jika add-on mengakses metadata acara Kalender. Mengizinkan add-on untuk mengakses metadata peristiwa. |
Membaca data peristiwa buatan pengguna |
https://www.googleapis.com/auth/calendar.addons.current.event.read
Wajib ada jika add-on perlu membaca data peristiwa buatan pengguna.
Mengizinkan add-on mengakses data peristiwa buatan pengguna. Data ini
hanya tersedia jika
Kolom manifes |
Menulis data peristiwa yang dibuat pengguna |
https://www.googleapis.com/auth/calendar.addons.current.event.write
Wajib jika add-on perlu menulis data peristiwa buatan pengguna.
Mengizinkan add-on mengedit data peristiwa yang dibuat pengguna. Data ini
hanya tersedia jika
Kolom manifes |
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 untuk membaca metadata terbatas tentang item yang dimiliki pengguna dipilih di Google Drive. Metadata terbatas pada ID item, judul, jenis MIME, URL ikon, 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 Drive individual
.
Memberikan akses per file ke file yang dibuat atau dibuka oleh aplikasi, menggunakan
Apps Script Drive Lanjutan
Layanan. Hal ini tidak mengizinkan penggunaan tindakan serupa menggunakan
layanan Drive dasar,
. Otorisasi file diberikan
per file dan
dicabut jika pengguna membatalkan otorisasi aplikasi. |
Cakupan add-on Gmail
Ada beberapa cakupan yang dibuat khusus untuk Add-on Google Workspace untuk membantu melindungi Gmail pengguna layanan otomatis dan data skalabel. Anda harus menambahkan cakupan ini secara eksplisit ke manifes add-on Anda, bersama dengan yang lain yang diperlukan oleh kode add-on Anda.
Di bawah ini 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 Anda.
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 draf pesan untuk mengetahui detailnya; ruang lingkup ini juga sering digunakan dengan membuat tindakan. 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 isi pesan
dan memerlukan token akses. Wajib ada jika add-on menggunakan metadata dalam tindakan compose pemicu. Untuk compose actions, cakupan ini diperlukan jika pemicu compose yang membutuhkan akses ke {i>metadata<i}. Dalam praktiknya, cakupan ini memungkinkan memicu daftar penerima akses (to:, cc:, dan bcc:) dari balasan draf email. |
Membaca konten pesan yang terbuka |
https://www.googleapis.com/auth/gmail.addons.current.message.action
Memberikan akses ke konten pesan terbuka setelah interaksi pengguna, seperti saat item menu add-on dipilih. Memerlukan akses sebelumnya yang benar. |
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 semua metadata dan konten email, termasuk pesan yang terbuka. Wajib diisi jika Anda perlu membaca informasi tentang pesan lain, seperti saat melakukan kueri penelusuran atau membaca seluruh utas 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 memperoleh token akses dari
objek peristiwa tindakan.
Berikut ini contoh setelan 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
Di bawah ini adalah cakupan yang sering digunakan untuk Add-on Google Workspace yang memperluas penggunaan 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 |
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 menghapus cakupan apa pun kecuali Anda menggantinya dengan alternatif yang lebih tepat, 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 untuk membaca alamat email pengguna saat ini. |
Izinkan panggilan ke layanan eksternal |
https://www.googleapis.com/auth/script.external_request
Izinkan proyek untuk membuat
|
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
Izinkan project untuk membuat pemicu. |
Pratinjau link pihak ketiga |
https://www.googleapis.com/auth/workspace.linkpreview
Wajib ada jika add-on mempratinjau 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 ada 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 @. |