API Management cross domain policies(API 管理跨域策略)API Management cross domain policies

本主题提供以下 API 管理策略的参考。This topic provides a reference for the following API Management policies. 有关添加和配置策略的信息,请参阅 API 管理中的策略For information on adding and configuring policies, see Policies in API Management.

跨域策略Cross domain policies

  • 允许跨域调用 - 使 API 能够通过 Adobe Flash 和基于 Microsoft Silverlight 浏览器的客户端进行访问。Allow cross-domain calls - Makes the API accessible from Adobe Flash and Microsoft Silverlight browser-based clients.
  • CORS - 向操作或 API 添加跨源资源共享 (CORS) 支持,允许从基于浏览器的客户端进行跨域调用。CORS - Adds cross-origin resource sharing (CORS) support to an operation or an API to allow cross-domain calls from browser-based clients.
  • JSONP - 向操作或 API 添加填充型 JSON (JSONP) 支持,允许从基于 JavaScript 浏览器的客户端进行跨域调用。JSONP - Adds JSON with padding (JSONP) support to an operation or an API to allow cross-domain calls from JavaScript browser-based clients.

允许跨域调用Allow cross-domain calls

使用 cross-domain 策略使 API 能够通过 Adobe Flash 和基于 Microsoft Silverlight 浏览器的客户端进行访问。Use the cross-domain policy to make the API accessible from Adobe Flash and Microsoft Silverlight browser-based clients.

策略语句Policy statement

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

示例Example

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

元素Elements

名称Name 说明Description 必选Required
cross-domaincross-domain 根元素。Root element. 子元素必须符合 Adobe 跨域策略文件规范Child elements must conform to the Adobe cross-domain policy file specification. Yes

使用情况Usage

此策略可在以下策略范围中使用。This policy can be used in the following policy sections and scopes.

  • 策略节: 入站Policy sections: inbound
  • 策略范围: 所有范围Policy scopes: all scopes

CORSCORS

cors 策略向操作或 API 添加跨源资源共享 (CORS) 支持,以便从基于浏览器的客户端执行跨域调用。The cors policy adds cross-origin resource sharing (CORS) support to an operation or an API to allow cross-domain calls from browser-based clients.

备注

如果请求与 API 中定义的 OPTIONS 方法的操作匹配,则将不执行与 CORS 策略关联的预检请求处理逻辑。If request matches an operation with an OPTIONS method defined in the API, pre-flight request processing logic associated with CORS policies will not be executed. 因此,此类操作可用于实现自定义预检处理逻辑。Therefore, such operations can be used to implement custom pre-flight processing logic.

CORS 允许浏览器与服务器交互,并确定是否允许特定的跨源请求(例如,通过某个网页上的 JavaScript 对其他域执行 XMLHttpRequests 调用)。CORS allows a browser and a server to interact and determine whether or not to allow specific cross-origin requests (i.e. XMLHttpRequests calls made from JavaScript on a web page to other domains). 与只允许同源请求相比,它的灵活性更高,而且比允许所有跨源请求更安全。This allows for more flexibility than only allowing same-origin requests, but is more secure than allowing all cross-origin requests.

你需要应用 CORS 策略,以便在开发人员门户中启用交互式控制台。You need to apply the CORS policy to enable the interactive console in the developer portal. 有关详细信息,请参阅开发人员门户文档Refer to the developer portal documentation for details.

策略语句Policy statement

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

示例Example

此示例演示如何支持预检请求,例如那些具有自定义标头或 GET 和 POST 之外的方法的预检请求。This example demonstrates how to support pre-flight requests, such as those with custom headers or methods other than GET and POST. 若要支持自定义标头和其他 HTTP 谓词,请使用 allowed-methodsallowed-headers 部分,如以下示例所示。To support custom headers and additional HTTP verbs, use the allowed-methods and allowed-headers sections as shown in the following example.

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

元素Elements

名称Name 说明Description 必须Required 默认Default
corscors 根元素。Root element. Yes 不适用N/A
allowed-originsallowed-origins 包含的 origin 元素说明了跨域请求的允许来源。Contains origin elements that describe the allowed origins for cross-domain requests. allowed-origins 可能包含单个 origin 元素,该元素指定允许任何源的 *,或者包含一个或多个内含 URI 的 origin 元素。allowed-origins can contain either a single origin element that specifies * to allow any origin, or one or more origin elements that contain a URI. Yes 不适用N/A
originorigin 值可以是允许所有源的 *,或者是用于指定单个源的 URI。The value can be either * to allow all origins, or a URI that specifies a single origin. URI 必须包括方案、主机和端口。The URI must include a scheme, host, and port. Yes 如果 URI 中省略了端口,则端口 80 用于 HTTP,端口 443 用于 HTTPS。If the port is omitted in a URI, port 80 is used for HTTP and port 443 is used for HTTPS.
allowed-methodsallowed-methods 如果允许 GET 或 POST 之外的方法,则此元素是必需的。This element is required if methods other than GET or POST are allowed. 包含 method 元素,用于指定支持的 HTTP 谓词。Contains method elements that specify the supported HTTP verbs. * 指示所有方法。The value * indicates all methods. No 如果此部分不存在,则支持 GET 和 POST。If this section is not present, GET and POST are supported.
methodmethod 指定 HTTP 谓词。Specifies an HTTP verb. 如果 allowed-methods 部分存在,则至少一个 method 元素是必需。At least one method element is required if the allowed-methods section is present. 不适用N/A
allowed-headersallowed-headers 此元素包含 header 元素,用于指定可以包括在请求中的标头的名称。This element contains header elements specifying names of the headers that can be included in the request. No 不适用N/A
expose-headersexpose-headers 此元素包含 header 元素,用于指定可以通过客户端访问的标头的名称。This element contains header elements specifying names of the headers that will be accessible by the client. No 不适用N/A
标头header 指定标头名称。Specifies a header name. 如果节存在,则 allowed-headersexpose-headers 中至少一个 header 元素是必需。At least one header element is required in allowed-headers or expose-headers if the section is present. 不适用N/A

属性Attributes

名称Name 说明Description 必须Required 默认Default
allow-credentialsallow-credentials 预检响应中的 Access-Control-Allow-Credentials 标头将设置为此属性的值,会影响客户端在跨域请求中提交凭据的功能。The Access-Control-Allow-Credentials header in the preflight response will be set to the value of this attribute and affect the client's ability to submit credentials in cross-domain requests. No falsefalse
terminate-unmatched-requestterminate-unmatched-request 此属性控制与 CORS 策略设置不匹配的跨域请求的处理。This attribute controls the processing of cross-origin requests that don't match the CORS policy settings. 当 OPTIONS 请求作为预检请求进行处理且与 CORS 策略设置不匹配时:如果属性设置为 true,请立即终止请求并返回空的 200 OK 响应;如果属性设置为 false,请检查入站以查找其他作用域内 CORS 策略(这些策略是 inbound 元素的直接子级),并应用这些策略。When OPTIONS request is processed as a pre-flight request and doesn't match CORS policy settings: If the attribute is set to true, immediately terminate the request with an empty 200 OK response; If the attribute is set to false, check inbound for other in-scope CORS policies that are direct children of the inbound element and apply them. 如果找不到 CORS 策略,请终止请求并返回空的 200 OK 响应。If no CORS policies are found, terminate the request with an empty 200 OK response. 当 GET 或 HEAD 请求包含源标头(并因此作为跨域请求进行处理)且与 CORS 策略设置不匹配时:如果属性设置为 true,请立即终止请求并返回空的 200 OK 响应;如果属性设置为 false,则允许请求正常进行,并且不在响应中添加 CORS 标头。When GET or HEAD request includes the Origin header (and therefore is processed as a cross-origin request) and doesn't match CORS policy settings: If the attribute is set to true, immediately terminate the request with an empty 200 OK response; If the attribute is set to false, allow the request to proceed normally and don't add CORS headers to the response. No true
preflight-result-max-agepreflight-result-max-age 预检响应中的 Access-Control-Max-Age 标头将设置为此属性的值,会影响用户代理缓存预检响应的功能。The Access-Control-Max-Age header in the preflight response will be set to the value of this attribute and affect the user agent's ability to cache pre-flight response. No 00

使用情况Usage

此策略可在以下策略范围中使用。This policy can be used in the following policy sections and scopes.

  • 策略节: 入站Policy sections: inbound
  • 策略范围: 所有范围Policy scopes: all scopes

JSONPJSONP

jsonp 策略向操作或 API 添加填充型 JSON (JSONP) 支持,以便从基于 JavaScript 浏览器的客户端执行跨域调用。The jsonp policy adds JSON with padding (JSONP) support to an operation or an API to allow cross-domain calls from JavaScript browser-based clients. JSONP 是 JavaScript 程序中使用的方法,用于从不同域中的服务器请求数据。JSONP is a method used in JavaScript programs to request data from a server in a different domain. JSONP 规避了大多数 Web 浏览器强制实施的只能在同一域中访问网页的限制。JSONP bypasses the limitation enforced by most web browsers where access to web pages must be in the same domain.

策略语句Policy statement

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

示例Example

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

如果调用此方法时没有回调参数 ?cb=XXX,该方法将返回无格式 JSON(不带函数调用包装)。If you call the method without the callback parameter ?cb=XXX it will return plain JSON (without a function call wrapper).

如果添加回调参数 ?cb=XXX,它将返回 JSONP 结果,并使用原始 JSON 结果包装回调函数,例如 XYZ('<json result goes here>');If you add the callback parameter ?cb=XXX it will return a JSONP result, wrapping the original JSON results around the callback function like XYZ('<json result goes here>');

元素Elements

名称Name 说明Description 必需Required
jsonpjsonp 根元素。Root element. Yes

属性Attributes

名称Name 说明Description 必须Required 默认Default
callback-parameter-namecallback-parameter-name 以函数所在的完全限定域名为前缀的跨域 JavaScript 函数调用。The cross-domain JavaScript function call prefixed with the fully qualified domain name where the function resides. Yes 空值N/A

使用情况Usage

此策略可在以下策略范围中使用。This policy can be used in the following policy sections and scopes.

  • 策略段: 出站Policy sections: outbound
  • 策略范围: 所有范围Policy scopes: all scopes

后续步骤Next steps

有关如何使用策略的详细信息,请参阅:For more information working with policies, see: