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>
    <cross-domain>
        <allow-http-request-headers-from domain='*' headers='*' />
    </cross-domain>
</cross-domain>  

元素Elements

NameName 说明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.

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.

策略语句Policy statement

<cors allow-credentials="false|true">  
    <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

NameName 说明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. No 如果此部分不存在,则支持 GET 和 POST。If this section is not present, GET and POST are supported.
方法method 指定 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

NameName 说明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
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

NameName 说明Description 必须Required
jsonpjsonp 根元素。Root element. Yes

属性Attributes

NameName 说明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: