Halaman ini berlaku untuk Apigee dan Apigee Hybrid.
Lihat dokumentasi
Apigee Edge.
Apa
Cross-origin resource sharing (CORS) adalah mekanisme standar yang memungkinkan panggilan JavaScript XMLHttpRequest (XHR) yang dieksekusi di halaman web 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 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 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 dan ketersediaan kebijakan 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 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 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 Secara opsional, gunakan elemen |
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 selanjutnya.
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 preflight) 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 mengetahui informasi selengkapnya, lihat Apa itu 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 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
diserialkan 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 mengetahui informasi selengkapnya, lihat Apa itu 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:
List
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
berisi asal yang dipisahkan koma. Jika kecocokan ditemukan, Access-Control-Allow-Origin
keluar
ditetapkan ke origin seperti yang diberikan oleh klien.
Nilai Default | T/A |
Wajib? | Wajib |
Jenis | 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:
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
This example specifies that all origins are allowed to access the 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 oleh browser atau tanda bintang (*
)
untuk mengizinkan semua header HTTP.
Diserialkan ke dalam
header Access-Control-Expose-Headers
.
Nilai Default | Jika tidak ditentukan, Access-Control-Expose-Headers tidak akan ditetapkan. Header tidak sederhana tidak diekspos secara default. |
Wajib? | Opsional |
Jenis | 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:
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 diselesaikan ditemukan.
Setel ke true
untuk mengabaikan variabel yang belum diselesaikan 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
This example specifies that processing continues when an unresolved variable is encountered.
<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
akan mengisi header Access-Control-Max-Age
dengan
nilai -1
, yang menonaktifkan penyimpanan dalam cache, sehingga memerlukan pemeriksaan
OPTIONS
pra-penerbangan 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
This example specifies that the results of a preflight request
can be cached for 3628800
seconds.
<CORS continueOnError="false" enabled="true" name="add-cors"> <AllowOrigins>{request.header.origin}</AllowOrigins> <MaxAge>3628800</MaxAge> </CORS>
Contoh:
Tanpa cache
This example specifies that the results of a preflight request cannot be cached.
<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
ditransfer langsung ke PreFlow Respons Proxy, 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 dijalankan, 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
This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.
Runtime errors
These errors can occur when the policy executes.
Fault code | HTTP status | Cause |
---|---|---|
steps.cors.UnresolvedVariable |
500 |
This error occurs if a variable specified in the CORS policy is either:
or |
Deployment errors
These errors can occur when you deploy a proxy containing this policy.
Error name | Cause |
---|---|
InvalidMaxAge |
MaxAge is not number |
MissingAllowOrigins |
AllowOrigins is not specified |
InvalidHTTPMethods |
One of the methods in AllowMethods is not valid |
AllowHeadersSizeTooLarge |
The string size in AllowHeaders is too large. |
ExposeHeadersSizeTooLarge |
The string size in ExposeHeaders is too large. |
Fault variables
These variables are set when this policy triggers an error at runtime. For more information, see What you need to know about policy errors.
Variables | Where | Example |
---|---|---|
fault.name = "FAULT_NAME" |
FAULT_NAME is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. | fault.name Matches "UnresolveVariable" |
cors.POLICY_NAME.failed |
POLICY_NAME is the user-specified name of the policy that threw the fault. | cors.AddCORS.failed = true |
Example error response
{ "fault":{ "detail":{ "errorcode":"steps.cors.UnresolvedVariable" }, "faultstring":"CORS[AddCORS]: unable to resolve variable wrong.var" } }
Example fault rule
<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 pelacakan.
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 permintaan Access-Control-Request-Headers |
Permintaan proxy |
cross_origin_resource_sharing.request.method |
String | Baca/Tulis | Nilai header permintaan Access-Control-Request-Method |
Permintaan proxy |
cross_origin_resource_sharing.request.origin |
String | Baca/Tulis | Sama dengan request.header.origin |
Permintaan proxy |
cross_origin_resource_sharing.request.type |
String | Baca/Tulis |
Jenis permintaan CORS. Nilai yang memungkinkan:
|
Permintaan proxy |