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

适用于：所有 API 管理层级

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

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

值类型

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

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

密钥保管库机密

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

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

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

先决条件

• 如果尚未创建 API 管理服务实例，请参阅 快速入门：使用 Azure 门户创建新的 Azure 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. 选择“查看 + 分配”。

配置 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. 在 “类型” 下拉列表中，选择 “密钥保管库”。

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

   重要

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

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

   注意

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

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 管理中的策略
• 策略参考
• 策略表达式