你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Az PowerShell 模块故障排除

项目
04/06/2024

启用调试日志记录

排查 Azure Az PowerShell 模块问题时，首先应指定的步骤之一是启用调试日志记录。

若要根据每个命令启用调试日志记录，请指定 Debug 参数。

Get-AzResource -Name 'DoesNotExist' -Debug

若要为整个 PowerShell 会话启用调试日志记录，请将 DebugPreference 变量的值设置为 Continue。

$DebugPreference = 'Continue'

安装

本部分包含安装 Azure Az PowerShell 模块时常见问题的解决方案列表。

Az 和 AzureRM 共存

警告

我们不支持在 Windows PowerShell 5.1 中同时安装 AzureRM 和 Az PowerShell 模块。

在需要在同一 Windows 系统上同时安装 AzureRM 和 Az PowerShell 模块的情况下：

AzureRM 必须仅安装在 Windows PowerShell 5.1 的当前用户范围内。
在 PowerShell 7.2 或更高版本中安装 Az PowerShell 模块。

警告

AzureRM PowerShell 模块已自 2024 年 2 月 29 日起正式弃用。为了确保持续获得支持和更新，建议用户从 AzureRM 迁移到 Az PowerShell 模块。

尽管 AzureRM 模块仍可运行，但不再受到维护或支持，任何继续使用的行为都由用户自行决定并自行承担风险。有关过渡到 Az 模块的指导，请参阅我们的迁移资源。

Visual Studio

旧版本的 Visual Studio 可能会将 Azure PowerShell 安装为 Azure 开发工作负载的一部分，进而会安装 AzureRM 模块。可以使用 Visual Studio 安装程序或者使用“应用和功能”中的“卸载”来删除 Azure PowerShell。如果安装了 PowerShell 7.x，可能需要手动安装 Az PowerShell 模块。

代理阻止连接

如果从 Install-Module 获得的错误指示 PowerShell 库无法访问，你可能位于某个代理后面。不同的操作系统和网络环境对于如何配置系统范围的代理有不同的要求。请联系系统管理员，了解你的代理设置，以及如何针对你的环境来配置它们。

PowerShell 本身可能尚未配置为自动使用此代理。使用 PowerShell 5.1 及更高版本时，请使用以下命令将 PowerShell 会话配置为使用代理：

$webClient = New-Object -TypeName System.Net.WebClient
$webClient.Proxy.Credentials = [System.Net.CredentialCache]::DefaultNetworkCredentials

如果操作系统凭据已正确配置，则此配置会通过代理来路由 PowerShell 请求。若要使此设置在各个会话之间持久存在，请将命令添加到 PowerShell 配置文件。

若要安装此包，代理需要允许通过 HTTPS 连接到 www.powershellgallery.com。

对象引用未设置为对象的实例

消息“对象引用未设置为某个对象的实例”表示所引用的对象为 NULL 或 Azure 资源不存在，或表示你没有访问权限。

$resourceId =  '/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/<resource-group-name>/providers/Microsoft.Web/sites/<webapp-name>/privateEndpointConnections/<endpoint-name>'
Get-AzPrivateEndpointConnection -ResourceId $resourceId

Get-AzPrivateEndpointConnection: Object reference not set to an instance of an object.

可以使用 Get-AzResource cmdlet 验证指定 Azure 资源是否存在。

Get-AzResource -ResourceId $resourceId

AzAD cmdlet 的权限问题

Az PowerShell 模块使用 Microsoft Graph API。使用 Az PowerShell 模块在 Azure 中管理资源与从 Azure 门户或任何其他 Azure 命令行工具执行相同任务所需的权限是相同的。有关权限的特定问题，请参阅 Microsoft Graph 权限参考。

Microsoft Graph 查询参数

Az.Resources 下的 AzAd cmdlet 现在支持查询参数和搜索查询参数。有关语法的详细信息，请参阅前面引用的链接。

Get-AzAdGroupMember 不返回服务主体

由于当前图形 API 的限制，Az 7.x 中的 Get-AzAdGroupMember 不会返回服务主体。作为一种解决方法，可将 Invoke-AzRestMethod 与测试版的 Microsoft 图形 API 一起使用。

以下示例需要 Az PowerShell 模块。将第一行中的 myGroupName 替换为你的组的名称。

$Group = Get-AzADGroup -DisplayName myGroupName
((Invoke-AzRestMethod -Uri "https://graph.microsoft.com/beta/groups/$($Group.id)/members").Content |
  ConvertFrom-Json).value |
  Select-Object -Property DisplayName, Id, @{label='OdataType';expression={$_.'@odata.type'}}

找到命令，但无法加载它

尝试运行下述任一 Az PowerShell 命令时，PowerShell 返回以下消息。

Connect-AzAccount: The 'Connect-AzAccount' command was found in the module 'Az.Accounts', but the module could not be loaded. For more information, run 'Import-Module Az.Accounts'.

如果你在基于 Windows 的系统上同时安装了 Az 模块和 AzureRM PowerShell 模块，并且它们位于同一版本的 PowerShell 的 $env:PSModulePath 中，则会出现此消息。

重要

当 AzureRM 安装在 Windows PowerShell 的 AllUsers 范围中时，它安装在 PowerShell 7 的 $env:PSModulePath 中的某个位置。由于 AzureRM 模块和 Az PowerShell 模块之间存在冲突，因此不支持此操作。

Az 和 AzureRM 可同时存在于同一 Windows 系统上，但前提必须是 AzureRM 安装在 Windows PowerShell 的 CurrentUser 范围中，Az 安装在 PowerShell 7 中。有关详细信息，请查看安装 Azure Az PowerShell 模块。

警告

AzureRM PowerShell 模块已自 2024 年 2 月 29 日起正式弃用。为了确保持续获得支持和更新，建议用户从 AzureRM 迁移到 Az PowerShell 模块。

在 MacOS 上，密钥链授权失败时返回错误

在 MacOS 上运行 Azure PowerShell 时，如果尝试从 PowerShell 会话登录到 Azure 帐户，可能会遇到错误消息。

DeviceCodeCredential authentication failed: Persistence check failed. Reason: KeyChain authorization/authentication failed. .Error code: -25293. OS error code -25293.

此问题的解决方法是，通过运行以下命令禁用在会话之间存储凭据。但在进行此更改后，每次启动新的 PowerShell 会话时，都需要运行 Connect-AzAccount。

Disable-AzContextAutosave

此站点的连接不安全

当默认浏览器为 Microsoft Edge 时，如果尝试使用 Connect-AzAccount 以交互方式登录到 Azure，则可能会遇到以下错误：“此站点的连接不安全。”若要解决此问题，请在 Microsoft Edge 中访问 edge://net-internals/#hsts。在“ 删除域安全策略”下添加 localhost，然后单击“删除”。

服务主体标识符 URI 已验证域错误

错误： identifierUris 属性的值必须使用运行 New-AzADServicePrincipal 或 New-AzADApplication 时显示的组织的已验证域或其子域。

由于 Microsoft Entra 中断性变更要求单个租户应用程序中的 AppId Uri 使用默认方案或经验证的域，因此必须将 Az.Resources 模块升级到版本 4.1.0 或更高版本才能继续使用 New-AzADServicePrincipal 或 New-AzADApplication cmdlet。

还可以升级到 Az PowerShell 模块版本 6.0 或更高版本。

时间线

该要求已于 2021 年 10 月 15 日生效。

受影响的版本

以下版本的 Azure PowerShell 受 AzureAD 中断性变更的影响：

Az.Resources PowerShell 模块版本 3.5.1 预览版或更低版本。
Az PowerShell 模块版本 5.9.0 或更低版本。

如果升级后问题仍存在，请创建问题。

解决方法

如果无法升级到前述 PowerShell 模块，则创建服务主体时可以遵循以下步骤：

根据需要使用 Microsoft Entra 管理中心添加自定义域名
使用接受的 IdentifierUri 创建应用程序
创建引用此应用程序的服务主体

其他问题

如果遇到本文未列出的 Azure PowerShell 产品问题或需要进一步帮助，请在 GitHub 上提出问题。