在 API 管理策略定义中重用策略配置

适用于:所有 API 管理层级

本文介绍如何在 API 管理策略定义中创建和使用策略片段。 策略片段是集中管理的、可重用的 XML 片段,其中包含一个或多个 API 管理策略配置。

策略片段有助于以一致的方式配置策略并维护策略定义,而无需重复或重新键入 XML 代码。

策略片段:

  • 必须是包含一个或多个策略配置的有效 XML
  • 可能包括策略表达式(如果引用的策略支持这类表达式)
  • 使用 include-fragment 策略按原样插入到策略定义中

的限制:

  • 策略片段不能包含策略部分标识符(<inbound><outbound> 等)或 <base/> 元素。
  • 目前,策略片段无法嵌套另一个策略片段。
  • 策略片段的最大大小为 32 KB。

先决条件

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

虽然并非必需,但可能需要配置一个或多个策略定义。 创建策略片段时,可以从这些定义中复制策略元素。

转到你的 API 管理实例

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

    选择“API 管理服务”

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

    选择你的 API 管理实例

创建策略片段

  1. 在 API 管理实例左侧导航的 API 下,选择“策略片段”>“+ 创建”。

  2. 在“创建新的策略片段”窗口中,输入策略片段的名称和可选的描述。 该名称在 API 管理实例中必须是唯一的。

    示例名称:ForwardContext

  3. 在 XML 策略片段编辑器中,在 <fragment></fragment> 标记之间键入或粘贴一个或多个策略 XML 元素。

    屏幕截图显示了“创建新策略片段”窗体。

    例如,以下片段包含一个 set-header 策略配置,用于将上下文信息转发到后端服务。 此片段将包含在入站策略部分中。 此示例中的策略表达式访问内置 context 变量

    <fragment>
        <set-header name="x-request-context-data" exists-action="override">
          <value>@(context.User.Id)</value>
          <value>@(context.Deployment.Region)</value>
        </set-header>
    </fragment>
    
  4. 选择“创建”。 该片段被添加到策略片段列表中。

在策略定义中包含片段

配置 include-fragment 策略以在策略定义中插入策略片段。 有关策略定义的详细信息,请参阅设置或编辑策略

  • 可在任何范围和任何策略部分中包含一个片段,只要该片段中的一个或多个基础策略支持该用法。
  • 可以在策略定义中包含多个策略片段。

例如,在入站策略部分插入名为 ForwardContext 的策略片段:

<policies>
    <inbound>
        <include-fragment fragment-id="ForwardContext" />
        <base />
    </inbound>
[...]

提示

要查看策略定义中显示的包含片段的内容,请在策略编辑器中选择“计算有效策略”。

管理策略片段

创建策略分片后,可以随时查看和更新策略片段的属性,也可随时删除策略片段。

查看策略片段的属性:

  1. 在 API 管理实例的左侧导航中,在“API”下选择“策略片段”。 选择片段的名称。
  2. 在概述页面上,查看“策略文档参考”以查看包含该片段的策略定义。
  3. 在“属性”页面上,查看策略片段的名称和说明。 以后无法更改此名称。

编辑策略片段:

  1. 在 API 管理实例的左侧导航中,在“API”下选择“策略片段”。 选择片段的名称。
  2. 选择“策略编辑器”。
  3. 更新片段中的语句,然后选择“应用”。

注意

更新会影响包含片段的所有策略定义。

删除策略片段:

  1. 在 API 管理实例的左侧导航中,在“API”下选择“策略片段”。 选择片段的名称。
  2. 查看包含片段的策略定义的策略文档参考。 必须先从所有策略定义中删除片段引用,然后才能删除片段。
  3. 删除所有引用后,选择“删除”。

有关使用策略的详细信息,请参阅: