Azure API 管理中的策略
适用于:所有 API 管理层级
在 Azure API 管理中,API 发布者可以使用策略通过配置来更改 API 行为。 策略是针对 API 请求或响应按顺序运行的一系列语句。 API Management 现成提供 50 多个策略,可用于解决常见 API 场景,例如身份验证、速率限制、缓存,以及请求或响应的转换。 有关完整列表,请参阅 API 管理策略参考。
常见的策略包括:
- 将格式从 XML 转换为 JSON
- 调用速率限制以限制开发人员的传入调用数
- 筛选来自特定 IP 地址的请求
策略在网关内部应用,该网关位于 API 使用者和托管 API 之间。 当网关接收请求并将其原封不动地转发到基础 API 后,策略可以向入站请求和出站响应应用更改。
了解策略配置
策略定义是简单的 XML 文档,用于描述要应用于请求和响应的语句序列。 为了帮助你配置策略定义,门户提供了以下选项:
- 基于窗体的引导式编辑器,用于简化常用策略的配置,无需编写 XML 代码
- 代码编辑器,可在其中插入 XML 代码片段或直接编辑 XML
有关配置策略的详细信息,请参阅设置或编辑策略。
策略 XML 配置分为 inbound
、backend
、outbound
和 on-error
节。 指定的策略语句系列将针对请求和响应按顺序执行。
<policies>
<inbound>
<!-- statements to be applied to the request go here -->
</inbound>
<backend>
<!-- statements to be applied before the request is forwarded to
the backend service go here -->
</backend>
<outbound>
<!-- statements to be applied to the response go here -->
</outbound>
<on-error>
<!-- statements to be applied if there is an error condition go here -->
</on-error>
</policies>
有关策略 XML 示例,请参阅 API 管理策略片段存储库。
错误处理。
如果在处理请求的过程中出现错误:
- 将跳过
inbound
、backend
或outbound
部分中所有的剩余步骤。 - 执行将跳转到
on-error
部分中的语句。
通过将策略语句置于 on-error
部分,你可以:
- 使用
context.LastError
属性查看错误。 - 使用
set-body
策略检查和自定义错误响应。 - 配置发生错误时的应对措施。
有关详细信息,请参阅 Error handling in API Management policies(API 管理策略中的错误处理)。
策略表达式
在任何 API 管理策略中,策略表达式都可以用作属性值或文本值,除非该策略另外指定。 策略表达式为:
- 括在
@(expression)
中的单个 C# 语句,或 - 括在
@{expression}
中的多语句 C# 代码块,它返回一个值
每个表达式可以访问隐式提供的 context
变量以及允许的 .NET Framework 类型子集。
策略表达式提供一种复杂的方式用于控制流量和修改 API 行为,而无需编写专用的代码或修改后端服务。 某些策略(如“控制流”和“设置变量”)基于策略表达式。
作用域
API 管理允许在以下范围(从最宽到最窄)定义策略:
- 全局(所有 API)
- 工作区(与所选工作区关联的所有 API)
- 产品(与选定产品关联的所有 API)
- API(API 中的所有操作)
- 操作(API 中的单个操作)
配置某个策略时,必须先选择该策略的应用范围。
使用须知
要精细控制不同的 API 使用者,可以在多个范围配置策略定义
并非所有策略在每个范围和策略部分都受支持
在多个范围内配置策略定义时,可以通过放置
base
元素来控制策略继承和每个策略部分中的策略评估顺序应用于 API 请求的策略也会受到请求上下文的影响,包括请求中使用的订阅密钥存在与否、订阅密钥的 API 或产品范围以及 API 或产品是否需要订阅。
注意
如果使用 API 范围的订阅、所有 API 订阅或内置全访问订阅,则产品范围内配置的策略不会应用于来自该订阅的请求。
有关详细信息,请参阅:
GraphQL 解析程序策略
在 API 管理中,使用范围限定为 GraphQL 架构中的特定操作类型和字段配置 GraphQL 解析程序。
- 目前,API 管理支持指定 HTTP API、Cosmos DB 或 Azure SQL 数据源的 GraphQL 解析程序。 例如,使用元素配置单个
http-data-source
策略,以指定对 HTTP 数据源的请求(以及选择性地指定来自 HTTP 数据源的响应)。 - 不能在其他范围(如 API、产品或所有 API)的策略定义中包含解析程序策略。 它也不会继承在其他范围配置的策略。
- 网关会在策略执行管道中任何已配置的
inbound
和backend
策略之后评估解析程序范围的策略。
有关详细信息,请参阅配置 GraphQL 解析程序。
示例
应用在不同范围指定的策略
如果在全局级别有一个策略并且为 API 配置了一个策略,则只要使用该特定 API,就可以应用这两个策略。 API 管理允许通过 base
元素实现组合策略声明的确定性排序。
API 范围的策略定义示例:
<policies>
<inbound>
<cross-domain />
<base />
<find-and-replace from="xyz" to="abc" />
</inbound>
</policies>
在上述示例策略定义中:
- 首先执行
cross-domain
语句。 - 在应用更宽泛范围的所有策略之后执行
find-and-replace
策略。
注意
如果删除 API 范围的 base
元素,则只会应用在 API 范围配置的策略。 不会应用产品范围策略或全局范围策略。
使用策略表达式修改请求
以下示例使用策略表达式和 set-header
策略将用户数据添加到传入的请求。 添加的标头包含与请求中的订阅密钥关联的用户 ID,以及处理请求的网关所在的区域。
<policies>
<inbound>
<base />
<set-header name="x-request-context-data" exists-action="override">
<value>@(context.User.Id)</value>
<value>@(context.Deployment.Region)</value>
</set-header>
</inbound>
</policies>
后续步骤
有关使用策略的详细信息,请参阅:
- 教程:转换和保护 API
- 策略参考,其中提供了策略语句及其设置的完整列表
- 策略表达式
- 设置或编辑策略
- 策略示例