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

Azure API 管理中的策略

适用于：所有 API 管理层级

在 Azure API 管理中，API 发布者可以使用 策略通过配置来更改 API 行为。 本文介绍如何使用策略。

策略是针对 API 请求或响应按顺序运行的一系列语句。 API 管理提供了 75 个以上的现装策略，你可以配置这些策略来解决常见的 API 方案，例如身份验证、速率限制、缓存和请求或响应的转换。 有关完整列表，请参阅 API 管理策略参考。

注意

API 管理策略不同于 Azure Policy 定义。 API 管理策略是在网关内执行的运行时规则，用于转换、验证、保护和路由 API 请求和响应。 相比之下，Azure Policy是一项治理服务，它评估并强制执行Azure资源（如具有组织或法规要求的 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's 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 管理策略中，策略表达式都可以用作属性值或文本值，除非该策略另外指定。 策略表达式是以下项之一：

  • 单个 C# 语句被括在 @(expression) 中
  • 一个被@{expression}标签括起来的多语句 C# 代码块，该代码块返回一个值。

每个表达式可以访问隐式提供的 context 变量以及允许的 .NET Framework 类型子集。

策略表达式提供一种复杂的方式用于控制流量和修改 API 行为，而无需编写专用的代码或修改后端服务。 某些策略（如“控制流”和“设置变量”）基于策略表达式。

作用域

API 管理使你能够在以下范围内定义策略，从最宽到最窄提供：

  • 全局（所有 API）
  • 工作区（与所选工作区关联的所有 API）
  • 产品（与选定产品关联的所有 API）
  • API（API 中的所有操作）
  • 操作（API 中的单个操作）

配置某个策略时，必须先选择该策略的应用范围。

说明五个策略范围的示意图。

使用须知

  • 对于不同 API 使用者的精细控制，可以在多个范围内配置策略定义。

  • 并非所有策略在每个范围和策略部分都受支持。

  • 在多个范围内配置策略定义时，可以通过放置 base 元素来控制每个策略部分中的策略继承和策略评估顺序。

    重要

    最佳做法是在每个策略部分的开头包含一个 base 元素，用于从父范围继承策略。 这可确保在较高级别定义的任何策略都不会无意中被重写或忽略。 内置 Azure Policy 定义 (API Management policies should inherit parent scope policies using <base/>) 可用于审核或强制实施此最佳做法。

  • 应用于 API 请求的策略也会受到请求上下文的影响，包括请求中使用的订阅密钥存在与否、订阅密钥的 API 或产品范围以及 API 或产品是否需要订阅。

    注意

    如果使用 API 范围的订阅、所有 API 订阅或内置全访问订阅，则产品范围内配置的策略不会应用于来自该订阅的请求。

有关详细信息，请参阅：

GraphQL 解析程序策略

在 API 管理中， GraphQL 解析程序 配置了范围限定为 GraphQL 架构中特定作类型和字段的策略。

  • 目前，API 管理支持指定 HTTP API、Azure Cosmos DB 或 Azure SQL 数据源的 GraphQL 解析程序。 例如，您可以配置一个包含元素的单个 http-data-source 策略，以指定对 HTTP 数据源的请求（以及可选的响应）。
  • 不能在其他范围（例如 API、产品或所有 API）的策略定义中包含解析程序策略。 该策略也不会继承在其他范围内配置的策略。
  • 网关会在策略执行管道中任何已配置的 inbound 和 backend 策略之后评估解析程序范围的策略。

有关详细信息，请参阅配置 GraphQL 解析程序。

获取 Copilot 帮助

可以从 Copilot 获取 AI 帮助，以创建和编辑 API 管理策略定义。 可以使用 Copilot 创建和更新符合特定要求的策略，而无需知道 XML 语法。 还可以获取现有策略的说明。 Copilot 可以帮助你转换你可能在其他 API 管理解决方案中配置的策略。

示例提示：

Generate a policy that adds an Authorization header to the request with a Bearer token.

Copilot 由 AI 提供支持，因此可能会带来意外和错误。 有关详细信息，请参阅 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>

相关内容

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

  • Last updated on