Teropong senjata api

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

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

Selama alur ini, perintah tersebut memberi tahu pengguna tindakan yang perlu dilakukan aplikasi. Misalnya, add-on mungkin meminta izin untuk membaca pesan email pengguna atau membuat acara di kalendernya. Project skrip add-on menentukan izin individu 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 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 saat add-on dijalankan.

Melihat cakupan

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

Editor baru

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

Editor lama

  1. Buka project skrip di editor Apps Script.
  2. Di menu, pilih File > Properti project.
  3. Pilih tab Cakupan.

Cakupan dicantumkan di bagian bawah jendela di bawah judul Project OAuth Scopes.

Anda juga dapat melihat cakupan project skrip saat ini di 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 mengetahui panggilan fungsi yang memerlukannya. Untuk sebagian besar skrip, hal ini cukup dan menghemat waktu Anda, tetapi untuk add-on yang dipublikasikan, Anda harus menjalankan kontrol langsung pada cakupan.

Misalnya, Apps Script dapat memberikan cakupan yang sangat permisif ke project skrip add-on https://mail.google.com secara default. Saat pengguna mengizinkan project skrip dengan cakupan ini, project tersebut 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 lagi.

Anda dapat secara eksplisit menyetel cakupan yang digunakan project skrip dengan mengedit file manifes. Kolom manifes oauthScopes adalah array semua cakupan yang digunakan oleh add-on. Untuk menyetel cakupan project, lakukan langkah berikut:

  1. Lihat cakupan yang saat ini digunakan add-on. Tentukan perubahan apa yang perlu dilakukan, seperti menggunakan cakupan yang lebih sempit.
  2. Buka file manifes add-on.
  3. Temukan kolom tingkat atas 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

Untuk menggunakan cakupan OAuth sensitif tertentu, add-on harus menjalani 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 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 mencoba memublikasikannya. 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 buatan pengguna. Mengizinkan add-on mengakses data peristiwa buatan 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 harus menulis data peristiwa buatan pengguna. Mengizinkan add-on untuk mengedit data peristiwa buatan pengguna. Data ini hanya tersedia jika kolom manifes addOns.calendar.eventAccess disetel 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 jika add-on mengimplementasikan antarmuka kontekstual yang dipicu saat pengguna memilih item di Drive. Mengizinkan add-on untuk membaca metadata terbatas tentang item yang telah dipilih pengguna di Google Drive. Metadata dibatasi pada ID, judul, jenis MIME, URL 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 file Drive individual. Memberikan akses per file ke file yang dibuat atau dibuka oleh aplikasi, menggunakan Layanan Drive Lanjutan Apps Script. Namun, hal ini tidak memungkinkan penggunaan tindakan serupa menggunakan layanan Drive dasar. Otorisasi file diberikan per file dan dicabut saat pengguna membatalkan otorisasi aplikasi.

Lihat Contoh akses file untuk file tertentu yang dipilih.

Cakupan add-on 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 yang lainnya yang diperlukan oleh kode add-on Anda.

Berikut adalah cakupan yang sering digunakan untuk Add-on Google Workspace yang memperluas Gmail; yang diberi label 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 dengan kumpulan cakupan yang lebih sempit, yang memungkinkan interaksi yang diperlukan add-on Anda dan tidak lebih dari itu.

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

Wajib ada jika add-on menggunakan pemicu tindakan compose. Mengizinkan add-on untuk membuat pesan draf dan balasan baru untuk sementara. Lihat Menulis pesan draf untuk detailnya; cakupan ini juga sering digunakan dengan tindakan tulis. Memerlukan token akses.

Membaca metadata pesan 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 pemicu tindakan tulis. Untuk tindakan compose, cakupan ini diperlukan jika pemicu compose memerlukan akses ke metadata. Dalam praktiknya, cakupan ini memungkinkan Compose memicu daftar penerima akses (ke:, cc:, dan bcc:) draf email balasan.

Baca konten pesan 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 token akses.

Baca 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 dalam thread terbuka. Memerlukan token akses.

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

Membaca metadata dan konten email apa pun, termasuk pesan terbuka. Wajib jika Anda perlu membaca informasi tentang pesan lainnya, seperti saat melakukan kueri penelusuran atau membaca seluruh rangkaian pesan.

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

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

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

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

Akses file Slide saat ini https://www.googleapis.com/auth/presentations.currentonly

Wajib 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

Diperlukan add-on untuk menggunakan onFileScopeGrantedTrigger dan jika add-on mengakses API REST, Dokumen, Spreadsheet, Slide, atau Drive. Memberikan akses per file ke file yang dibuat atau dibuka oleh aplikasi, menggunakan Layanan Drive Lanjutan Apps Script. Namun, hal ini tidak memungkinkan penggunaan tindakan serupa menggunakan layanan Drive dasar. Otorisasi file diberikan per file dan dicabut saat pengguna membatalkan otorisasi aplikasi.

Cakupan lainnya

Add-on Anda mungkin memerlukan cakupan tambahan jika menggunakan layanan Apps Script lain. Dalam sebagian besar kasus, Anda dapat mengizinkan Apps Script mendeteksi cakupan ini dan mengupdate manifes secara otomatis. Saat mengedit daftar cakupan manifes, jangan hapus cakupan mana 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 bersama dengan Add-on Google Workspace:

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

Mengizinkan project membaca alamat email pengguna saat ini.

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

Mengizinkan project membuat permintaan UrlFetch. Hal ini juga diperlukan jika project menggunakan library OAuth2 for Apps Script.

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

Izinkan project mempelajari lokal dan zona waktu pengguna saat ini. Lihat Mengakses lokal dan zona waktu pengguna untuk mengetahui detailnya.

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

Mengizinkan project untuk membuat pemicu.