Halaman ini diterjemahkan oleh Cloud Translation API.

Cross-Origin Resource Sharing (CORS)

Cross-Origin Resource Sharing (CORS) memungkinkan aplikasi web sisi klien mengakses resource dari origin yang berbeda. Cloud Storage mendukung spesifikasi CORS, sehingga Anda dapat mengonfigurasi bucket untuk membagikan resource secara aman dengan skrip dari origin lain. Misalnya, Anda dapat menggunakan CORS untuk mengizinkan aplikasi web https://example-app.appspot.com Anda mengakses resource di origin https://example-data.storage.googleapis.com.

Untuk mengetahui informasi lebih lanjut mengenai komponen konfigurasi CORS, lihat Menetapkan Bucket CORS.

Cara kerja CORS

Gunakan CORS jika Anda ingin situs Anda mengambil file, gambar, atau skrip secara langsung dari bucket Cloud Storage menggunakan permintaan berbasis browser.

Mengizinkan akses di seluruh domain

Secara default, browser web menerapkan langkah keamanan yang disebut kebijakan origin yang sama. Kebijakan origin yang sama mencegah skrip di satu situs berinteraksi dengan resource di domain lain. Meskipun melindungi pengguna dari situs berbahaya, fitur ini juga memblokir permintaan yang sah. Misalnya, jika aplikasi web https://example-app.appspot.com Anda mencoba mengakses resource di origin https://example-data.storage.googleapis.com, browser akan memblokir permintaan secara default karena domain tidak cocok.

Spesifikasi CORS menyediakan cara bagi server untuk memberi tahu browser, "Saya memercayai domain tertentu ini, jadi lanjutkan dan izinkan permintaan."

Dengan Cloud Storage, Anda dapat menetapkan konfigurasi CORS di bucket Anda. Jika dikonfigurasi, Cloud Storage akan mengirimkan header HTTP tertentu kembali ke browser (seperti Access-Control-Allow-Origin) yang mengizinkan browser untuk membagikan resource bucket dengan aplikasi web Anda.

Jenis permintaan

Permintaan CORS beroperasi dalam dua cara: sederhana dan preflight. Permintaan sederhana diproses secara langsung, sementara permintaan preflight pertama-tama mengirimkan permintaan awal untuk mendapatkan izin.

Permintaan sederhana

Proses berikut terjadi saat browser membuat permintaan sederhana ke Cloud Storage:

Browser menambahkan header Origin ke permintaan. Header Origin berisi asal resource yang ingin berbagi resource bucket Cloud Storage, misalnya, Origin:https://www.example-app.appspot.com.
Cloud Storage membandingkan metode HTTP permintaan dan nilai header Origin dengan informasi Metode dan Origin di konfigurasi CORS bucket target untuk melihat apakah ada kecocokan. Jika ada, Cloud Storage akan menyertakan header Access-Control-Allow-Origin dalam responsnya. Header Access-Control-Allow-Origin berisi nilai header Origin dari permintaan awal.
Browser akan menerima respons dan memeriksa apakah nilai Access-Control-Allow-Origin cocok dengan domain yang ditentukan dalam permintaan asli. Jika cocok, permintaan akan berhasil. Jika tidak cocok, atau jika header Access-Control-Allow-Origin tidak ada dalam respons, permintaan akan gagal.

Permintaan pra-penerbangan

Permintaan akan dijalankan sebelumnya jika salah satu keadaan berikut terpenuhi:

Menggunakan metode selain GET, HEAD, atau POST.
Menggunakan metode POST dengan Content-Type selain text/plain, application/x-www-form-urlencoded, atau multipart/form-data.
Menetapkan header kustom. Misalnya, X-PINGOTHER.

Permintaan yang di-preflight melakukan langkah-langkah berikut terlebih dahulu. Jika berhasil, permintaan tersebut akan mengikuti proses yang sama dengan permintaan sederhana:

Browser akan mengirimkan permintaan OPTIONS yang berisi Requested Method dan Requested Headers dari permintaan utama.
Cloud Storage merespons kembali dengan nilai metode dan header HTTP yang diizinkan oleh resource yang ditargetkan. Jika salah satu nilai metode atau header dalam permintaan preflight tidak berada dalam kumpulan metode dan header yang diizinkan oleh resource yang ditargetkan, permintaan akan gagal, dan permintaan utama tidak akan dikirim.

Untuk deskripsi permintaan CORS yang lebih lengkap, baca spesifikasi Fetch.

Dukungan CORS Cloud Storage

Dengan Cloud Storage, Anda dapat menetapkan konfigurasi CORS di tingkat bucket. Endpoint JSON API dan XML API menangani permintaan CORS dan menampilkan header respons secara berbeda. Pahami perilaku ini untuk mengonfigurasi bucket Anda secara efektif:

Endpoint JSON API selalu mengizinkan permintaan CORS dan menampilkan nilai default di header respons CORS, terlepas dari konfigurasi yang ditetapkan pada bucket.
Endpoint XML API hanya mengizinkan permintaan CORS berdasarkan konfigurasi pada bucket dan menampilkan nilai header CORS tertentu sebagai respons terhadap konfigurasi tersebut.
Endpoint download browser terautentikasi storage.cloud.google.com tidak mengizinkan permintaan CORS. Perhatikan bahwa konsol Google Cloud menyediakan endpoint ini untuk link URL publik setiap objek.

Anda dapat menggunakan salah satu URL permintaan API XML berikut untuk mendapatkan respons dari Cloud Storage yang berisi header CORS:

storage.googleapis.com/BUCKET_NAME

BUCKET_NAME.storage.googleapis.com

Untuk mengetahui informasi tentang URL permintaan API XML, lihat Meminta Endpoint.

Komponen konfigurasi CORS

Saat menggunakan XML API, nilai yang Anda tetapkan pada konfigurasi CORS bucket akan menentukan header CORS yang ditampilkan Cloud Storage dalam respons HTTP. Saat menggunakan JSON API, Cloud Storage tidak mengevaluasi konfigurasi bucket Anda dan menampilkan nilai header default.

Tabel berikut menjelaskan kolom dalam konfigurasi CORS dan perilaku respons XML API dan JSON API. Untuk mempelajari penggunaan kolom ini, lihat contoh konfigurasi CORS.

Kolom¹	Deskripsi	Perilaku respons XML API	Perilaku respons JSON API
`origin`	Tentukan origin yang ingin Anda izinkan untuk Cross-Origin Resource Sharing (CORS) dengan bucket Cloud Storage ini. Misalnya, `https://origin1.example.com`.	Jika origin dalam permintaan browser cocok dengan origin dalam konfigurasi CORS Anda, Cloud Storage akan menampilkan `Access-Control-Allow-Origin` ke browser. Jika tidak ada kecocokan, Cloud Storage tidak akan menyertakan `Access-Control-Allow-Origin` dalam respons. Anda dapat memberikan nilai pengganti yang memberikan akses ke semua origin: `<Origin>*</Origin>`.	Cloud Storage menampilkan header `Access-Control-Allow-Origin` yang ditetapkan ke asal permintaan.
`method`	Tentukan metode HTTP yang ingin Anda izinkan untuk berbagi resource lintas origin dengan bucket Cloud Storage ini. Nilai ditampilkan dalam header `Access-Control-Allow-Methods` sebagai respons terhadap permintaan preflight yang berhasil. Karena `OPTIONS` adalah metode standar yang digunakan browser untuk memulai permintaan preflight, Anda tidak boleh menentukan `OPTIONS` dalam konfigurasi CORS.	Cloud Storage mendukung metode berikut: `DELETE`, `GET`, `HEAD`, `POST`, `PUT`. Cloud Storage memeriksa metode yang dikirim dari browser di header `Access-Control-Request-Methods` terhadap konfigurasi CORS bucket. Jika tidak ada kecocokan, Cloud Storage akan menampilkan kode respons `200` tanpa header respons CORS.	Cloud Storage menampilkan header `Access-Control-Allow-Methods` yang ditetapkan ke metode berikut: `DELETE`, `GET`, `HEAD`, `PATCH`, `POST`, `PUT`.
`responseHeader`	Tentukan header yang ingin Anda izinkan untuk Cross-Origin Resource Sharing dengan bucket Cloud Storage ini. Nilai ditampilkan dalam header `Access-Control-Allow-Headers` sebagai respons terhadap permintaan preflight yang berhasil.	Untuk permintaan preflight, Cloud Storage akan memeriksa header yang dikirim dari browser di header `Access-Control-Request-Headers` terhadap konfigurasi CORS bucket. Jika tidak ada kecocokan, Cloud Storage tidak akan menampilkan header respons CORS.	Cloud Storage menampilkan header `Access-Control-Allow-Headers` yang ditetapkan setara dengan nilai yang ditentukan oleh header `Access-Control-Request-Headers`.
`maxAgeSeconds` (opsional)	Tentukan jumlah detik yang diizinkan bagi browser untuk membuat permintaan sebelum harus mengulangi permintaan preflight. Ini juga dikenal sebagai waktu berakhirnya cache. Nilai ini ditampilkan dalam header `Access-Control-Max-Age` sebagai respons terhadap permintaan preflight. Misalnya, `3600` menetapkan waktu berakhirnya cache ke 1 jam.	Cloud Storage menampilkan header `Access-Control-Max-Age` dengan waktu berakhir cache yang ditentukan. Jika Anda menghapus kolom ini, Cloud Storage akan menampilkan nilai default `3600`.	Cloud Storage menampilkan header `Access-Control-Max-Age` dengan nilai default `3600`.

¹ Nama yang didokumentasikan di bidang Kolom bersifat khusus untuk JSON API. Saat menggunakan XML API untuk menetapkan konfigurasi CORS, gunakan format khusus XML.

Menentukan beberapa origin, metode, atau header

Untuk mempelajari cara menetapkan beberapa origin, metode, atau header dalam konfigurasi CORS, lihat daftar berikut:

Saat menggunakan JSON API, Anda dapat menentukan beberapa origin, metode, atau header dengan menggunakan array yang dipisahkan koma. Misalnya, "method": ["GET", "PUT"].

Perhatian: Saat Anda menetapkan konfigurasi CORS menggunakan JSON API, permintaan dari semua origin akan diterima terlepas dari nilai kolom origin dalam konfigurasi CORS.
Saat menggunakan XML API, Anda dapat menentukan beberapa origin, metode, atau header dengan menggunakan elemen terpisah. Contoh:
```
<Methods>
  <Method>PUT</Method>
  <Method>GET</Method>
</Methods>
```
Untuk mengizinkan permintaan dibuat dari origin mana pun, tetapkan origin ke wildcard *. Misalnya, "origin": ["*"] di JSON API atau <Origin>*</Origin> di XML API. Meskipun asal ini berguna untuk menguji konfigurasi, dalam sebagian besar kasus, Anda sebaiknya membatasi asal permintaan untuk mencegah penggunaan yang tidak diinginkan atas resource Anda.

Pertimbangan lainnya

Tabel berikut menjelaskan pertimbangan saat membuat permintaan menggunakan kredensial atau header kontrol akses:

Properti atau header Deskripsi Perilaku respons XML API Perilaku respons JSON API

Kredensial

Cookie, header otorisasi, atau sertifikat klien TLS.

Properti atau header	Deskripsi	Perilaku respons XML API	Perilaku respons JSON API
Kredensial	Cookie, header otorisasi, atau sertifikat klien TLS.	Cloud Storage tidak pernah menampilkan header `Access-Control-Allow-Credentials`. Kredensial CORS tidak didukung oleh XML API.	Untuk permintaan sederhana, jika permintaan CORS disetujui, header `Access-Control-Allow-Credentials` akan ditetapkan ke true (benar). Untuk permintaan preflight, jika `Access-Control-Request-Method` kosong, Cloud Storage akan menetapkan `Access-Control-Allow-Credentials` ke true dan menolak permintaan dengan `404 - Not Found`.
Header yang terekspos	Untuk permintaan preflight, header permintaan `Access-Control-Request-Headers` menunjukkan header mana yang mungkin disertakan dalam permintaan CORS di masa mendatang. Header respons `Access-Control-Expose-Headers` disertakan dalam respons server dan menunjukkan kepada klien header mana yang dapat diekspos.	Untuk permintaan sederhana, `Access-Control-Expose-Headers` mencantumkan nilai header respons dalam konfigurasi CORS Anda.	Untuk permintaan sederhana, `Access-Control-Expose-Headers` menampilkan nilai yang ditentukan dalam `Access-Control-Request-Headers` jika nilai tersebut merupakan bagian dari daftar header HTTP umum.

Cloud Storage tidak pernah menampilkan header Access-Control-Allow-Credentials. Kredensial CORS tidak didukung oleh XML API.

Untuk permintaan sederhana, jika permintaan CORS disetujui, header Access-Control-Allow-Credentials akan ditetapkan ke true (benar).

Untuk permintaan preflight, jika Access-Control-Request-Method kosong, Cloud Storage akan menetapkan Access-Control-Allow-Credentials ke true dan menolak permintaan dengan 404 - Not Found.

Header yang terekspos Untuk permintaan preflight, header permintaan Access-Control-Request-Headers menunjukkan header mana yang mungkin disertakan dalam permintaan CORS di masa mendatang. Header respons Access-Control-Expose-Headers disertakan dalam respons server dan menunjukkan kepada klien header mana yang dapat diekspos. Untuk permintaan sederhana, Access-Control-Expose-Headers mencantumkan nilai header respons dalam konfigurasi CORS Anda. Untuk permintaan sederhana, Access-Control-Expose-Headers menampilkan nilai yang ditentukan dalam Access-Control-Request-Headers jika nilai tersebut merupakan bagian dari daftar header HTTP umum.

Mengizinkan bucket mengakses resource eksternal

Terkadang, Anda mungkin ingin mengizinkan skrip yang dihosting di Cloud Storage untuk mengakses resource statis yang dihosting di situs di luar Cloud Storage. Dalam skenario ini, situs menayangkan header CORS sehingga konten di storage.googleapis.com diizinkan untuk diakses.

Sebagai praktik terbaik, Anda harus mendedikasikan bucket tertentu untuk akses data ini. Pendekatan ini mencegah situs Anda mengekspos resource statis secara tidak sengaja ke semua storage.googleapis.com. Misalnya, jika Anda ingin mendedikasikan bucket bernama mybucket untuk akses data, Anda harus meminta situs menayangkan header CORS Access-Control-Allow-Origin: https://mybucket.storage.googleapis.com, bukan Access-Control-Allow-Origin: https://storage.googleapis.com.

Dukungan CORS sisi klien

Sebagian besar browser menggunakan objek XMLHttpRequest untuk membuat permintaan lintas-domain. XMLHttpRequest menangani semua tugas memasukkan header yang tepat dan menangani interaksi CORS dengan server. Anda tidak perlu menambahkan kode baru untuk memanfaatkan dukungan CORS pada bucket Cloud Storage.

Langkah berikutnya

Pelajari cara mengaktifkan CORS untuk bucket Anda.
Pelajari contoh konfigurasi CORS, termasuk contoh yang menghapus konfigurasi CORS pada bucket.
Pelajari cara memecahkan masalah permintaan CORS.