如何设置或编辑 Azure API 管理策略

适用于：所有 API 管理层级

本文介绍如何在 Azure 门户中通过编辑策略定义来配置 API 管理实例中的策略。 每个策略定义是一个 XML 文档，描述针对 API 请求或响应按顺序运行的入站和出站语句序列。

门户中的策略编辑器提供引导式窗体，API 发布者可以使用这些窗体在策略定义中添加和编辑策略。 你还可以直接在策略代码编辑器中编辑 XML。

有关策略的详细信息：

• 策略概述
• 策略参考，其中提供了策略语句及其设置的完整列表
• 策略片段存储库
• Azure API 管理策略工具包
• 使用 Microsoft Copilot in Azure 创作策略

先决条件

如果你没有 API 管理实例和后端 API，请参阅：

• 创建一个 Azure API 管理实例
• 导入和发布 API

转到你的 API 管理实例

1. 在 Azure 门户中，搜索并选择“API 管理服务”：

   

2. 在“API 管理服务”页上，选择你的 API 管理实例：

   

在门户中配置策略

以下示例演示如何使用门户的策略编辑器中的两个选项配置策略：

• 基于引导式表单的编辑器，可简化配置大量策略
• 代码编辑器，可在其中直接添加或编辑 XML

在此示例中，策略将筛选来自特定传入 IP 地址的请求。 筛选范围限定为所选 API。

若要配置策略，请执行以下操作：

在不同的范围配置策略

API 管理让你可以在每个策略部分灵活地在多个范围配置策略定义。

全局范围

在您的 API 管理实例中，已将全局范围配置为针对所有 API。

1. 在 API 管理实例的左侧导航栏中，选择“API”“所有 API”。

2. 选择“设计”选项卡。

   

3. 在策略部分，选择“+ 添加策略”以使用表单编辑的策略编辑器，或选择“</>”（代码编辑器）图标直接添加和编辑 XML。

4. 选择“保存”以立即将更改传播到 API 管理网关。

产品范围

产品范围是针对选定的产品配置的。

1. 在左侧菜单中选择“产品”，然后选择要对其应用策略的产品。

2. 在产品窗口中选择“策略”。

   

3. 在策略部分，选择+ 添加策略以使用基于窗体的策略编辑器，或选择</>（代码编辑器）图标直接添加和编辑 XML。

4. 选择“保存”以立即将更改传播到 API 管理网关。

API 范围

API 范围是针对选定 API 的所有操作配置的。

1. 在 API 管理实例的左侧导航栏中选择“API”，然后选择要对其应用策略的 API。

2. 选择“设计”选项卡。

3. 选择所有操作。

   

4. 在策略部分，选择“+ 添加策略”以使用基于窗体的策略编辑器，或选择</>（代码编辑器）图标直接添加和编辑XML。

5. 选择“保存”以立即将更改传播到 API 管理网关。

操作范围

操作范围是针对选定的 API 操作配置的。

1. 在 API 管理实例的左侧导航栏中，选择“API”。

2. 选择“设计”选项卡。

3. 选择要将策略应用到的操作。

   

4. 在策略部分，选择“+ 添加策略”以使用基于表单的策略编辑器，或选择“</>”（代码编辑器）图标直接添加和编辑 XML。

5. 选择“保存”以立即将更改传播到 API 管理网关。

重复使用策略配置

可以在 API 管理实例中创建可重复使用的策略片段。 策略片段是包含一个或多个策略配置的 XML 元素。 策略片段有助于以一致的方式配置策略并维护策略定义，而无需重复或重新键入 XML 代码。

使用 include-fragment 策略在策略定义中插入策略片段。

使用 base 元素设置策略评估顺序

如果在多个范围内配置策略定义，则可将多个策略应用到 API 请求或响应。 根据不同范围内策略的应用顺序，请求或响应的转换可能不同。

在 API 管理中，通过在每个范围的策略定义中放置 base 元素来确定策略评估顺序。 base 元素继承处于下一个更宽泛（父）范围的该部分中配置的策略。 base 元素默认包含在每个策略部分。

若要使用策略编辑器修改策略评估顺序，请执行以下操作：

1. 从您配置的最窄范围的定义开始，API 管理会首先应用它。

   例如，使用在全局范围和 API 范围配置的策略定义时，请先处理 API 范围的配置。

2. 将 base 元素放在某个部分，以确定要从父范围的相应部分的哪个位置继承所有策略。

   例如，在 API 范围配置的 inbound 部分，放置一个 base 元素，以控制要在哪个位置继承全局范围的 inbound 部分中配置的策略。 在以下示例中，从全局范围继承的策略将先应用，然后再应用 ip-filter 策略。

   <policies>
     <inbound>
         <base />
           <ip-filter action="allow">
               <address>10.100.7.1</address>
           </ip-filter>
     </inbound>
     [...]
   </policies>
   

   注意

   • 可以在部分中的任何策略元素之前或之后放置 base 元素。
   • 若要防止从父范围继承策略，请删除 base 元素。 在大多数情况下，不建议这样做。 但是，在某些情况下，它可能非常有用，例如，当您希望对特定操作应用不同的策略，而不是针对于 API（涵盖所有操作的范围）所配置的策略时。

3. 在范围逐渐扩大的策略定义中继续配置 base 元素。

   全局范围的策略没有父范围，在其中使用 base 元素不起作用。

获取 Copilot 帮助

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

• Azure 中的 Microsoft Copilot - 在 Azure 门户中提供通过自然语言指令进行策略编写的协助。 在 API 管理的策略编辑器中创作策略，并要求 Copilot 解释策略部分。
• VS Code 中适用于 Azure 的 GitHub Copilot - 在 Visual Studio Code 中使用 Azure API 管理扩展时提供策略创作帮助，并在使用 适用于 Visual Studio Code 的 Azure API 管理扩展时加速策略配置。 使用自然语言向 Copilot 对话助手或 Copilot Edits（预览版）提供提示，以就地创建和优化策略定义。

示例提示：

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

Copilot 由 AI 提供支持，因此可能会带来意外和错误。 有关详细信息，请参阅 Copilot 常规使用常见问题解答。

相关内容

若要详细了解如何使用策略，请参阅：

• 教程：转换和保护 API
• 策略参考，其中提供了策略语句及其设置的完整列表
• 策略表达式
• 设置或编辑策略
• 重复使用策略配置
• 策略片段存储库
• Azure API 管理策略工具包
• 获取 Copilot 帮助以创建、解释策略和排查策略问题