在 Azure API 管理策略中使用命名值

适用于：所有 API 管理层级

API 管理策略是一项强大的系统功能，允许发布者通过配置更改 API 的行为。 策略是一组语句，在请求或 API 的响应时按顺序执行。 可以使用文字文本值、策略表达式和命名值构造策略语句。

“命名值”是每个 API 管理实例中的名称/值对的全局集合。 对该集合中的项数没有施加限制。 命名值可以用来管理所有 API 配置和策略中的常量字符串值和机密。

值类型

明文值或机密可以包含策略表达式。 例如，表达式 @(DateTime.Now.ToString()) 返回包含当前日期和时间的一个字符串。

有关命名值特性的详细信息，请参阅 API 管理 REST API 参考。

密钥保管库机密

机密值可以存储为 API 管理中的加密字符串（自定义机密），也可以通过引用 Azure Key Vault 中的机密进行存储。

建议使用密钥保管库机密，因为它有助于提高 API 管理安全性：

• 密钥保管库中存储的机密可以在服务之间重复使用
• 可以为机密应用精细访问策略
• 在密钥保管库中更新的机密会自动在 API 管理中轮换。 在密钥保管库中更新后，API 管理中的命名值会在 4 小时内更新。 你还可以使用 Azure 门户或通过管理 REST API 手动刷新机密。

先决条件

• 如果尚未创建 API 管理服务实例，请参阅创建 API 管理服务实例。

密钥保管库集成的先决条件

• 如果还没有密钥保管库，请创建一个。 有关创建密钥保管库的步骤，请参阅快速入门：使用 Azure 门户创建密钥保管库。

  若要创建机密或将机密导入密钥保管库，请参阅快速入门：使用 Azure 门户在 Azure Key Vault 中设置和检索机密。

• 在 API 管理实例中启用系统分配的或用户分配的托管标识。

配置对密钥保管库的访问权限

1. 在门户中导航到你的密钥保管库。

2. 在左侧菜单中，选择“访问配置”，并记下配置的权限模型。

3. 根据权限模型，为 API 管理托管标识配置密钥保管库访问策略或 Azure RBAC 访问。

   添加密钥保管库访问策略：
   

   1. 在左侧菜单中，选择“访问策略”。
   2. 在“访问策略”页上，选择“+ 创建”。
   3. 在“权限”选项卡上的“机密权限”下，选中“获取”和“列出”，然后选择“下一步”。
   4. 在“主体”选项卡上的“选择主体”中，搜索托管标识的资源名称，然后选择“下一步”。 如果你使用系统分配的标识，则主体为你的 API 管理实例的名称。
   5. 再次选择“下一步”。 在“查看 + 创建”选项卡上，选择“创建”。

   配置 Azure RBAC 访问：
   

   1. 在左侧菜单中，选择“访问控制(IAM)”。
   2. 在“访问控制(IAM)”页上，选择“添加角色分配”。
   3. 在“角色”选项卡上，选择“密钥保管库机密用户”。
   4. 在“成员”选项卡上，选择“托管标识”>“+ 选择成员”。
   5. 在“选择托管标识”页上，选择系统分配的托管标识或与 API 管理实例关联的用户分配的托管标识，然后选择“选择”。
   6. 选择“查看 + 分配”。

Key Vault 防火墙要求

如果在密钥保管库上启用了 Key Vault 防火墙，则具有以下附加要求：

• 必须使用 API 管理实例的“系统分配的”托管标识来访问密钥保管库。

• 在 Key Vault 防火墙中，启用“允许受信任的 Microsoft 服务绕过此防火墙”选项。

• 在选择要添加到 Azure API 管理的证书或机密时，请确保允许本地客户端 IP 地址临时访问密钥保管库。 有关详细信息，请参阅配置 Azure Key Vault 网络设置。

  完成配置后，可以在密钥保管库防火墙中阻止客户端地址。

虚拟网络要求

如果 API 管理实例部署在虚拟网络中，则还应配置下列网络设置：

• 在 API 管理子网上，启用 Azure Key Vault 的服务终结点。
• 配置一个网络安全组 (NSG) 规则，以允许指向 AzureKeyVault 和 AzureActiveDirectory 服务标记的出站流量。

有关详细信息，请参阅在 VNet 中设置 Azure API 管理时使用的网络配置。

添加或编辑命名值

将密钥保管库机密添加到 API 管理

请参阅密钥保管库集成的先决条件。

1. 在 Azure 门户，导航到 API 管理实例。

2. 在“API”下，选择“命名值”>“+添加”。

3. 输入一个“名称”标识符，并输入用来在策略中引用此属性的“显示名称”。

4. 在“值类型”中，选择“密钥保管库”。

5. 输入密钥保管库机密的标识符（不含版本），或选择“选择”来选择密钥保管库中的机密。

   重要

   如果你自己输入密钥保管库机密标识符，请确保它不包含版本信息。 否则，在密钥保管库中进行更新后，机密在 API 管理中不会自动轮换。

6. 在“客户端标识”中，选择一个系统分配的托管标识，或一个现有的用户分配的托管标识。 了解如何在 API 管理服务中添加或修改托管标识。

   注意

   标识需要具有获取和列出密钥保管库中机密的权限。 如果你尚未配置对密钥保管库的访问权限，则 API 管理会提示你，你可以让其自动为标识配置必要的权限。

7. 添加一个或多个可帮助你组织命名值的可选标记，然后单击“保存”。

8. 选择“创建” 。

   

将纯值或机密值添加到 API 管理

az apim nv create --resource-group apim-hello-word-resource-group \
    --display-name "named_value_01" --named-value-id named_value_01 \
    --secret true --service-name apim-hello-world --value test

az apim nv list --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --output table

az apim nv show --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

az apim nv show-secret --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

az apim nv delete --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

使用命名值

本部分的示例使用下表中显示的命名值。

若要在策略中使用某个命名值，请将其显示名称包含在一对双大括号中（例如 {{ContosoHeader}}），如以下示例所示：

<set-header name="{{ContosoHeader}}" exists-action="override">
  <value>{{ContosoHeaderValue}}</value>
</set-header>

在此示例中，ContosoHeader 用作 set-header 策略中一个标头的名称，ContosoHeaderValue 用作该标头的值。 在请求或响应 API 管理网关的过程中，如果要对该策略进行评估，则会将 {{ContosoHeader}} 和 {{ContosoHeaderValue}} 替换为各自的值。

命名值可以用作完整的特性或元素值（如前面的示例所示），但也可插入到文字文本表达式中或与该表达式的一部分组合在一起，如以下示例所示：

<set-header name = "CustomHeader{{ContosoHeader}}" ...>

命名值还可以包含策略表达式。 以下示例使用了 ExpressionProperty 表达式。

<set-header name="CustomHeader" exists-action="override">
    <value>{{ExpressionProperty}}</value>
</set-header>

评估此策略时，会将 {{ExpressionProperty}} 替换为其值 @(DateTime.Now.ToString())。 由于该值是一个策略表达式，因此会对表达式进行评估并且策略将继续执行。

若要在 Azure 门户或开发人员门户中对此进行测试，可调用其策略包含的命名值处于范围内的一个操作。 在以下示例中，调用了一个包含两个带命名值的前述示例性 set-header 策略的操作。 请注意，响应包含两个自定义标头，这两个标头是使用带命名值的策略配置的。

在出站 API 跟踪中，如果查看包含前面两个示例策略（带命名值）的调用，则可以看到两个 set-header 策略，这两个策略已插入了命名值，并已针对包含策略表达式的命名值进行了策略表达式计算。

字符串内插也可用于命名值。

<set-header name="CustomHeader" exists-action="override">
    <value>@($"The URL encoded value is {System.Net.WebUtility.UrlEncode("{{ContosoHeaderValue2}}")}")</value>
</set-header>

CustomHeader 的值将为 The URL encoded value is This+is+a+header+value.。

虽然命名值可以包含策略表达式，但不能包含其他命名值。 如果将包含命名值引用的文本用作值（例如 Text: {{MyProperty}}），将不会解析和替换该引用。

删除命名值

若要删除某个命名值，请选择该名称，然后从上下文菜单 (...) 中选择“删除”。

后续步骤

• 详细了解如何使用策略
  • API 管理中的策略
  • 策略参考
  • 策略表达式