使用az cli创建引用Key Vault密钥的APIM命名值遇阻求助

问题描述 #

尝试通过AZ CLI创建引用Key Vault密钥的APIM命名值，由于原生CLI不支持该功能，改用az rest调用Azure REST API替代。脚本执行无报错，但命名值的ProvisioningState始终停留在InProgress，且无法在Azure门户或AZ CLI中查询到该资源。

我的脚本 #

$ApiUrl = "https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroupName/providers/Microsoft.ApiManagement/service/$apimServiceName/namedValues/${namedValueName}?api-version=2023-09-01-preview"
Write-Host $ApiUrl
Write-Host $NamedValueProperties

# 调用Azure REST API创建/更新命名值
$response = az rest --method put --url $ApiUrl --body $namedValuePropertiesString --headers "Content-Type=application/json" --output json | ConvertFrom-Json

# 输出响应状态和内容用于诊断
Write-Host $response.properties

输出内容 #

https://management.azure.com/subscriptions/sub-id/resourceGroups/rg/providers/Microsoft.ApiManagement/service/apim-name/namedValues/nv-name?api-version=2023-09-01-preview 
{
"properties":  
{
    "keyVault":  {
                    "identityClientId":  "client-id",
                    "secretIdentifier":  "https://kv-name.vault.azure.net/secrets/SecretThing"
                },
    "displayName":  "nv-name",
    "secret":  true
} 
} 
@{ProvisioningState=InProgress}

解决步骤 #

1. 验证APIM托管身份权限 #

• 确认APIM使用的托管身份（系统分配或用户分配）已在目标Key Vault的访问策略中配置secrets/get和secrets/list权限。
• 如果使用用户分配身份，确保identityClientId是该身份的客户端ID，且身份已关联到APIM实例。

2. 修正请求体格式 #

• 使用系统分配身份时，请求体中不要包含identityClientId字段，API会自动关联APIM的系统身份。
• 确保JSON格式合法，可通过ConvertTo-Json -Depth 10生成正确的嵌套结构，避免层级丢失。

3. 使用稳定版API #

避免使用预览版API可能存在的兼容性问题，建议使用2023-03-01-preview或正式版API版本。

4. 检查异步操作状态 #

APIM命名值创建是异步操作，可通过以下命令定期查询状态：

az apim named-value show --resource-group $resourceGroupName --service-name $apimServiceName --name $namedValueName

如果长时间停留在InProgress，查看APIM资源的活动日志，获取具体错误信息（如权限不足、密钥不存在等）。

修正后的示例脚本 #

# 配置参数
$subscriptionId = "你的订阅ID"
$resourceGroupName = "你的资源组名"
$apimServiceName = "你的APIM服务名"
$namedValueName = "命名值名称"
$kvSecretUrl = "https://你的密钥保管库.vault.azure.net/secrets/密钥名称"
# $identityClientId = "用户分配身份的客户端ID" # 系统分配身份请注释此行

# 构建请求体
$namedValueProperties = @{
    properties = @{
        displayName = $namedValueName
        secret = $true
        keyVault = @{
            secretIdentifier = $kvSecretUrl
            # 系统分配身份无需添加identityClientId
            # identityClientId = $identityClientId
        }
    }
}
$namedValuePropertiesString = $namedValueProperties | ConvertTo-Json -Depth 10

# 使用稳定版API
$ApiUrl = "https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroupName/providers/Microsoft.ApiManagement/service/$apimServiceName/namedValues/${namedValueName}?api-version=2023-03-01-preview"

# 调用REST API
$response = az rest --method put --url $ApiUrl --body $namedValuePropertiesString --headers "Content-Type=application/json" --output json | ConvertFrom-Json

# 输出当前状态
Write-Host "当前部署状态: $($response.properties.provisioningState)"

内容的提问来源于stack exchange，提问作者Rob Bowman