通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

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 解析程序。

使用 Microsoft Azure Copilot（预览版）获取有关创建策略的帮助

Microsoft Azure Copilot（预览版）为 Azure API Management 提供了策略创作功能。 在 API Management 策略编辑器的上下文中使用 Azure Copilot，以在无需了解语法的情况下创建与你的特定需求匹配的策略，或者向你解释已配置的策略。

你可以提示 Azure Copilot 生成策略定义，然后将结果复制到策略编辑器中并进行任何必要的调整。 提出问题以获取对不同选项的见解、修改所提供的策略或阐明你已有的策略。 了解详细信息

示例

应用在不同范围指定的策略

如果在全局级别有一个策略并且为 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>

相关内容

有关使用策略的详细信息，请参阅：