Otorisasi untuk Layanan Google

Google Apps Script memerlukan otorisasi pengguna untuk mengakses data pribadi dari layanan Google bawaan atau layanan Google lanjutan.

Cara kerja otorisasi untuk Layanan Google

Jika memerlukan akses ke layanan Google, skrip akan mengikuti proses umum berikut:

  1. Deteksi: Apps Script memindai skrip untuk mengidentifikasi layanan yang digunakan (misalnya, SpreadsheetApp atau GmailApp).
  2. Penentuan cakupan: Berdasarkan hasil pemindaian, Apps Script mengidentifikasi kumpulan cakupan OAuth yang diperlukan agar skrip dapat berjalan.
  3. Pemeriksaan otorisasi: Saat skrip dijalankan, skrip akan memeriksa apakah pengguna telah mengotorisasi cakupan tersebut.
  4. Perintah pengguna: Jika otorisasi tidak ada, dialog akan muncul dan meminta pengguna untuk memberikan izin.
  5. Eksekusi: Setelah diotorisasi, skrip dapat mengakses data yang diminta untuk pengguna tersebut.

Izin dan jenis skrip

Identitas pengguna yang digunakan skrip untuk berjalan — dan dengan demikian data yang dapat diakses — bervariasi berdasarkan skenario tempat skrip dijalankan, seperti yang ditunjukkan dalam tabel berikut.

Jenis skrip Skrip berjalan sebagai...
Mandiri, add-on Google Workspace, atau terikat ke Google Dokumen, Google Spreadsheet, Google Slide, atau Google Formulir Pengguna di keyboard
Fungsi kustom di spreadsheet Pengguna anonim; namun, batas kuota dihitung terhadap pengguna di keyboard
Aplikasi web atau gadget Google Sites Pengguna di keyboard atau pemilik skrip, bergantung pada opsi yang dipilih saat men-deploy aplikasi
Pemicu yang dapat diinstal Pengguna yang membuat pemicu

Memberikan hak akses

Apps Script menentukan cakupan otorisasi (seperti akses ke file Spreadsheet atau Gmail Anda) secara otomatis, berdasarkan pemindaian kode. Kode yang diberi komentar masih dapat menghasilkan permintaan otorisasi. Jika memerlukan otorisasi, dialog otorisasi akan muncul saat skrip dijalankan.

Skrip yang sebelumnya telah Anda otorisasi juga akan meminta otorisasi tambahan jika perubahan kode menambahkan layanan baru. Skrip mungkin tidak meminta otorisasi jika Anda mengakses skrip sebagai aplikasi web yang berjalan di bawah identitas pengguna pemilik skrip.

Mencabut hak akses

Untuk mencabut akses skrip ke data Anda, ikuti langkah-langkah berikut:

  1. Buka bagian Keamanan di Akun Google Anda.
  2. Di bagian Koneksi Anda ke aplikasi &layanan pihak ketiga, klik Lihat semua koneksi.
  3. Pilih skrip atau aplikasi yang ingin Anda cabut aksesnya.
  4. Klik Hapus semua koneksi yang Anda miliki dengan APP_NAME, lalu klik Konfirmasi.

Membatasi cakupan ke dokumen saat ini

Jika Anda membuat add-on atau skrip lain yang menggunakan layanan Spreadsheet, layanan Dokumen, layanan Slide, atau layanan Formulir, Anda dapat memaksa dialog otorisasi untuk hanya meminta akses ke file tempat add-on atau skrip digunakan, bukan semua spreadsheet, dokumen, atau formulir pengguna. Untuk melakukannya, sertakan anotasi JSDoc berikut dalam komentar tingkat file:

/**
 * @OnlyCurrentDoc
 */

Anotasi yang berlawanan, @NotOnlyCurrentDoc, tersedia jika skrip Anda menyertakan library yang mendeklarasikan @OnlyCurrentDoc, tetapi skrip utama sebenarnya memerlukan akses ke lebih dari file saat ini.

Siklus proses otorisasi untuk add-on

Add-on untuk Spreadsheet, Dokumen, Slide, dan Formulir umumnya mengikuti model otorisasi yang sama dengan skrip yang terikat ke dokumen. Namun, dalam keadaan tertentu, fungsi onOpen(e) dan onEdit(e)-nya berjalan dalam mode tanpa otorisasi yang menimbulkan beberapa komplikasi tambahan. Untuk mengetahui informasi selengkapnya, lihat panduan siklus proses otorisasi add-on.

Batas pengguna aplikasi OAuth

Aplikasi yang menggunakan OAuth untuk mengakses data pengguna Google, termasuk project Apps Script, tunduk pada batas otorisasi. Lihat Batas pengguna aplikasi OAuth untuk mengetahui detailnya.

Perilaku autentikasi ulang dengan Apps Script

Apps Script tidak menerapkan frekuensi autentikasi ulang yang dikonfigurasi dalam setelan layanan Google Cloud. Hal ini karena Apps Script dapat berjalan secara otomatis menggunakan pemicu, yang beroperasi tanpa interaksi pengguna langsung. Eksekusi otomatis ini tidak memicu perintah autentikasi ulang. Aplikasi Apps Script tidak otomatis meminta Anda untuk melakukan autentikasi ulang setelah jangka waktu yang ditentukan (misalnya, 12 jam).

Menetapkan cakupan eksplisit dalam manifes

Apps Script otomatis menentukan cakupan yang diperlukan dengan memindai kode untuk panggilan fungsi. Jika memerlukan kontrol yang lebih besar, Anda dapat menetapkan cakupan secara eksplisit dalam manifes project (appsscript.json). Hal ini direkomendasikan untuk skrip yang dipublikasikan guna memastikan bahwa Anda menggunakan izin minimum yang diperlukan.

Untuk mengetahui petunjuknya, lihat Menetapkan cakupan eksplisit.

Pemecahan masalah

  • Error"Authorization required" saat menjalankan pemicu: Pemicu harus diotorisasi oleh pengguna yang membuatnya. Jika Anda menambahkan kode yang memerlukan izin baru, Anda harus menjalankan fungsi secara manual di editor skrip satu kali untuk memicu dialog otorisasi.
  • Cakupan tidak diperbarui: Jika Anda telah memperbarui kode, tetapi dialog otorisasi tidak mencerminkan perubahan tersebut, coba simpan project dan muat ulang editor. Jika Anda menggunakan cakupan eksplisit dalam manifes, pastikan Anda telah menambahkan cakupan baru ke array oauthScopes.
  • "This app is blocked" atau peringatan aplikasi yang tidak diverifikasi: Hal ini terjadi jika skrip Anda menggunakan cakupan sensitif atau terbatas dan belum diverifikasi oleh Google. Lihat Verifikasi klien OAuth.