Halaman ini diterjemahkan oleh Cloud Translation API.

Cross-Origin Resource Sharing (CORS)

Kebijakan origin yang sama adalah kebijakan keamanan yang diterapkan pada aplikasi web sisi klien (seperti browser web) untuk mencegah interaksi antara resource dari origin yang berbeda. Meskipun berguna untuk mencegah perilaku berbahaya, langkah keamanan ini juga mencegah interaksi yang sah antara origin yang diketahui. Misalnya, skrip pada halaman yang dihosting di example.appspot.com mungkin perlu menggunakan resource yang disimpan dalam bucket Cloud Storage di example.storage.googleapis.com. Namun, karena ini adalah dua origin yang berbeda dari perspektif browser, browser tidak akan mengizinkan skrip dari example.appspot.com untuk mengambil resource dari example.storage.googleapis.com.

Spesifikasi Cross Origin Resource Sharing (CORS) dikembangkan oleh World Wide Web Consortium (W3C) untuk mengatasi batasan ini. Cloud Storage mendukung spesifikasi ini dengan memungkinkan Anda mengonfigurasi bucket untuk mendukung CORS. Melanjutkan contoh sebelumnya, Anda dapat mengonfigurasi bucket example.storage.googleapis.com sehingga browser dapat membagikan resource-nya dengan skrip dari example.appspot.com.

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

Cara kerja CORS

Ada dua jenis permintaan CORS: sederhana dan preflight. Permintaan sederhana dapat dimulai secara langsung. Permintaan preflight harus mengirimkan permintaan "preflight" awal ke server untuk mendapatkan izin sebelum permintaan utama dapat dilanjutkan. 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.

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.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 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 HTTP dan header 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.

Ini adalah deskripsi sederhana tentang CORS. Untuk deskripsi yang lebih lengkap, baca spesifikasi Fetch.

Dukungan CORS Cloud Storage

Dengan Cloud Storage, Anda dapat menetapkan konfigurasi CORS hanya pada level bucket. Anda dapat menyiapkan konfigurasi CORS untuk bucket menggunakan berbagai alat; tetapi, endpoint Cloud Storage yang berbeda menangani permintaan CORS dengan cara yang berbeda:

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. Perlu diperhatikan 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 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 menggunakan elemen terpisah. Contoh:
```
<Methods>
  <Method>PUT</Method>
  <Method>GET</Method>
</Methods>
```
Untuk mengizinkan permintaan dibuat dari origin mana pun, tetapkan origin ke *. Misalnya, "origin": ["*"] di JSON API atau <Origin>*</Origin> di XML API. Meskipun origin ini berguna untuk menguji konfigurasi, dalam sebagian besar kasus, Anda sebaiknya membatasi origin permintaan untuk mencegah penggunaan resource yang tidak diinginkan.

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.