Azure CLI在PowerShell环境中处理JSON参数的注意事项

问题背景

在使用Azure CLI进行应用注册管理时，开发人员经常需要通过命令行传递复杂的JSON参数。特别是在Windows和Linux环境下，PowerShell对JSON字符串的处理方式存在差异，这可能导致Azure CLI接收到的参数与预期不符。

典型场景分析

一个常见的场景是使用az ad app update命令更新应用程序的OAuth2权限范围。开发人员通常会构建一个JSON对象，然后将其作为参数传递给Azure CLI命令。例如：

$scopeId = [guid]::NewGuid().Guid
$userImpersonationScope = [ordered]@{
    adminConsentDescription = "user impersonation"
    adminConsentDisplayName = "user_impersonation"
    id                      = "$scopeId"
    isEnabled               = "true"
    type                    = "User"
    userConsentDescription  = "user impersonation"
    userConsentDisplayName  = "user_impersonation"
    value                   = "user_impersonation"
}

$update = @{
    oauth2PermissionScopes = @($userImpersonationScope)
}
$updateJson = ConvertTo-Json $update -Depth 4 -Compress 

跨平台差异问题

在Windows环境下，PowerShell和CMD对JSON字符串中的转义字符处理较为宽松，命令能够正常执行。但在Linux环境下，PowerShell会严格保留JSON字符串中的所有转义字符，导致Azure CLI接收到的参数格式不正确。

Windows环境下实际传递的参数：

{"api": {"oauth2PermissionScopes": [...]}}

Linux环境下实际传递的参数：

{"api": "{\"oauth2PermissionScopes\":[...]}"}

解决方案推荐

最佳实践：使用标准输入(stdin)

为了避免shell对JSON字符串的转义处理，推荐使用标准输入方式传递JSON参数：

$updateJson | az ad app update --id $appId --set api=@-

这种方法完全绕过了shell的引号处理机制，确保JSON数据原封不动地传递给Azure CLI。

替代方案：临时文件

如果标准输入方式不适用，也可以考虑使用临时文件：

$updateJson | Out-File -FilePath temp.json
az ad app update --id $appId --set api=@temp.json
Remove-Item -Path temp.json

技术原理

PowerShell在不同平台上的参数传递行为差异源于其底层实现机制。在Windows上，PowerShell与CMD交互时会自动处理某些转义字符；而在Linux上，PowerShell更严格地遵循POSIX标准，保留了所有转义字符。

Azure CLI接收到参数后，会直接将其作为HTTP请求的负载发送到Azure服务端。如果JSON格式不正确，服务端会返回400错误，提示"Property api in payload has a value that does not match schema"。

总结

在跨平台使用Azure CLI时，特别是在自动化脚本中，开发者应当注意：

1. 优先使用标准输入方式传递复杂JSON参数
2. 避免依赖特定shell环境对JSON字符串的处理方式
3. 在关键操作前添加调试输出，验证实际传递的参数格式
4. 考虑使用Azure CLI的--debug参数排查参数传递问题

通过遵循这些最佳实践，可以确保Azure CLI命令在各种环境下都能稳定执行，避免因参数传递问题导致的意外错误。