Kebijakan CORS

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

ikon kebijakan

Apa

Cross-origin resource sharing (CORS) adalah mekanisme standar yang memungkinkan panggilan XMLHttpRequest (XHR) JavaScript yang dijalankan di halaman web untuk berinteraksi dengan resource dari domain non-asal. CORS adalah solusi yang umum diterapkan untuk kebijakan origin yang sama yang diterapkan oleh semua browser.

Misalnya, jika Anda melakukan panggilan XHR ke Twitter API dari kode JavaScript yang dieksekusi di browser, panggilan akan gagal. Hal ini karena domain yang menayangkan halaman ke browser Anda tidak sama dengan domain yang menayangkan Twitter API. CORS memberikan solusi untuk masalah ini dengan mengizinkan server untuk ikut serta jika ingin menyediakan cross-origin resource sharing.

Kebijakan CORS ini memungkinkan pelanggan Apigee menetapkan kebijakan CORS untuk API yang digunakan oleh aplikasi web.

Kebijakan ini adalah Kebijakan standar dan dapat di-deploy ke jenis lingkungan apa pun. Untuk mengetahui informasi tentang jenis kebijakan dan ketersediaan dengan setiap jenis lingkungan, lihat Jenis kebijakan.

Elemen <CORS>

Menentukan kebijakan CORS.

Nilai Default Lihat tab Kebijakan Default, di bawah
Wajib? Wajib
Jenis Objek kompleks
Elemen Induk T/A
Elemen Turunan <AllowCredentials>
<AllowHeaders>
<AllowMethods>
<AllowOrigins>
<DisplayName>
<ExposeHeaders>
<GeneratePreflightResponse>
<IgnoreUnresolvedVariables>
<MaxAge>

Elemen <CORS> menggunakan sintaksis berikut:

Sintaks

Elemen <CORS> menggunakan sintaksis berikut:


<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <DisplayName>DISPLAY_NAME</DisplayName>
  <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins>
  <AllowMethods>[GET, PUT, POST, DELETE, ...|*]</AllowMethods>
  <AllowHeaders>[origin, x-requested-with, accept, content-type, ...]</AllowHeaders>
  <ExposeHeaders>[X-CUSTOM-HEADER-A, X-CUSTOM-HEADER-B, ... | *]</ExposeHeaders>
  <MaxAge>[integer|-1]</MaxAge>
  <AllowCredentials>[false|true]</AllowCredentials>
  <GeneratePreflightResponse>[false|true]</GeneratePreflightResponse>
  <IgnoreUnresolvedVariables>[false|true]</IgnoreUnresolvedVariables>
</CORS>

Kebijakan default

Contoh berikut menunjukkan setelan default saat Anda menambahkan kebijakan CORS ke flow di UI Edge:

<CORS continueOnError="false" enabled="true" name="add-cors">
    <DisplayName>Add CORS</DisplayName>
    <AllowOrigins>{request.header.origin}</AllowOrigins>
    <AllowMethods>GET, PUT, POST, DELETE</AllowMethods>
    <AllowHeaders>origin, x-requested-with, accept, content-type</AllowHeaders>
    <ExposeHeaders>*</ExposeHeaders>
    <MaxAge>3628800</MaxAge>
    <AllowCredentials>false</AllowCredentials>
    <GeneratePreflightResponse>true</GeneratePreflightResponse>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</CORS>

Saat Anda menyisipkan kebijakan CORS baru di UI Apigee, template akan berisi stub untuk semua kemungkinan operasi. Biasanya, Anda memilih operasi yang ingin dilakukan dengan kebijakan ini dan menghapus elemen turunan lainnya. Misalnya, jika Anda ingin menentukan metode HTTP yang diizinkan untuk mengakses resource, gunakan elemen <AllowMethods> dan hapus elemen turunan lainnya dari kebijakan agar lebih mudah dibaca.

Elemen ini memiliki atribut berikut yang umum untuk semua kebijakan:

Atribut Default Wajib? Deskripsi
name T/A Wajib

Nama internal kebijakan. Nilai atribut name dapat berisi huruf, angka, spasi, tanda hubung, garis bawah, dan titik. Nilai ini tidak boleh melebihi 255 karakter.

Secara opsional, gunakan elemen <DisplayName> untuk memberi label pada kebijakan di editor proxy UI pengelolaan dengan nama bahasa alami yang berbeda.

continueOnError false Opsional Tetapkan ke false untuk menampilkan error saat kebijakan gagal. Perilaku ini wajar terjadi untuk sebagian besar kebijakan. Tetapkan ke true agar eksekusi alur berlanjut meskipun setelah kebijakan gagal. Lihat juga:
enabled benar Opsional Tetapkan ke true untuk menerapkan kebijakan. Tetapkan ke false untuk menonaktifkan kebijakan. Kebijakan tidak akan diterapkan meskipun tetap terlampir ke alur.
async   false Tidak digunakan lagi Atribut ini tidak digunakan lagi.

Setiap elemen turunan dijelaskan di bagian berikut.

Contoh

Contoh disediakan untuk semua elemen turunan di bagian berikut.

Referensi elemen turunan

Bagian ini menjelaskan elemen turunan <CORS>.

<AllowCredentials>

Menunjukkan apakah pemanggil diizinkan untuk mengirim permintaan sebenarnya (bukan pra-penerbangan) menggunakan kredensial. Diterjemahkan ke header Access-Control-Allow-Credentials.

Nilai Default Jika tidak ditentukan, Access-Control-Allow-Credentials tidak akan ditetapkan.
Wajib? Opsional
Jenis Boolean
Elemen Induk <CORS>
Elemen Turunan Tidak ada

Elemen <AllowCredentials> menggunakan sintaksis berikut:

Sintaks

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins>
  <AllowCredentials>[false|true]</AllowCredentials>
</CORS>
      

Contoh

Contoh ini menetapkan header Access-Control-Allow-Credentials ke false. Artinya, pemanggil tidak diizinkan untuk mengirim permintaan sebenarnya (bukan pra-penerbangan) menggunakan kredensial.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <AllowCredentials>false</AllowCredentials>
</CORS>

<AllowHeaders>

Daftar header HTTP yang dapat digunakan saat meminta resource. Diserialisasi ke header Access-Control-Allow-Headers.

Nilai Default Origin, Accept, X-Requested-With, Content-Type, Access-Control-Request-Method, Access-Control-Request-Headers
Wajib? Opsional
Jenis String, dengan dukungan template pesan*
Elemen Induk <CORS>
Elemen Turunan Tidak ada

* Untuk informasi selengkapnya, lihat Apa yang dimaksud dengan template pesan?

Elemen <AllowHeaders> menggunakan sintaksis berikut:

Sintaks

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins>
  <AllowHeaders>[origin, x-requested-with, accept, content-type, ...]</AllowHeaders>
</CORS>

Contoh

Contoh AllowOrigins CORS

Contoh ini menentukan header HTTP yang dapat digunakan saat meminta resource.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <AllowHeaders>origin, x-requested-with, accept, content-type</AllowHeaders>
</CORS>

<AllowMethods>

Daftar metode HTTP yang diizinkan untuk mengakses resource. Konten akan diserialisasi ke dalam header Access-Control-Allow-Methods.

Nilai Default GET, POST, HEAD, OPTIONS
Wajib? Opsional
Jenis String, dengan dukungan template pesan*
Elemen Induk <CORS>
Elemen Turunan Tidak ada

* Untuk informasi selengkapnya, lihat Apa yang dimaksud dengan template pesan?

Elemen <AllowMethods> menggunakan sintaksis berikut:

Sintaks

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins>
  <AllowMethods>[GET, PUT, POST, DELETE, ...|*]</AllowMethods>
</CORS>

Contoh:
Daftar

Contoh ini menentukan metode HTTP yang diizinkan untuk mengakses resource.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <AllowMethods>GET, PUT, POST, DELETE</AllowMethods>
</CORS>

Contoh:
Karakter pengganti

Contoh ini menentukan bahwa semua metode HTTP diizinkan untuk mengakses resource.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <AllowMethods>*</AllowMethods>
</CORS>

<AllowOrigins>

Daftar origin yang diizinkan untuk mengakses resource. Gunakan tanda bintang (*) untuk mengaktifkan akses ke resource dari asal mana pun. Jika tidak, berikan daftar yang diizinkan dari origin yang dipisahkan koma. Jika kecocokan ditemukan, Access-Control-Allow-Origin keluar akan ditetapkan ke origin seperti yang disediakan oleh klien.

Nilai Default T/A
Wajib? Wajib
Jenis String, dengan dukungan template pesan*
Elemen Induk <CORS>
Elemen Turunan Tidak ada

* Untuk informasi selengkapnya, lihat Apa yang dimaksud dengan template pesan?

Elemen <AllowOrigins> menggunakan sintaksis berikut:

Sintaks

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins>
</CORS>

Contoh:
URL tunggal

Contoh ini menentukan satu origin URL yang diizinkan untuk mengakses resource.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>https://www.w3.org</AllowOrigins>
</CORS>

Contoh:
Beberapa URL

Contoh ini menentukan beberapa origin yang diizinkan untuk mengakses resource.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>https://www.w3.org, https://www.apache.org</AllowOrigins>
</CORS>

Contoh:
Variabel konteks

Contoh ini menentukan variabel konteks yang mewakili satu atau beberapa origin yang diizinkan untuk mengakses resource.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{origins.list}</AllowOrigins>
</CORS>

Contoh:
Variabel alur

Contoh ini menentukan variabel alur yang mewakili satu origin yang diizinkan untuk mengakses resource.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
</CORS>

Contoh:
Karakter pengganti

Contoh ini menentukan bahwa semua origin diizinkan untuk mengakses resource.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>*</AllowOrigins>
</CORS>

<DisplayName>

Gunakan selain atribut name untuk memberi label pada kebijakan di editor proxy UI pengelolaan dengan nama yang berbeda dan lebih terdengar alami.

Elemen <DisplayName> umum untuk semua kebijakan.

Nilai Default T/A
Wajib? Opsional. Jika Anda menghilangkan <DisplayName>, nilai atribut name kebijakan akan digunakan.
Jenis String
Elemen Induk <PolicyElement>
Elemen Turunan Tidak ada

Elemen <DisplayName> menggunakan sintaksis berikut:

Sintaks

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

Contoh

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

Elemen <DisplayName> tidak memiliki atribut atau elemen turunan.

<ExposeHeaders>

Daftar header HTTP yang diizinkan untuk diakses browser atau tanda bintang (*) untuk mengizinkan semua header HTTP. Diseralisasikan ke dalam header Access-Control-Expose-Headers.

Nilai Default Jika tidak ditentukan, Access-Control-Expose-Headers tidak akan ditetapkan. Header non-sederhana tidak diekspos secara default.
Wajib? Opsional
Jenis String, dengan dukungan template pesan*
Elemen Induk <CORS>
Elemen Turunan Tidak ada

* Untuk informasi selengkapnya, lihat Apa yang dimaksud dengan template pesan?

Elemen <ExposeHeaders> menggunakan sintaksis berikut:

Sintaks

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins>
  <ExposeHeaders>[X-CUSTOM-HEADER-A, X-CUSTOM-HEADER-B, ... | *]</ExposeHeaders>
</CORS>

Contoh

Contoh ini menentukan bahwa browser diizinkan untuk mengakses semua header HTTP.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <ExposeHeaders>*</ExposeHeaders>
</CORS>

<GeneratePreflightResponse>

Menunjukkan apakah kebijakan harus membuat dan menampilkan respons preflight CORS. Jika false, tidak ada respons yang dikirim. Sebagai gantinya, variabel alur berikut akan diisi:

  • cross_origin_resource_sharing.allow.credentials
  • cross_origin_resource_sharing.allow.headers
  • cross_origin_resource_sharing.allow.methods
  • cross_origin_resource_sharing.allow.origin
  • cross_origin_resource_sharing.allow.origins.list
  • cross_origin_resource_sharing.expose.headers
  • cross_origin_resource_sharing.max.age
  • cross_origin_resource_sharing.preflight.accepted
  • cross_origin_resource_sharing.request.headers
  • cross_origin_resource_sharing.request.method
  • cross_origin_resource_sharing.request.origin
  • cross_origin_resource_sharing.request.type
Nilai Default true
Wajib? Opsional
Jenis Boolean
Elemen Induk <CORS>
Elemen Turunan Tidak ada

Elemen <GeneratePreflightResponse> menggunakan sintaksis berikut:

Sintaks

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <GeneratePreflightResponse>[false|true]</GeneratePreflightResponse>
  <GeneratePreflightResponse>[false|true]</GeneratePreflightResponse>
</CORS>

Contoh

Contoh ini menentukan bahwa kebijakan harus membuat dan menampilkan respons preflight CORS.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <GeneratePreflightResponse>true</GeneratePreflightResponse>
</CORS>

<IgnoreUnresolvedVariables>

Menentukan apakah pemrosesan berhenti saat variabel yang belum terselesaikan ditemukan. Tetapkan ke true untuk mengabaikan variabel yang belum terselesaikan dan melanjutkan pemrosesan; jika tidak, false.

Nilai Default true
Wajib? Opsional
Jenis Boolean
Elemen Induk <CORS>
Elemen Turunan Tidak ada

Elemen <IgnoreUnresolvedVariables> menggunakan sintaksis berikut:

Sintaks

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins>
  <IgnoreUnresolvedVariables>[false|true]</IgnoreUnresolvedVariables>
</CORS>

Contoh

Contoh ini menentukan bahwa pemrosesan berlanjut saat variabel yang belum terselesaikan ditemukan.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</CORS>

<MaxAge>

Menentukan berapa lama hasil permintaan pra-penerbangan dapat disimpan dalam cache dalam hitungan detik. Nilai -1 mengisi header Access-Control-Max-Age dengan nilai -1, yang menonaktifkan penyimpanan dalam cache, sehingga memerlukan pemeriksaan preflight OPTIONS untuk semua panggilan. Hal ini ditentukan dalam spesifikasi Access-Control-Max-Age.

Nilai Default 1800
Wajib? Opsional
Jenis Bilangan bulat
Elemen Induk <CORS>
Elemen Turunan Tidak ada

Elemen <MaxAge> menggunakan sintaksis berikut:

Sintaks

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins>
  <MaxAge>[integer|-1]</MaxAge>
</CORS>

Contoh:
Cache

Contoh ini menentukan bahwa hasil permintaan pra-penerbangan dapat disimpan dalam cache selama 3628800 detik.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <MaxAge>3628800</MaxAge>
</CORS>

Contoh:
Tidak ada cache

Contoh ini menentukan bahwa hasil permintaan pra-penerbangan tidak dapat di-cache.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <MaxAge>-1</MaxAge>
</CORS>

Catatan penggunaan

Permintaan OPTIONS

Saat permintaan OPTIONS diterima dan diproses oleh kebijakan CORS, eksekusi alur proxy akan ditransfer langsung ke PreFlow Respons Proxy, yang akan melewati alur permintaan sepenuhnya dan melanjutkan eksekusi dari sana. Anda tidak perlu membuat Kondisi untuk mengabaikan permintaan OPTIONS dalam alur permintaan proxy.

Pada panggilan berikutnya, saat kebijakan CORS dieksekusi, jika MaxAge yang ditetapkan dalam kebijakan belum berakhir, alur akan dilanjutkan seperti biasa. Selama alur respons akhir tepat sebelum "Response Sent to Client", langkah eksekusi CORS khusus "CORSResponseOrErrorFlowExecution" menetapkan header respons CORS (Access-Control-Allow-Credentials, Access-Control-Allow-Origin, dan Access-Control-Expose-Headers) untuk menampilkan respons yang divalidasi CORS.

Kode error

Bagian ini menjelaskan kode error dan pesan error yang ditampilkan serta variabel error yang ditetapkan oleh Apigee saat kebijakan ini memicu error. Informasi ini penting untuk diketahui jika Anda mengembangkan aturan error untuk menangani error. Untuk mempelajari lebih lanjut, lihat Yang perlu Anda ketahui tentang error kebijakan dan Menangani error.

Error runtime

Error ini dapat terjadi saat kebijakan dieksekusi.

Kode kerusakan Status HTTP Penyebab
steps.cors.UnresolvedVariable 500 Error ini terjadi jika variabel yang ditentukan dalam kebijakan CORS adalah:
  • Di luar cakupan (tidak tersedia dalam alur tertentu tempat kebijakan dijalankan)
  • atau

  • Tidak dapat diselesaikan (tidak ditentukan)

Error saat deployment

Error ini dapat terjadi saat Anda men-deploy proxy yang berisi kebijakan ini.

Nama error Penyebab
InvalidMaxAge MaxAge bukan angka
MissingAllowOrigins AllowOrigins tidak ditentukan
InvalidHTTPMethods Salah satu metode di AllowMethods tidak valid
AllowHeadersSizeTooLarge Ukuran string di AllowHeaders terlalu besar.
ExposeHeadersSizeTooLarge Ukuran string di ExposeHeaders terlalu besar.

Variabel error

Variabel ini ditetapkan saat kebijakan ini memicu error saat runtime. Untuk informasi selengkapnya, lihat Yang perlu Anda ketahui tentang error kebijakan.

Variabel Dari mana Contoh
fault.name = "FAULT_NAME" FAULT_NAME adalah nama error, seperti yang tercantum dalam tabel Runtime errors di atas. Nama error adalah bagian terakhir dari kode error. fault.name Matches "UnresolveVariable"
cors.POLICY_NAME.failed POLICY_NAME adalah nama kebijakan yang ditentukan pengguna yang menampilkan error. cors.AddCORS.failed = true

Contoh respons error

{
   "fault":{
      "detail":{
         "errorcode":"steps.cors.UnresolvedVariable"
      },
      "faultstring":"CORS[AddCORS]: unable to resolve variable wrong.var"
   }
}

Contoh aturan error

<FaultRule name="Add CORS Fault">
    <Step>
        <Name>Add-CORSCustomUnresolvedVariableErrorResponse</Name>
        <Condition>(fault.name Matches "UnresolvedVariable") </Condition>
    </Step>
    <Condition>(cors.Add-CORS.failed = true) </Condition>
</FaultRule>

Variabel alur

Objek CorsFlowInfo FlowInfo akan ditambahkan dan akan tersedia untuk dilacak.

Properti Jenis Baca/Tulis Deskripsi Cakupan dimulai
cross_origin_resource_sharing.allow.credentials Boolean Baca/Tulis Nilai dari <AllowCredentials> Permintaan proxy
cross_origin_resource_sharing.allow.headers String Baca/Tulis Nilai dari <AllowHeaders> Permintaan proxy
cross_origin_resource_sharing.allow.methods String Baca/Tulis Nilai dari <AllowMethods> Permintaan proxy
cross_origin_resource_sharing.allow.origin String Baca/Tulis Asal permintaan yang diizinkan, kosong jika tidak ada dalam daftar yang diizinkan Permintaan proxy
cross_origin_resource_sharing.allow.origins.list String Baca/Tulis Nilai dari <AllowOrigins> Permintaan proxy
cross_origin_resource_sharing.expose.headers String Baca/Tulis Nilai dari <ExposeHeaders> Permintaan proxy
cross_origin_resource_sharing.max.age Bilangan bulat Baca/Tulis Nilai dari <MaxAge> Permintaan proxy
cross_origin_resource_sharing.preflight.accepted Boolean Baca/Tulis Menunjukkan apakah permintaan pra-penerbangan diterima Permintaan proxy
cross_origin_resource_sharing.request.headers String Baca/Tulis Nilai header Access-Control-Request-Headers permintaan Permintaan proxy
cross_origin_resource_sharing.request.method String Baca/Tulis Nilai header Access-Control-Request-Method permintaan Permintaan proxy
cross_origin_resource_sharing.request.origin String Baca/Tulis Sama seperti request.header.origin Permintaan proxy
cross_origin_resource_sharing.request.type String Baca/Tulis

Jenis permintaan CORS. Nilai yang memungkinkan:

  • AKTUAL: Permintaan yang bukan permintaan pra-penerbangan
  • PRE_FLIGHT: Permintaan preflight
Permintaan proxy