如何设置或编辑 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 解释策略部分。
• Visual Studio Code 中的 GitHub Copilot for Azure 提供了 Visual Studio Code 中的策略创作帮助，你可以使用 适用于 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 帮助以创建、解释策略和排查策略问题