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

CORS 政策

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

結果

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

舉例來說，如果您從瀏覽器中執行的 JavaScript 程式碼，對 Twitter API 發出 XHR 呼叫，該呼叫就會失敗。這是因為向瀏覽器提供網頁的網域，與提供 Twitter API 的網域不同。CORS 可讓伺服器選擇啟用跨源資源共用，解決這個問題。

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

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

用途

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

詳情請參閱「設定 API Proxy，支援『試用這個 API』面板」。

`<CORS>` 元素

定義 CORS 政策。

預設值	請參閱下方的「預設政策」分頁
必填與否	必填
類型	複雜物件
父項元素	不適用
子元素	`<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 政策時，範本會包含所有可能作業的存根。通常，您會選取要透過這項政策執行的作業，並移除其餘子項元素。舉例來說，如要指定允許存取資源的 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>

範例：
內容變數

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

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

範例：
流程變數

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

<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 時，系統會以 -1 值填入 Access-Control-Max-Age 標頭，停用快取功能，並要求對所有呼叫進行預檢 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 回應前置流程，完全略過要求流程，並從該處繼續執行。您不需要建立條件，即可在 Proxy 要求流程中忽略 OPTIONS 要求。

在後續呼叫中，當 CORS 政策執行時，如果政策中設定的 MaxAge 尚未過期，流程會照常繼續。在最終回應流程中，也就是「Response Sent to Client」之前，系統會執行特殊的 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>

語法

範例：單一網址

範例：多個網址

範例：內容變數

範例：流程變數

範例：萬用字元

<DisplayName>

語法

範例

<ExposeHeaders>

語法

範例

<GeneratePreflightResponse>

語法

範例

<IgnoreUnresolvedVariables>

語法

範例

<MaxAge>

語法

示例：快取

示例：無快取

使用須知

OPTIONS 要求

錯誤代碼

執行階段錯誤

部署錯誤

錯誤變數

錯誤回應範例

錯誤規則範例

流程變數

CORS 政策

`<CORS>` 元素

`<AllowCredentials>`

`<AllowHeaders>`

`<AllowMethods>`

範例：
清單

範例：
萬用字元

`<AllowOrigins>`

範例：
單一網址

範例：
多個網址

範例：
內容變數

範例：
流程變數

範例：
萬用字元

`<DisplayName>`

`<ExposeHeaders>`

`<GeneratePreflightResponse>`

`<IgnoreUnresolvedVariables>`

`<MaxAge>`

示例：
快取

示例：
無快取

`OPTIONS` 要求