本頁面由 Cloud Translation API 翻譯而成。

CORS 政策

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

結果

跨來源資源共享 (CORS) 是一種標準機制，可讓您在網頁中執行 JavaScript XMLHttpRequest (XHR) 呼叫，以便與非來源網域的資源互動。CORS 是常見的實作解決方案，可解決所有瀏覽器強制執行的同源政策。

舉例來說，如果您透過在瀏覽器中執行的 JavaScript 程式碼，對 Twitter API 發出 XHR 呼叫，該呼叫將會失敗。這是因為向瀏覽器提供網頁的網域與提供 Twitter API 的網域不同。CORS 為此問題提供瞭解決方案，只要伺服器希望提供跨來源資源共用功能，即可選擇加入。

這項 CORS 政策可讓 Apigee 客戶為網頁應用程式所使用的 API 設定 CORS 政策。

這項政策是標準政策，可部署至任何環境類型。如要瞭解政策類型和各環境類型的可用性，請參閱「政策類型」。

用途

CORS 的一個常見用途是開發人員入口網站 SmartDoc 的「試用這個 API」功能。

詳情請參閱「設定 API proxy 以支援『Try this API』面板」。

`<CORS>` 元素

定義 CORS 政策。

預設值	請參閱下方的「Default Policy」分頁
是否必要？	必填
類型	複雜物件
上層元素	N/A
子元素	`<AllowCredentials>` `<AllowHeaders>` `<AllowMethods>` `<AllowOrigins>` `<DisplayName>` `<ExposeHeaders>` `<GeneratePreflightResponse>` `<IgnoreUnresolvedVariables>` `<MaxAge>`

<CORS> 元素使用以下語法：

語法

<CORS> 元素使用以下語法：


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

預設政策

以下範例顯示在 Edge UI 中將 CORS 政策新增至流程時的預設設定：

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

在 Apigee UI 中插入新的 CORS 政策時，範本會包含所有可能作業的 Stub。通常，您會選取要透過這項政策執行的作業，並移除其他子元素。舉例來說，如果您想指定允許存取資源的 HTTP 方法，請使用 <AllowMethods> 元素，並從政策中移除其他子元素，讓政策更易讀。

這個元素包含下列所有政策都適用的屬性：

屬性	預設	是否必要？	說明
`name`	不適用	必要	政策的內部名稱。`name` 屬性的值可以包含英文字母、數字、空格、連字號、底線和句號。這個值不得超過 255 個半形字元。您可以選擇使用 `<DisplayName>` 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。
`continueOnError`	false	選用	將其設為 `false`，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。將其設為 `true`，即使政策失敗，流程執行作業仍會繼續進行。另請參閱：錯誤規則僅會在錯誤狀態下觸發 (關於 continueOnError) 處理目前流程中的錯誤
`enabled`	是	選用	設為 `true` 即可強制執行政策。設為 `false` 即可關閉政策。即使政策仍附加至流程，系統也不會強制執行這項政策。
`async`	false	已淘汰	此屬性已淘汰。

下文將說明每個子元素。

範例

下列各節會提供所有子元素的範例。

子元素參照

本節將說明 <CORS> 的子元素。

`<AllowCredentials>`

指出是否允許呼叫端使用憑證傳送實際要求 (而非預檢)。會轉譯為 Access-Control-Allow-Credentials 標頭。

預設值	如未指定，系統不會設定 `Access-Control-Allow-Credentials`。
是否必要？	選用
類型	布林值
上層元素	`<CORS>`
子元素	無

<AllowCredentials> 元素使用以下語法：

語法

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

範例

這個範例會將 Access-Control-Allow-Credentials 標頭設為 false。也就是說，呼叫端「不得」使用憑證傳送實際要求 (而非預檢)。

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

`<AllowHeaders>`

可在要求資源時使用的 HTTP 標頭清單。序列化至 Access-Control-Allow-Headers 標頭。

預設值	`Origin, Accept, X-Requested-With, Content-Type, Access-Control-Request-Method, Access-Control-Request-Headers`
是否必要？	選用
類型	字串，支援訊息範本*
上層元素	`<CORS>`
子元素	無

提示：Apigee 建議您在 <AllowHeaders> 中新增的值不超過 50 個。

* 詳情請參閱「什麼是訊息範本？」

<AllowHeaders> 元素使用以下語法：

語法

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

範例

CORS AllowOrigins 範例

這個範例會指定可在要求資源時使用的 HTTP 標頭。

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

`<AllowMethods>`

允許存取資源的 HTTP 方法清單。內容會序列化至 Access-Control-Allow-Methods 標頭。

預設值	`GET, POST, HEAD, OPTIONS`
是否必要？	選用
類型	字串，支援訊息範本*
上層元素	`<CORS>`
子元素	無

* 詳情請參閱「什麼是訊息範本？」

<AllowMethods> 元素使用以下語法：

語法

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

範例：
清單

這個範例會指定允許存取資源的 HTTP 方法。

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

範例：
萬用字元

這個範例會指定允許所有 HTTP 方法存取資源。

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

`<AllowOrigins>`

可存取資源的來源清單。使用星號 (*) 可啟用從任何來源存取資源的權限。否則，請提供以半形逗號分隔的來源網址清單。如果找到相符項目，則傳出 Access-Control-Allow-Origin 會設為用戶端提供的來源。

預設值	不適用
是否必要？	必填
類型	字串，支援訊息範本*
上層元素	`<CORS>`
子元素	無

提示：Apigee 建議您在 <AllowOrigins> 中新增的值不超過 50 個。

* 詳情請參閱「什麼是訊息範本？」

<AllowOrigins> 元素使用以下語法：

語法

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

範例：
單一網址

這個範例指定了單一網址來源，可存取該資源。

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

範例：
多個網址

這個範例會指定允許存取資源的多個來源。

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

範例：
Context 變數

本範例會指定代表一或多個允許存取資源的來源的內容變數。

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

範例：
Flow 變數

這個範例會指定一個流程變數，代表允許存取資源的來源。

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

範例：
萬用字元

這個範例指定允許所有來源存取資源。

注意：如果 Proxy 開發人員將 Access-Control-Allow-Origin 標頭設為允許所有內容 (*)，就會有效地停用同源保護機制。預設值不應設為允許所有 (*)。政策開發人員應在公開資源前謹慎做出決定。

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

`<DisplayName>`

除了 name 屬性之外，您也可以在管理 UI 代理程式編輯器中使用其他更自然的名稱標記政策。

<DisplayName> 元素適用於所有政策。

預設值	不適用
是否必要？	(非必要) 如果省略 `<DisplayName>`，系統會使用政策的 `name` 屬性值。
類型	字串
上層元素	<`PolicyElement`>
子元素	無

<DisplayName> 元素使用以下語法：

語法

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

範例

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

<DisplayName> 元素沒有屬性或子項元素。

`<ExposeHeaders>`

瀏覽器可存取的 HTTP 標頭清單，或允許所有 HTTP 標頭的星號 (*)。序列化至 Access-Control-Expose-Headers 標頭。

預設值	如未指定，系統不會設定 `Access-Control-Expose-Headers`。根據預設，系統不會公開非簡式標頭。
是否必要？	選用
類型	字串，支援訊息範本*
上層元素	`<CORS>`
子元素	無

提示：Apigee 建議您在 <ExposeHeaders> 中新增的值不超過 50 個。

* 詳情請參閱「什麼是訊息範本？」

<ExposeHeaders> 元素使用以下語法：

語法

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

範例

這個範例會指定瀏覽器可存取所有 HTTP 標頭。

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

`<GeneratePreflightResponse>`

指出政策應否產生並傳回 CORS 預檢回應。如果為 false，則不會傳送回應。而是填入下列流程變數：

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

預設值	`true`
是否必要？	選用
類型	布林值
上層元素	`<CORS>`
子元素	無

<GeneratePreflightResponse> 元素使用以下語法：

語法

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

範例

這個範例會指定政策應產生並傳回 CORS 預檢回應。

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

`<IgnoreUnresolvedVariables>`

判斷遇到未解析的變數時是否停止處理。將其設為 true 可忽略未解析的變數並繼續處理；否則為 false。

預設值	`true`
是否必要？	選用
類型	布林值
上層元素	`<CORS>`
子元素	無

<IgnoreUnresolvedVariables> 元素使用以下語法：

語法

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

範例

這個範例會指定在遇到未解析的變數時繼續處理。

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

`<MaxAge>`

指定預檢要求結果的快取時間長度 (以秒為單位)。值為 -1 時，系統會在 Access-Control-Max-Age 標頭中填入值為 -1 的值，這會停用快取功能，並要求對所有呼叫執行預檢 OPTIONS 檢查。這項資訊已在 Access-Control-Max-Age 規格中定義。

預設值	`1800`
是否必要？	選用
類型	整數
上層元素	`<CORS>`
子元素	無

<MaxAge> 元素使用以下語法：

語法

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

示例：
快取

這個範例指定預檢要求的結果可快取 3628800 秒。

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

示例：
無快取

這個範例指定預檢要求的結果無法快取。

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

使用須知

`OPTIONS` 要求

當 CORS 政策收到並處理 OPTIONS 要求時，Proxy 流程執行作業會直接轉移至 Proxy Response PreFlow，完全略過要求流程，並從該處繼續執行。您不需要建立條件來忽略代理要求流程中的 OPTIONS 要求。

在後續呼叫中，當 CORS 政策執行時，如果政策中設定的 MaxAge 尚未到期，流程就會照常繼續。在「回應傳送至用戶端」之前的最終回應流程中，特殊的 CORS 執行步驟「CORSResponseOrErrorFlowExecution」會設定 CORS 回應標頭 (Access-Control-Allow-Credentials、Access-Control-Allow-Origin 和 Access-Control-Expose-Headers)，以便傳回經 CORS 驗證的回應。

錯誤代碼

本節說明這項政策觸發錯誤時，Apigee 傳回的錯誤代碼和錯誤訊息，以及 Apigee 設定的錯誤變數。如果您要開發錯誤處理規則來處理錯誤，就必須瞭解這項資訊。如需更多資訊，請參閱「政策錯誤的相關資訊」和「處理錯誤」。

執行階段錯誤

政策執行時可能會發生這些錯誤。

錯誤代碼	HTTP 狀態	原因
`steps.cors.UnresolvedVariable`	`500`	如果 CORS 政策中指定的變數為下列任一情況，就會發生此錯誤：超出範圍 (無法在執行政策的特定流程中使用) 或無法解析 (未定義)

部署錯誤

部署含有這項政策的 Proxy 時，可能會發生這些錯誤。

錯誤名稱	原因
`InvalidMaxAge`	`MaxAge` 不是數字
`MissingAllowOrigins`	未指定 `AllowOrigins`
`InvalidHTTPMethods`	`AllowMethods` 中其中一個方法無效
`AllowHeadersSizeTooLarge`	`AllowHeaders` 中的字串大小過大。
`ExposeHeadersSizeTooLarge`	`ExposeHeaders` 中的字串大小過大。

錯誤變數

當這項政策在執行階段觸發錯誤時，系統就會設定這些變數。詳情請參閱「政策錯誤須知」。

注意：如果 <GeneratePreflightResponse> 設為 true 且發生錯誤，政策會立即傳回回應給用戶端，並略過錯誤流程。系統不會填入下列變數：

變數	地點	範例
`fault.name = "FAULT_NAME"`	`FAULT_NAME` 是錯誤名稱，如上方「執行階段錯誤」表格所列。錯誤名稱是錯誤代碼的最後一部分。	`fault.name Matches "UnresolveVariable"`
`cors.POLICY_NAME.failed`	`POLICY_NAME` 是擲回錯誤的政策的使用者指定名稱。	`cors.AddCORS.failed = true`

錯誤回應範例

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

錯誤規則範例

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

流程變數

系統會新增 CorsFlowInfo FlowInfo 物件，並可用於追蹤。

屬性	類型	讀取/寫入	說明	範圍開始
`cross_origin_resource_sharing.allow.credentials`	布林值	讀取/寫入	`<AllowCredentials>` 的值	Proxy 要求
`cross_origin_resource_sharing.allow.headers`	字串	讀取/寫入	`<AllowHeaders>` 的值	Proxy 要求
`cross_origin_resource_sharing.allow.methods`	字串	讀取/寫入	`<AllowMethods>` 的值	Proxy 要求
`cross_origin_resource_sharing.allow.origin`	字串	讀取/寫入	允許的請求來源，如果不在許可清單中，則為空白	Proxy 要求
`cross_origin_resource_sharing.allow.origins.list`	字串	讀取/寫入	`<AllowOrigins>` 的值	Proxy 要求
`cross_origin_resource_sharing.expose.headers`	字串	讀取/寫入	`<ExposeHeaders>` 的值	Proxy 要求
`cross_origin_resource_sharing.max.age`	整數	讀取/寫入	`<MaxAge>` 的值	Proxy 要求
`cross_origin_resource_sharing.preflight.accepted`	布林值	讀取/寫入	指出是否接受預檢要求	Proxy 要求
`cross_origin_resource_sharing.request.headers`	字串	讀取/寫入	要求 `Access-Control-Request-Headers` 標頭的值	Proxy 要求
`cross_origin_resource_sharing.request.method`	字串	讀取/寫入	要求 `Access-Control-Request-Method` 標頭的值	Proxy 要求
`cross_origin_resource_sharing.request.origin`	字串	讀取/寫入	與 `request.header.origin` 相同	Proxy 要求
`cross_origin_resource_sharing.request.type`	字串	讀取/寫入	CORS 要求類型。可能的值包括：實際情況：非預檢要求 PRE_FLIGHT:預檢要求	Proxy 要求

CORS 政策 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

結果

用途

<CORS> 元素

語法

預設政策

範例

子元素參照

<AllowCredentials>

語法

範例

<AllowHeaders>

語法

範例

<AllowMethods>

語法

範例：清單

範例：萬用字元

<AllowOrigins>

語法

範例：單一網址

範例：多個網址

範例：Context 變數

範例：Flow 變數

範例：萬用字元

<DisplayName>

語法

範例

<ExposeHeaders>

語法

範例

<GeneratePreflightResponse>

語法

範例

<IgnoreUnresolvedVariables>

語法

範例

<MaxAge>

語法

示例：快取

示例：無快取

使用須知

OPTIONS 要求

錯誤代碼

執行階段錯誤

部署錯誤

錯誤變數

錯誤回應範例

錯誤規則範例

流程變數

CORS 政策

`<CORS>` 元素

`<AllowCredentials>`

`<AllowHeaders>`

`<AllowMethods>`

範例：
清單

範例：
萬用字元

`<AllowOrigins>`

範例：
單一網址

範例：
多個網址

範例：
Context 變數

範例：
Flow 變數

範例：
萬用字元

`<DisplayName>`

`<ExposeHeaders>`

`<GeneratePreflightResponse>`

`<IgnoreUnresolvedVariables>`

`<MaxAge>`

示例：
快取

示例：
無快取

`OPTIONS` 要求