Kebijakan CORS

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat Dokumentasi Apigee Edge.

ikon kebijakan

Apa

Berbagi resource lintas origin (CORS) adalah mekanisme yang memungkinkan panggilan JavaScript XMLHttpRequest (XHR) yang dieksekusi di laman web untuk berinteraksi dengan resource dari domain non-origin. CORS adalah solusi yang umum diimplementasikan untuk kebijakan origin yang sama yang diterapkan oleh semua browser.

Misalnya, jika Anda membuat 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 menyalurkan Twitter API. CORS memberikan solusi untuk masalah ini dengan mengizinkan server untuk ikut serta jika ingin menyediakan resource berbagi lintas origin.

Dengan kebijakan CORS ini, pelanggan Apigee dapat menetapkan kebijakan CORS untuk API yang digunakan oleh web menggunakan berbagai aplikasi obrolan.

Kebijakan ini merupakan Kebijakan standar dan dapat di-deploy ke jenis lingkungan apa pun. Tidak semua perlu diketahui pengguna tentang jenis kebijakan dan lingkungan. Sebagai informasi tentang jenis kebijakan dan ketersediaan untuk 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 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 mana yang ingin Anda lakukan dengan kebijakan ini dan menghapus elemen turunan lainnya. Misalnya, jika Anda ingin menentukan metode HTTP yang diizinkan untuk mengakses resource, gunakan elemen <AllowMethods> dan menghapus elemen turunan lain dari kebijakan agar lebih mudah dibaca.

Elemen ini memiliki atribut berikut yang sama 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.

Atau, gunakan elemen <DisplayName> untuk memberi label kebijakan di editor proxy UI pengelolaan dengan nama natural-language yang berbeda.

continueOnError false Opsional Setel ke false untuk menampilkan error jika kebijakan gagal. Ini adalah perilaku yang wajar untuk sebagian besar kebijakan. Setel ke true agar eksekusi alur tetap berlanjut bahkan setelah kebijakan gagal. Lihat juga:
enabled true Opsional Setel ke true untuk menerapkan kebijakan. Setel ke false untuk menonaktifkan kebijakan. Kebijakan tidak akan diterapkan meskipun tetap melekat pada alur.
async   false Tidak digunakan lagi Atribut ini sudah tidak digunakan lagi.

Setiap elemen turunan dijelaskan di bagian selanjutnya.

Contoh

Contoh diberikan untuk semua elemen turunan di bagian berikut.

Referensi elemen turunan

Bagian ini menjelaskan elemen turunan dari <CORS>.

<AllowCredentials>

Menunjukkan apakah pemanggil diizinkan untuk mengirim permintaan sebenarnya (bukan preflight) menggunakan memiliki kredensial yang lengkap. Menerjemahkan 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 yang sebenarnya (bukan preflight) 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 menurut 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 menetapkan 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 tersebut 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 menetapkan 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 menetapkan bahwa semua metode HTTP diizinkan untuk mengakses sumber daya.

<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 sumber daya dari sumber mana pun. Atau, berikan daftar yang diizinkan dari origin yang dipisahkan koma. Jika ditemukan kecocokan, maka keluar Access-Control-Allow-Origin 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 menetapkan satu asal 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 menetapkan 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 menetapkan 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 flow

Contoh ini menetapkan variabel alur yang mewakili satu asal yang diizinkan untuk mengakses resource.

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

Contoh:
Karakter pengganti

Contoh ini menetapkan 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 kebijakan di editor proxy UI pengelolaan dengan nama yang berbeda dan lebih alami.

Elemen <DisplayName> bersifat 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:

Sintaksis

<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 boleh diakses oleh browser atau tanda bintang (*) untuk mengizinkan semua header HTTP. Diserialisasi ke dalam Header Access-Control-Expose-Headers.

Nilai Default Jika tidak ditentukan, Access-Control-Expose-Headers tidak akan ditetapkan. Header yang tidak sederhana tidak ditampilkan 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 menetapkan 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>

Tunjukkan apakah kebijakan harus membuat dan menampilkan respons preflight CORS. Jika false, tidak ada respons yang akan dikirim. Sebagai gantinya, variabel flow berikut telah 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 dilanjutkan 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 preflight dapat di-cache dalam detik. Nilai -1 mengisi header Access-Control-Max-Age dengan nilai -1, yang menonaktifkan penyimpanan dalam cache, sehingga memerlukan preflight OPTIONS periksa 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 menetapkan bahwa hasil permintaan preflight 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 menetapkan bahwa hasil permintaan preflight tidak dapat di-cache.

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

Catatan penggunaan

OPTIONS permintaan

Jika Permintaan OPTIONS diterima dan diproses oleh kebijakan CORS, eksekusi alur proxy langsung ditransfer ke PreFlow Respons Proxy, lewati alur permintaan sepenuhnya dan melanjutkan eksekusi dari sana. Tidak perlu membuat Kondisi untuk mengabaikan OPSI di alur permintaan proxy.

Pada panggilan berikutnya, saat kebijakan CORS dijalankan, jika MaxAge yang ditetapkan dalam kebijakan belum kedaluwarsa, alur akan berlanjut seperti biasa. Selama alur respons akhir tepat sebelum "Respons Dikirim ke Klien,” langkah eksekusi CORS khusus "CORSResponseOrErrorFlowExecution" menetapkan respons CORS header (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 kesalahan dan pesan error yang ditampilkan dan variabel kesalahan yang disetel oleh Apigee saat kebijakan ini memicu error. Informasi ini penting untuk diketahui apakah Anda mengembangkan aturan kesalahan untuk menangani kesalahan. Untuk mempelajari lebih lanjut, lihat Hal yang perlu Anda ketahui tentang error kebijakan dan Menangani kesalahan.

Error runtime

Error ini dapat terjadi saat kebijakan dieksekusi.

Kode kesalahan Status HTTP Penyebab
steps.cors.UnresolvedVariable 500 Error ini terjadi jika variabel yang ditentukan dalam kebijakan CORS adalah:
  • Di luar cakupan (tidak tersedia di alur spesifik tempat kebijakan sedang 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 kesalahan

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

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

Contoh respons error

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

Contoh aturan kesalahan

<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 flow

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 preflight 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:

  • ACTUAL: Permintaan yang bukan permintaan preflight
  • PRE_FLIGHT: Permintaan preflight
Permintaan proxy