Halaman ini berlaku untuk Apigee dan Apigee Hybrid.
Baca dokumentasi Apigee Edge.
Apa
Berbagi resource lintas origin (CORS) adalah mekanisme standar yang memungkinkan panggilan XMLHttpRequest (XHR) JavaScript yang dieksekusi di halaman web berinteraksi dengan resource dari domain non-asal. CORS adalah solusi yang umumnya diimplementasikan untuk kebijakan asal yang sama yang diterapkan oleh semua browser.
Misalnya, jika Anda melakukan panggilan XHR ke Twitter API dari kode JavaScript yang dieksekusi di browser Anda, panggilan akan gagal. Hal ini karena domain yang menayangkan halaman ke browser Anda tidak sama dengan domain yang menayangkan Twitter API. CORS memberikan solusi atas masalah ini dengan mengizinkan server untuk ikut serta jika ingin menyediakan resource berbagi lintas asal.
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. Tidak semua pengguna perlu mengetahui tentang kebijakan dan jenis lingkungan. Untuk mengetahui 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? | Diperlukan |
Type | 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 alur 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 tersebut akan berisi stub untuk semua kemungkinan operasi. Biasanya, Anda memilih operasi mana 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 sama untuk semua kebijakan:
Atribut | Default | Wajib? | Deskripsi |
---|---|---|---|
name |
T/A | Wajib |
Nama internal kebijakan. Nilai atribut Atau, gunakan elemen |
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 <CORS>
.
<AllowCredentials>
Menunjukkan apakah pemanggil diizinkan mengirim permintaan yang sebenarnya (bukan preflight) menggunakan
kredensial. Menerjemahkan ke header Access-Control-Allow-Credentials
.
Nilai Default | Jika tidak ditentukan, Access-Control-Allow-Credentials tidak akan ditetapkan. |
Wajib? | Opsional |
Type | Boolean |
Elemen Induk |
<CORS>
|
Elemen Turunan | Tidak ada |
Elemen <AllowCredentials>
menggunakan sintaksis berikut:
Sintaksis
<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 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 |
Type | String, dengan dukungan template pesan* |
Elemen Induk |
<CORS>
|
Elemen Turunan | Tidak ada |
* Untuk mengetahui informasi selengkapnya, lihat Apa itu template pesan?
Elemen <AllowHeaders>
menggunakan sintaksis berikut:
Sintaksis
<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 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 akan
diserialisasi ke
header Access-Control-Allow-Methods
.
Nilai Default | GET, POST, HEAD, OPTIONS |
Wajib? | Opsional |
Type | String, dengan dukungan template pesan* |
Elemen Induk |
<CORS>
|
Elemen Turunan | Tidak ada |
* Untuk mengetahui informasi selengkapnya, lihat Apa itu template pesan?
Elemen <AllowMethods>
menggunakan sintaksis berikut:
Sintaksis
<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 resource dari asal mana pun. Jika tidak, berikan daftar asal yang dipisahkan koma yang diizinkan. Jika ditemukan kecocokan, Access-Control-Allow-Origin
keluar akan ditetapkan ke asal seperti yang disediakan oleh klien.
Nilai Default | T/A |
Wajib? | Diperlukan |
Type | String, dengan dukungan template pesan* |
Elemen Induk |
<CORS>
|
Elemen Turunan | Tidak ada |
* Untuk mengetahui informasi selengkapnya, lihat Apa itu template pesan?
Elemen <AllowOrigins>
menggunakan sintaksis berikut:
Sintaksis
<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 diizinkan untuk diakses browser atau tanda bintang (*
)
untuk mengizinkan semua header HTTP.
Diserialisasi ke 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 |
Type | String, dengan dukungan template pesan* |
Elemen Induk |
<CORS>
|
Elemen Turunan | Tidak ada |
* Untuk mengetahui informasi selengkapnya, lihat Apa itu template pesan?
Elemen <ExposeHeaders>
menggunakan sintaksis berikut:
Sintaksis
<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>
Tentukan apakah kebijakan tersebut harus membuat dan menampilkan respons preflight CORS.
Jika false
, tidak ada respons yang dikirim. Sebagai gantinya, variabel flow 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 |
Type | Boolean |
Elemen Induk |
<CORS>
|
Elemen Turunan | Tidak ada |
Elemen <GeneratePreflightResponse>
menggunakan sintaksis berikut:
Sintaksis
<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 ketika 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 |
Type | Boolean |
Elemen Induk |
<CORS>
|
Elemen Turunan | Tidak ada |
Elemen <IgnoreUnresolvedVariables>
menggunakan sintaksis berikut:
Sintaksis
<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 hitungan detik.
Nilai -1
mengisi header Access-Control-Max-Age
dengan
nilai -1
, yang menonaktifkan penyimpanan dalam cache, sehingga memerlukan pemeriksaan
OPTIONS
preflight untuk semua panggilan. Hal ini ditentukan dalam
spesifikasi
Access-Control-Max-Age
.
Nilai Default | 1800 |
Wajib? | Opsional |
Type | Bilangan bulat |
Elemen Induk |
<CORS>
|
Elemen Turunan | Tidak ada |
Elemen <MaxAge>
menggunakan sintaksis berikut:
Sintaksis
<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
Saat permintaan
OPTIONS
diterima dan diproses oleh kebijakan CORS, eksekusi alur proxy akan ditransfer langsung ke PreFlow Respons Proxy, yang melewati alur permintaan sepenuhnya dan melanjutkan eksekusi dari sana. 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 habis masa berlakunya, alur akan berlanjut seperti biasa. Selama alur respons akhir tepat sebelum "Respons Dikirim ke Klien", 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 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:
atau |
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 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 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 mungkin muncul:
|
Permintaan proxy |