API 管理跨網域原則

本主題提供下列 API 管理原則的參考。 如需有關新增和設定原則的資訊,請參閱 API 管理中的原則

跨網域原則

  • 允許跨網域呼叫 - 將 API 設為可供 Adobe Flash 和 Microsoft Silverlight 瀏覽器型用戶端存取。
  • CORS - 將跨原始來源資源分享 (CORS) 支援加入至操作或 API,以允許來自瀏覽器型用戶端的跨網域呼叫。
  • JSONP - 將 JSON 與補充的 (JSONP) 支援加入至操作或 API,以允許來自 JavaScript 瀏覽器型用戶端的跨網域呼叫。

允許跨網域呼叫

使用 cross-domain 原則以將 API 設為可供 Adobe Flash 和 Microsoft Silverlight 瀏覽器型用戶端存取。

原則陳述式

<cross-domain>
    <!-Policy configuration is in the Adobe cross-domain policy file format,
        see https://www.adobe.com/devnet/articles/crossdomain_policy_file_spec.html-->
</cross-domain>

範例

<cross-domain>
        <allow-http-request-headers-from domain='*' headers='*' />
</cross-domain>

項目

名稱 描述 必要
cross-domain 根元素。 子元素必須符合 Adobe 跨網域原則檔案規格 Yes

使用方式

此原則可用於下列原則區段範圍

  • 原則區段︰ inbound
  • 原則範圍: 所有範圍

CORS

cors 原則會將跨原始來源資源分享 (CORS) 支援加入至操作或 API,以允許來自瀏覽器型用戶端的跨網域呼叫。

注意

如果要求符合具有 API 中所定義之選項方法的作業,將不會執行與 CORS 原則相關聯的執行前要求處理邏輯。 因此,這類作業可以用來執行自訂的前置處理邏輯。

CORS 可讓瀏覽器和伺服器互動,以決定是否允許特定的跨原始來源要求 (例如,從網頁上的 JavaScript 對其他網域提出的 XMLHttpRequests 呼叫)。 這比只允許相同原始來源的要求更有彈性,也比允許所有跨原始來源的要求更安全。

您必須套用 CORS 原則,才能在開發人員入口網站中啟用互動式主控台。 如需詳細資訊,請參閱 開發人員入口網站檔

原則陳述式

<cors allow-credentials="false|true" terminate-unmatched-request="true|false">
    <allowed-origins>
        <origin>origin uri</origin>
    </allowed-origins>
    <allowed-methods preflight-result-max-age="number of seconds">
        <method>http verb</method>
    </allowed-methods>
    <allowed-headers>
        <header>header name</header>
    </allowed-headers>
    <expose-headers>
        <header>header name</header>
    </expose-headers>
</cors>

範例

此範例示範如何支援事前要求,例如具有自訂標頭或 GET 和 POST 以外方法的要求。 若要支援自訂標頭和其他 HTTP 動詞命令,請使用 allowed-methodsallowed-headers 區段,如下列範例所示。

<cors allow-credentials="true">
    <allowed-origins>
        <!-- Localhost useful for development -->
        <origin>http://localhost:8080/</origin>
        <origin>http://example.com/</origin>
    </allowed-origins>
    <allowed-methods preflight-result-max-age="300">
        <method>GET</method>
        <method>POST</method>
        <method>PATCH</method>
        <method>DELETE</method>
    </allowed-methods>
    <allowed-headers>
        <!-- Examples below show Azure Mobile Services headers -->
        <header>x-zumo-installation-id</header>
        <header>x-zumo-application</header>
        <header>x-zumo-version</header>
        <header>x-zumo-auth</header>
        <header>content-type</header>
        <header>accept</header>
    </allowed-headers>
    <expose-headers>
        <!-- Examples below show Azure Mobile Services headers -->
        <header>x-zumo-installation-id</header>
        <header>x-zumo-application</header>
    </expose-headers>
</cors>

項目

名稱 描述 必要 預設
cors 根元素。 N/A
allowed-origins 包含可說明跨網域要求之允許來源的 origin 元素。 allowed-origins 可包含指定了 * 以允許任何來源的單一 origin 元素,或一或多個包含 URI 的 origin 元素。 N/A
原始 值可以是 * 以允許所有來源,或是 URI 以指定單一來源。 URI 必須包含配置、主機和連接埠。 Yes 如果 URI 中省略了連接埠,則會將連接埠 80 用於 HTTP,將連接埠 443 用於 HTTPS。
allowed-methods 如果允許 GET 或 POST 以外的方法,則需要此元素。 包含指定了所支援 HTTP 動詞命令的 method 元素。 值 * 表示所有方法。 No 如果這個區段不存在,則會支援 GET 和 POST。
method 指定 HTTP 動詞命令。 如果 allowed-methods 區段存在,則需要至少一個 method 元素。 N/A
allowed-headers 此元素包含指定了可包含在要求中之標頭名稱的 header 元素。 N/A
expose-headers 此元素包含指定了可供用戶端存取之標頭名稱的 header 元素。 N/A
header 指定標頭名稱。 如果 allowed-headersexpose-headers 區段存在,則該區段中需要至少一個 header 元素。 N/A

屬性

Name 描述 必要 預設
allow-credentials Access-Control-Allow-Credentials預檢回應中的標頭會設定為這個屬性的值,並影響用戶端在跨網域要求中提交認證的能力。 No false
終止-不相符-要求 這個屬性會控制不符合 CORS 原則設定的跨原始來源要求處理。 當選項要求被視為進入飛行要求,且不符合 CORS 原則設定時:如果屬性設定為,則會 true 立即以空的200正常回應來終止要求;如果屬性設定為 false ,請針對輸入專案的直接子系的其他範圍 CORS 原則檢查輸入,並加以套用。 如果找不到 CORS 原則,請使用空的 200 OK 回應來終止要求。 當 GET 或 HEAD 要求包含原始標頭 (,因此會處理為跨原始來源的要求) 且不符合 CORS 原則設定:如果屬性設為,則會 true 立即以空的200正常回應結束要求;如果屬性設定為 false ,則允許要求正常進行,且不會將 CORS 標頭新增至回應。 No true
preflight-result-max-age Access-Control-Max-Age預檢回應中的標頭會設定為這個屬性的值,並影響使用者代理程式快取預先傳送回應的能力。 No 0

使用方式

此原則可用於下列原則區段範圍

  • 原則區段︰ inbound
  • 原則範圍: 所有範圍

JSONP

jsonp 原則會將 JSON 與補充的 (JSONP) 支援加入至作業或 API,以允許來自 JavaScript 瀏覽器型用戶端的跨網域呼叫。 JSONP 是 JavaScript 程式中使用的方法,可從位於不同網域的伺服器要求資料。 JSONP 會略過大多數網頁瀏覽器中規定必須在相同網域內才能存取網頁的限制。

原則陳述式

<jsonp callback-parameter-name="callback function name" />

範例

<jsonp callback-parameter-name="cb" />

如果呼叫方法時未指定回呼參數 ?cb=XXX,則會傳回一般 JSON (沒有函式呼叫包裝函式)。

如果加上回呼參數 ?cb=XXX,則會傳回 JSONP 結果,在回呼函數旁邊包裝原始的 JSON 結果,例如 XYZ('<json result goes here>');

項目

名稱 描述 必要
jsonp 根元素。 Yes

屬性

Name 描述 必要 預設
callback-parameter-name 跨網域 JavaScript 函數呼叫,開頭加上函數所在的完整網域名稱。 N/A

使用方式

此原則可用於下列原則區段範圍

  • 原則區段︰ 輸出
  • 原則範圍: 所有範圍

下一步

如需使用原則的詳細資訊,請參閱︰