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 akan memberi tahu pengguna tindakan yang ingin dilakukan aplikasi dengan izin tersebut. Misalnya, add-on mungkin ingin 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 di 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 diperlukan project skrip Anda dengan melakukan hal berikut:
- Buka project skrip.
- Di sebelah kiri, klik Ringkasan .
- Lihat cakupan di bagian "Cakupan OAuth Project".
Anda juga dapat melihat cakupan project skrip saat ini 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 diperlukan skrip dengan memindai kodenya untuk menemukan panggilan fungsi yang memerlukannya. Untuk sebagian besar skrip, hal ini cukup dan menghemat waktu Anda, tetapi untuk add-on yang dipublikasikan, Anda harus menerapkan kontrol yang lebih langsung terhadap cakupan.
Misalnya, Apps Script mungkin memberikan cakupan https://mail.google.com
yang sangat permisif untuk project skrip add-on secara default. Saat pengguna memberikan otorisasi ke 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:
- Lihat cakupan yang saat ini digunakan add-on Anda. Tentukan perubahan apa yang perlu dilakukan, seperti menggunakan cakupan yang lebih sempit.
- Buka file manifes add-on.
- Temukan kolom tingkat teratas berlabel
oauthScopes
. Jika tidak ada, Anda dapat menambahkannya. 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" ], ... }
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:
- 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 memublikasikan Add-on Gmail atau Editor yang menggunakan satu atau beberapa cakupan yang dibatasi, add-on tersebut harus mematuhi semua pembatasan yang ditentukan sebelum dapat dipublikasikan.
Tinjau daftar lengkap cakupan yang dibatasi sebelum Anda mencoba memublikasikannya. Jika add-on Anda menggunakan salah satunya, Anda harus mematuhi Persyaratan tambahan untuk cakupan API tertentu sebelum memublikasikannya.
Memilih cakupan untuk Add-on Google Workspace
Bagian berikut memberikan cakupan yang biasa 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.
Cakupan | |
---|---|
Akses file Dokumen saat ini |
https://www.googleapis.com/auth/documents.currentonly
Wajib jika add-on mengakses Docs API Apps Script. Memberikan akses sementara ke konten dokumen yang terbuka. |
Akses file Spreadsheet saat ini |
https://www.googleapis.com/auth/spreadsheets.currentonly
Wajib jika add-on mengakses Sheets API Apps Script. Memberikan akses sementara ke konten spreadsheet yang terbuka. |
Akses file Slide Saat Ini |
https://www.googleapis.com/auth/presentations.currentonly
Wajib jika add-on mengakses Slides API Apps Script. Memberikan akses sementara ke konten presentasi terbuka. |
Akses per file |
https://www.googleapis.com/auth/drive.file
Diperlukan agar add-on dapat menggunakan |
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 add-on Anda dengan kumpulan cakupan yang lebih sempit yang memungkinkan interaksi yang diperlukan add-on Anda dan tidak lebih.
Cakupan | |
---|---|
Membuat draf baru |
https://www.googleapis.com/auth/gmail.addons.current.action.compose
Wajib jika add-on menggunakan pemicu tindakan compose. Memungkinkan add-on membuat pesan draf dan balasan baru untuk sementara. 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 isi pesan dan memerlukan token akses. Wajib ada jika add-on menggunakan metadata dalam pemicu tindakan Compose. Untuk tindakan compose, cakupan ini diperlukan jika pemicu compose memerlukan akses ke metadata. Dalam praktiknya, cakupan ini memungkinkan pemicu compose mengakses daftar penerima (to:, 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 rangkaian pesan terbuka. Memerlukan token akses. |
Membaca konten dan metadata pesan apa pun |
https://www.googleapis.com/auth/gmail.readonly
Membaca semua metadata dan konten email, termasuk pesan yang terbuka. Diperlukan jika Anda perlu membaca informasi tentang pesan lain, seperti saat melakukan kueri penelusuran atau membaca seluruh rangkaian pesan email. |
Cakupan Google 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 |
Menulis data peristiwa buatan 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 Google 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 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 Advanced Drive Service Apps Script. 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. |
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 setelan 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. Pada umumnya, Anda dapat mengizinkan Apps Script mendeteksi cakupan ini dan mengupdate 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:
Cakupan | |
---|---|
Membaca alamat email pengguna |
https://www.googleapis.com/auth/userinfo.email
Mengizinkan project untuk membaca alamat email pengguna saat ini. |
Mengizinkan panggilan ke layanan eksternal |
https://www.googleapis.com/auth/script.external_request
Mengizinkan project untuk membuat permintaan |
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
Mengizinkan project untuk membuat pemicu. |
Melihat 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 diisi jika add-on membuat resource di layanan pihak ketiga. Memungkinkan project membaca informasi yang dikirimkan pengguna ke formulir pembuatan resource dan menyisipkan link ke resource dalam aplikasi Google Workspace. Untuk mempelajari lebih lanjut, lihat Membuat resource pihak ketiga dari menu @. |