Azure API 管理中的策略Policies in Azure API Management

在 Azure API 管理 (APIM) 中,策略是一项强大的系统功能,允许发布者通过配置更改 API 的行为。In Azure API Management (APIM), policies are a powerful capability of the system that allow the publisher to change the behavior of the API through configuration. 策略是一组语句,在请求或响应 API 时按顺序执行。Policies are a collection of Statements that are executed sequentially on the request or response of an API. 常用的语句包括从 XML 到 JSON 的格式转换,并调用速率限制来限制从一名开发人员传入的调用量。Popular Statements include format conversion from XML to JSON and call rate limiting to restrict the amount of incoming calls from a developer. 许多策略开箱即用。Many more policies are available out of the box.

策略在网关内部应用,该网关位于 API 使用者和托管 API 之间。Policies are applied inside the gateway which sits between the API consumer and the managed API. 该网关接收所有请求,并通常将其原封不动地转发到基础 API。The gateway receives all requests and usually forwards them unaltered to the underlying API. 但是策略可以将更改应用于入站的请求和出站响应。However a policy can apply changes to both the inbound request and outbound response.

在任何 API 管理策略中,策略表达式可以用作属性值或文本值,除非该策略另外指定。Policy expressions can be used as attribute values or text values in any of the API Management policies, unless the policy specifies otherwise. 某些策略(如控制流设置变量策略)基于策略表达式。Some policies such as the Control flow and Set variable policies are based on policy expressions. 有关详细信息,请参阅高级策略策略表达式For more information, see Advanced policies and Policy expressions.

了解策略配置 Understanding policy configuration

策略定义是一个简单的 XML 文档,用于描述一个入站和出站语句序列。The policy definition is a simple XML document that describes a sequence of inbound and outbound statements. 可以直接在定义窗口中编辑 XML。The XML can be edited directly in the definition window. 右侧提供语句的列表,同时启用适用于当前范围的语句并突出显示。A list of statements is provided to the right and statements applicable to the current scope are enabled and highlighted.

单击启用的语句会在定义视图中的光标位置添加相应的 XML。Clicking an enabled statement will add the appropriate XML at the location of the cursor in the definition view.


如果无法启用要添加的策略,请确保为该策略设置的范围是正确的。If the policy that you want to add is not enabled, ensure that you are in the correct scope for that policy. 每个策略语句都设计有特定的使用范围,需在特定的策略部分使用。Each policy statement is designed for use in certain scopes and policy sections. 若要查看某个策略的策略部分和范围,请参阅策略参考中该策略的“用法”部分。To review the policy sections and scopes for a policy, check the Usage section for that policy in the Policy Reference.

配置划分为 inboundbackendoutboundon-errorThe configuration is divided into inbound, backend, outbound, and on-error. 指定的策略语句系列将按请求和响应顺序执行。The series of specified policy statements is executed in order for a request and a response.

    <!-- statements to be applied to the request go here -->
    <!-- statements to be applied before the request is forwarded to 
         the backend service go here -->
    <!-- statements to be applied to the response go here -->
    <!-- statements to be applied if there is an error condition go here -->

如果在处理请求的过程中出错,则会忽略 inboundbackendoutbound 部分的其余步骤,跳到 on-error 部分执行相关语句。If there is an error during the processing of a request, any remaining steps in the inbound, backend, or outbound sections are skipped and execution jumps to the statements in the on-error section. 将策略语句置于 on-error 部分以后,即可使用 context.LastError 属性查看错误、使用 set-body 策略检查和自定义错误响应,以及配置发生错误时的应对措施。By placing policy statements in the on-error section you can review the error by using the context.LastError property, inspect and customize the error response using the set-body policy, and configure what happens if an error occurs. 错误代码可针对内置步骤,也可针对在处理策略语句的过程中会发生的错误。There are error codes for built-in steps and for errors that may occur during the processing of policy statements. 有关详细信息,请参阅 Error handling in API Management policies(API 管理策略中的错误处理)。For more information, see Error handling in API Management policies.

如何配置策略 How to configure policies

有关如何配置策略的信息,请参阅设置或编辑策略For information on how to configure policies, see Set or edit policies.

策略参考Policy Reference

请参阅策略参考了解政策说明完整列表及其设置。See the Policy reference for a full list of policy statements and their settings.

策略示例Policy samples

请参阅策略示例获取更多代码示例。See Policy samples for more code examples.


应用在不同范围指定的策略Apply policies specified at different scopes

如果在全局级别有一个策略并且为 API 配置了一个策略,则只要使用该特定 API,这两种策略都会被应用。If you have a policy at the global level and a policy configured for an API, then whenever that particular API is used both policies will be applied. API 管理允许通过基础元素实现组合策略声明的确定性排序。API Management allows for deterministic ordering of combined policy statements via the base element.

        <cross-domain />
        <base />
        <find-and-replace from="xyz" to="abc" />

在上述示例策略定义中,cross-domain 语句会在执行任何更高版本的策略前执行,之后是 find-and-replace 策略。In the example policy definition above, the cross-domain statement would execute before any higher policies which would in turn, be followed by the find-and-replace policy.

限制传入的请求Restrict incoming requests

要添加新的语句以限制到指定 IP 地址的入站请求,请将光标置于 inbound XML 元素的内容中,然后单击“限制调用方 IP”语句。To add a new statement to restrict incoming requests to specified IP addresses, place the cursor just inside the content of the inbound XML element and click the Restrict caller IPs statement.


这会将 XML 代码片段添加到 inbound 元素,提供如何配置该语句的指导。This will add an XML snippet to the inbound element that provides guidance on how to configure the statement.

<ip-filter action="allow | forbid">
    <address-range from="address" to="address"/>

要限制入站请求并接受来自 IP 地址 的那些,请修改 XML,如下所示:To limit inbound requests and accept only those from an IP address of modify the XML as follows:

<ip-filter action="allow">

后续步骤Next steps

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