Pilih cakupan Google Drive API

Dokumen ini berisi informasi otorisasi dan autentikasi khusus Google Drive API. Sebelum membaca dokumen ini, pastikan Anda membaca informasi autentikasi dan otorisasi umum Google Workspace diMempelajari autentikasi dan otorisasi.

Mengonfigurasi OAuth 2.0 untuk otorisasi

Untuk mengotorisasi aplikasi Anda, Google Drive API mengharuskan Anda menentukan cakupan OAuth di dua tempat: Konsol Google Cloud dan aplikasi Anda.

Di Konsol Google Cloud, Anda harus mendeklarasikan cakupan yang diperlukan aplikasi Anda dalam konfigurasi layar izin OAuth-nya. Ini adalah tingkat izin tertinggi yang dapat diminta aplikasi Anda. Hal ini berfungsi sebagai permintaan formal kepada Google, dan cakupan yang dideklarasikan adalah cakupan yang ditampilkan Google kepada pengguna di layar izin. Hal ini memungkinkan pengguna memahami dengan tepat data dan tindakan yang aksesnya diminta oleh aplikasi Anda.

Konfigurasi layar izin OAuth dan pilih cakupan untuk menentukan informasi yang ditampilkan kepada pengguna dan peninjau aplikasi, serta daftarkan aplikasi Anda agar dapat dipublikasikan nanti.

Di aplikasi Anda, saat memulai API, Anda harus secara eksplisit meminta cakupan tertentu yang Anda perlukan untuk sesi tersebut. Meskipun Konsol Google Cloud menentukan tingkat izin tertinggi yang diizinkan untuk diminta aplikasi Anda, kode menentukan izin sebenarnya untuk pengguna tertentu. Hal ini membantu memastikan aplikasi hanya meminta izin yang diperlukan untuk tugas tertentu.

Anda dapat mendeklarasikan satu atau beberapa cakupan OAuth sekaligus dalam kode aplikasi Anda sebagai array.

Contoh kode berikut menunjukkan cara mendeklarasikan beberapa cakupan OAuth:

Java

List<String> SCOPES = Arrays.asList(
  DriveScopes.DRIVE_FILE,
  DriveScopes.DRIVE_METADATA_READONLY
);

Python

SCOPES = [
  "https://www.googleapis.com/auth/drive.file",
  "https://www.googleapis.com/auth/drive.metadata.readonly",
]

Node.js

const SCOPES = [
  'https://www.googleapis.com/auth/drive.file',
  'https://www.googleapis.com/auth/drive.metadata.readonly'
];

Untuk melihat cara cakupan dideklarasikan dan digunakan dalam contoh kode lengkap, lihat Panduan memulai.

Cakupan Drive API

Untuk menentukan tingkat akses yang diberikan ke aplikasi Anda, Anda harus mengidentifikasi dan mendeklarasikan cakupan otorisasi. Cakupan otorisasi adalah string URI OAuth 2.0 yang berisi nama aplikasi Google Workspace, jenis data yang diakses, dan tingkat akses. Cakupan adalah permintaan aplikasi Anda untuk menggunakan data Google Workspace, termasuk data Akun Google pengguna.

Saat aplikasi Anda diinstal, pengguna akan diminta untuk memvalidasi cakupan yang digunakan oleh aplikasi. Umumnya, Anda harus memilih cakupan yang paling sempit dan menghindari permintaan cakupan yang tidak diperlukan aplikasi Anda. Pengguna lebih mudah memberikan akses ke cakupan terbatas yang dijelaskan dengan jelas.

Jika memungkinkan, gunakan cakupan tidak sensitif karena cakupan tersebut memberikan akses per file dan mempersempit akses ke fitur tertentu yang diperlukan oleh aplikasi.

Cakupan tidak sensitif

Cakupan Drive API berikut direkomendasikan untuk sebagian besar kasus penggunaan:

Kode cakupan	Deskripsi
`https://www.googleapis.com/auth/drive.appdata https://www.googleapis.com/auth/drive.appfolder`	Melihat dan mengelola data konfigurasi aplikasi sendiri di Google Drive Anda.
`https://www.googleapis.com/auth/drive.install`	Mengizinkan aplikasi muncul sebagai opsi di menu "Buka dengan" atau "Baru".
`https://www.googleapis.com/auth/drive.file`	Membuat file Drive baru, atau mengubah file yang ada, yang Anda buka dengan aplikasi atau yang dibagikan pengguna ke aplikasi saat menggunakan Google Picker API atau pemilih file aplikasi.

Cakupan sensitif

Kode cakupan	Deskripsi
`https://www.googleapis.com/auth/drive.apps.readonly`	Melihat aplikasi yang diizinkan untuk mengakses Drive Anda.

Cakupan yang dibatasi

Kode cakupan	Deskripsi
`https://www.googleapis.com/auth/drive`	Melihat dan mengelola semua file Drive Anda.
`https://www.googleapis.com/auth/drive.readonly`	Melihat dan mendownload semua file Drive Anda.
`https://www.googleapis.com/auth/drive.activity`	Melihat dan menambahkan ke catatan aktivitas file di Drive Anda.
`https://www.googleapis.com/auth/drive.activity.readonly`	Melihat catatan aktivitas file di Drive Anda.
`https://www.googleapis.com/auth/drive.meet.readonly`	Melihat file Drive yang dibuat atau diedit oleh Google Meet.
`https://www.googleapis.com/auth/drive.metadata`	Melihat dan mengelola metadata file di Drive Anda.
`https://www.googleapis.com/auth/drive.metadata.readonly`	Melihat metadata file di Drive Anda.
`https://www.googleapis.com/auth/drive.scripts`	Mengubah perilaku skrip Google Apps Script Anda.

Cakupan dalam tabel sebelumnya menunjukkan sensitivitasnya, menurut definisi berikut:

Tidak sensitif: Cakupan ini memberikan cakupan otorisasi terkecil dan hanya memerlukan Aplikasi OAuth Verifikasi dasar. Untuk mengetahui informasi selengkapnya, lihat Persyaratan verifikasi.
Sensitif: Cakupan ini memberikan akses ke data pengguna Google tertentu yang diizinkan pengguna untuk aplikasi Anda. Cakupan ini memerlukan Verifikasi Aplikasi OAuth tambahan. Untuk mengetahui informasi selengkapnya, lihat Persyaratan Cakupan Sensitif dan Dibatasi.
Dibatasi: Cakupan ini memberikan akses luas ke data pengguna Google dan memerlukan Verifikasi Aplikasi OAuth cakupan yang dibatasi. Untuk mengetahui informasi selengkapnya, lihat Kebijakan Data Pengguna Layanan Google API dan Persyaratan Tambahan untuk Cakupan API Tertentu. Lihat juga Persyaratan Layanan Google Drive.

Jika Anda menyimpan data cakupan yang dibatasi di server (atau mengirimkannya), Anda harus menjalani penilaian keamanan.

Jika aplikasi Anda memerlukan akses ke Google API lainnya, Anda juga dapat menambahkan cakupan tersebut. Untuk mengetahui informasi selengkapnya tentang cakupan Google API, lihat Menggunakan OAuth 2.0 untuk Mengakses Google API.

Untuk mengetahui informasi selengkapnya tentang cakupan OAuth 2.0 tertentu, lihat Cakupan OAuth 2.0 untuk Google API.

Kualifikasi untuk cakupan yang dibatasi

Hanya jenis aplikasi tertentu yang diizinkan menggunakan cakupan yang dibatasi untuk Google Drive. Agar memenuhi syarat, aplikasi Anda harus termasuk dalam salah satu kategori berikut:

Pencadangan dan sinkronisasi: Aplikasi khusus platform dan web yang menyediakan sinkronisasi lokal atau pencadangan otomatis file Drive pengguna.
Produktivitas dan pendidikan: Aplikasi dengan antarmuka pengguna utama yang mungkin melibatkan interaksi dengan file, metadata, atau izin Drive. Aplikasi ini mencakup aplikasi pengelolaan tugas, pencatatan, komunikasi grup kerja, dan kolaborasi kelas.
Pelaporan dan keamanan: Aplikasi yang memberikan insight pengguna atau pelanggan tentang cara file dibagikan atau diakses.

Untuk terus menggunakan cakupan yang dibatasi, Anda harus menyiapkan aplikasi untuk verifikasi cakupan yang dibatasi.

Memigrasikan aplikasi yang ada dari cakupan yang dibatasi

Jika aplikasi Drive Anda menggunakan cakupan yang dibatasi, sebaiknya migrasikan ke cakupan Drive API yang tidak sensitif. Menggunakan cakupan yang tidak sensitif, seperti drive.file, memberikan akses per file dan mempersempit akses ke fitur tertentu yang diperlukan oleh aplikasi.

Banyak aplikasi dapat beralih ke akses per file tanpa perubahan apa pun.

Jika Anda menggunakan pemilih file sendiri, sebaiknya beralihlah ke Google Picker API yang sepenuhnya mendukung cakupan yang berbeda.

Manfaat cakupan file Drive

Menggunakan cakupan OAuth drive.file bersama dengan Google Picker API mengoptimalkan pengalaman dan keamanan pengguna untuk aplikasi Anda.

Cakupan OAuth drive.file memungkinkan pengguna memilih file yang ingin mereka bagikan ke aplikasi Anda. Hal ini memberi mereka lebih banyak kontrol dan keyakinan bahwa akses aplikasi Anda ke file mereka terbatas dan lebih aman. Sebaliknya, mewajibkan akses luas ke semua file Drive dapat membuat pengguna enggan berinteraksi dengan aplikasi Anda.

Berikut beberapa alasan mengapa Anda harus menggunakan cakupan drive.file:

Kegunaan: Cakupan drive.file berfungsi dengan semua Drive API Resource REST yang berarti Anda dapat menggunakannya dengan cara yang sama seperti saat menggunakan cakupan OAuth yang lebih luas.
Fitur: Google Picker API menyediakan antarmuka yang mirip dengan UI Drive. Hal ini mencakup beberapa tampilan yang menampilkan pratinjau dan thumbnail file Drive, serta jendela modal inline sehingga pengguna tidak pernah keluar dari aplikasi utama.
Kenyamanan: Aplikasi dapat menerapkan filter untuk jenis file Drive tertentu (seperti Google Dokumen, Spreadsheet, dan foto) saat menggunakan filter pada file Google Picker.
Verifikasi yang mudah: Karena drive.file tidak sensitif, ini memungkinkan proses verifikasi yang lebih efisien.

Menyimpan token refresh dengan aman

Untuk mengakses data pribadi menggunakan Drive API, aplikasi Anda harus mendapatkan token akses yang memberikan akses ke API tersebut. Satu token akses dapat memberikan berbagai tingkat akses ke beberapa API, yang diatur oleh cakupan yang Anda minta.

Karena token akses memiliki masa berlaku singkat, Anda harus menggunakan token refresh untuk akses jangka panjang ke Drive API. Token refresh memungkinkan aplikasi Anda meminta token akses baru.

Simpan token refresh di penyimpanan jangka panjang yang aman dan terus gunakan selama token tersebut tetap valid.

Untuk mengetahui informasi selengkapnya, lihat Menggunakan OAuth 2.0 untuk Mengakses Google API.

Untuk ringkasan autentikasi dan otorisasi di Google Workspace, lihat Mempelajari autentikasi & otorisasi.
Untuk ringkasan autentikasi dan otorisasi di Google Cloud, lihat Ringkasan autentikasi.
Untuk mempelajari akun layanan lebih lanjut, lihat Akun layanan.
Untuk mendapatkan bantuan terkait pemecahan masalah, lihat Mengatasi error.