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

项目
10/28/2024

适用于：所有 API 管理层级

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

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

Azure 门户中的命名值

值类型

类型	说明
普通	文本字符串或策略表达式
机密	由 API 管理加密的文本字符串或策略表达式
密钥保管库	某个 Azure 密钥保管库中存储的机密的标识符。

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

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

密钥保管库机密

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

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

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

注意

Azure 密钥保管库中存储的机密必须介于 1 到 4096 个字符之间，因为 API 管理无法检索超出此限制的值。

先决条件

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

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

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

若要创建机密或将机密导入密钥保管库，请参阅快速入门：使用 Azure 门户在 Azure Key Vault 中设置和检索机密。
在 API 管理实例中启用系统分配的或用户分配的托管标识。

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

在门户中导航到你的密钥保管库。
在左侧菜单中，选择“访问配置”，并记下配置的权限模型。
根据权限模型，为 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 管理

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

重要

将密钥保管库机密添加到 API 管理实例时，必须具有列出密钥保管库机密的权限。

注意

在 API 管理中使用密钥保管库机密时，请注意不要删除机密、密钥保管库或用于访问密钥保管库的托管标识。

在 Azure 门户，导航到 API 管理实例。
在“API”下，选择“命名值”>“+添加”。
输入一个“名称”标识符，并输入用来在策略中引用此属性的“显示名称”。
在“值类型”中，选择“密钥保管库”。
输入密钥保管库机密的标识符（不含版本），或选择“选择”来选择密钥保管库中的机密。

重要

如果你自己输入密钥保管库机密标识符，请确保它不包含版本信息。否则，在密钥保管库中进行更新后，机密在 API 管理中不会自动轮换。
在“客户端标识”中，选择一个系统分配的托管标识，或一个现有的用户分配的托管标识。了解如何在 API 管理服务中添加或修改托管标识。

注意

标识需要具有获取和列出密钥保管库中机密的权限。如果你尚未配置对密钥保管库的访问权限，则 API 管理会提示你，你可以让其自动为标识配置必要的权限。
添加一个或多个可帮助你组织命名值的可选标记，然后单击“保存”。
选择“创建” 。

在 Azure 门户，导航到 API 管理实例。
在“API”下，选择“命名值”>“+添加”。
输入一个“名称”标识符，并输入用来在策略中引用此属性的“显示名称”。
在“值类型”中，选择“明文”或“机密”。
在“值”中，输入一个字符串或策略表达式。
添加一个或多个可帮助你组织命名值的可选标记，然后单击“保存”。
选择“创建” 。

创建命名值后，可以通过选择名称对其进行编辑。如果你更改显示名称，系统会自动更新引用该命名值的任何策略，以使用新的显示名称。

开始使用 Azure CLI：

可以使用本地 Azure CLI。

如果需要，请安装 Azure CLI 来运行 CLI 参考命令。
本地 Azure CLI，请了解如何安装 Azure CLI。如果在 Windows 或 macOS 上运行，请考虑在 Docker 容器中运行 Azure CLI。有关详细信息，请参阅如何在 Docker 容器中运行 Azure CLI。
- 通过使用 az login 命令登录到 Azure CLI。若要完成身份验证过程，请遵循终端中显示的步骤。有关其他登录选项，请参阅使用 Azure CLI 登录。
- 出现提示时，请在首次使用时安装 Azure CLI 扩展。有关扩展详细信息，请参阅使用 Azure CLI 的扩展。
- 运行 az version 以查找安装的版本和依赖库。若要升级到最新版本，请运行 az upgrade。

若要添加命名值，请使用 az apim nv create 命令：

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 update 命令对其进行更新。若要查看所有命名值，请运行 az apim nv list 命令：

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

若要查看为此示例创建的命名值的详细信息，请运行 az apim nv show 命令：

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 命令：

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 命令：

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

使用命名值

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

名称	值	机密
ContosoHeader	`TrackingId`	False
ContosoHeaderValue	••••••••••••••••••••••	True
ExpressionProperty	`@(DateTime.Now.ToString())`	False
ContosoHeaderValue2	`This is a header value.`	False

若要在策略中使用某个命名值，请将其显示名称包含在一对双大括号中（例如 {{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 响应

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

API 检查器跟踪

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

<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.。

注意

如果策略引用了 Azure Key Vault 中的机密，则对允许进行 API 请求跟踪的订阅具有访问权限的用户将能够查看该密钥保管库中的值。

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

删除命名值

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

重要

如果有任何 API 管理策略引用了该命名值，则无法删除它，除非将它从所有使用它的策略中删除。

后续步骤

详细了解如何使用策略

通过