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

Saat 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 pemindaian, Apps Script mengidentifikasi serangkaian cakupan OAuth yang diperlukan agar skrip dapat berjalan.
  3. Pemeriksaan otorisasi: Saat skrip dijalankan, skrip akan memeriksa apakah pengguna telah mengizinkan cakupan tersebut.
  4. Perintah pengguna: Jika otorisasi tidak ada, dialog akan muncul untuk meminta pengguna memberikan izin.
  5. Eksekusi: Setelah skrip diberi otorisasi, skrip dapat mengakses data yang diminta untuk pengguna tersebut.

Izin dan jenis skrip

Identitas pengguna yang menjalankan skrip — dan dengan demikian data yang dapat diaksesnya — berbeda-beda berdasarkan skenario saat 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 dalam 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 dikomentari masih dapat membuat permintaan otorisasi. Jika skrip memerlukan otorisasi, dialog otorisasi akan muncul saat skrip dijalankan.

Skrip yang sebelumnya telah Anda beri otorisasi juga 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 aksesnya ingin Anda cabut.
  4. Klik Hapus semua koneksi Anda 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) mereka 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 di 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 prompt autentikasi ulang. Aplikasi Apps Script Anda tidak secara otomatis meminta Anda melakukan autentikasi ulang setelah jangka waktu yang ditentukan (misalnya, 12 jam).

Menetapkan cakupan eksplisit dalam manifes

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

Untuk mengetahui petunjuknya, lihat Menetapkan cakupan eksplisit.

Pemecahan masalah

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