Az PowerShell 模块故障排除

启用调试日志记录

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

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

Get-AzResource -Name 'DoesNotExist' -Debug

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

$DebugPreference = 'Continue'

已知问题：从 MAR 安装 Az 模块失败

使用 PSResourceGet 从Microsoft项目注册表（MAR）安装某些 Az PowerShell 模块时，可能会遇到如下错误：

Install-PSResource: Package(s) 'Az.Keyvault' could not be installed from repository 'MAR'.

有关详细信息，请参阅 Bugfix，以比较文件路径名称以确定完全匹配。

多重身份验证疑难解答 （MFA）

交互式登录失败

如果在运行创建、修改或删除资源的 Azure PowerShell cmdlet 时遇到错误，问题可能是由需要多重身份验证（MFA）的Microsoft Entra ID 条件访问策略引起的。

这些错误通常在策略要求 MFA 时发生，但在登录期间不会强制实施。

SharedTokenCacheCredential 身份验证不可用

使用以下方法时，可能会看到此错误：

• Az PowerShell 模块版本 14.2.0 或更高版本
• Az.Accounts PowerShell 模块 5.1.1 或更早版本

SharedTokenCacheCredential authentication unavailable. Token acquisition failed for user
someone@contoso.com. Ensure that you have authenticated with a developer tool that supports Azure
single sign on.

升级到以下版本或更高版本以接收更详细的错误消息和策略详细信息：

• Az PowerShell 模块：版本 14.3.0 或更高版本
• Az.Accounts 模块：版本 5.2.0 或更高版本

策略不允许资源

此错误发生在较新的模块版本（Az 14.3.0+ 和 Az.Accounts 5.2.0+），其中条件访问需要 MFA 才能执行特定作。

Resource was disallowed by policy. Users must use MFA for Create operation.
Users must authenticate with multi-factor authentication to create or update resources.
Run the cmdlet below to authenticate interactively; additional parameters may be added as needed.
Connect-AzAccount -Tenant (Get-AzContext).Tenant.Id -ClaimsChallenge "<claims-challenge-token>"

解决方法选项

• 要求 Azure 管理员在登录时强制实施 MFA。 这样，会话就可以满足条件访问要求，而无需执行其他步骤。

• 如果无法在登录时执行 MFA，请使用 ClaimsChallenge 参数以交互方式进行身份验证：

  Connect-AzAccount -Tenant (Get-AzContext).Tenant.Id -ClaimsChallenge "<claims-challenge-token>"
  

有关详细信息，请参阅 规划 Azure 和其他管理门户的强制多重身份验证

ROPC 错误：由于管理员所做的配置更改

使用密码登录到 Azure 时，可以使用资源所有者密码凭据 (ROPC) 流。 此身份验证方法不支持 MFA。 下面是一个示例：

Connect-AzAccount -Credential $Credential

如果用户帐户需要 MFA，该命令将失败并出现以下错误：

Connect-AzAccount : UsernamePasswordCredential authentication failed: Response status code does not
indicate success: 400 (BadRequest). See the troubleshooting guide for more information
https://aka.ms/azsdk/net/identity/usernamepasswordcredential/troubleshoot

解决方案： 使用与 MFA 兼容的身份验证方法。

跨租户警告：对特定租户的身份验证失败

如果有权访问多个租户，其中一个租户需要 MFA，Azure PowerShell 可能会显示以下警告：

WARNING: Unable to acquire token for tenant '00000000-0000-0000-0000-000000000000' with error
'Authentication failed against tenant 00000000-0000-0000-0000-000000000000. User interaction is
required. This may be due to the conditional access policy settings such as multi-factor
authentication (MFA). If you need to access subscriptions in that tenant, please rerun
'Connect-AzAccount' with additional parameter '-TenantId 00000000-0000-0000-0000-000000000000.'

Azure PowerShell 尝试使用在登录期间找到的第一个租户登录。 如果该租户强制实施 MFA，身份验证可能会失败。 若要避免此问题，请使用 TenantId 参数显式指定目标租户：

Connect-AzAccount -TenantId 00000000-0000-0000-0000-000000000000

这可确保针对正确的租户尝试身份验证，从而减少与 MFA 相关的失败的可能性。

自动化方案中的公告消息

使用 Azure PowerShell 连接到 Azure 时，将使用 PowerShell 的信息流显示通知消息，以防止它们更改返回的基于对象的输出。 尽管我们已尽一切努力确保公告消息不会干扰你的体验，但在某些自动化场景中，它们可能会影响使用。 如果遇到问题，建议在这些情况下禁止显示信息流：

Connect-AzAccount -Subscription '<subscription name or id>' -InformationAction Ignore

Web 帐户管理器 (WAM)

• 交互式登录方法无法打开 WAM 窗口并返回错误：用户取消了身份验证。
• 使用用户名和密码或设备代码登录后，Azure PowerShell cmdlet 无法运行。
• WAM 弹出窗口不显示 “工作和学校帐户 ”选项。
• 交互式登录方法无法在 Windows PowerShell ISE 控制台中打开 WAM 窗口。

这些问题的解决方法是禁用 WAM：

Update-AzConfig -EnableLoginByWam $false

• 用于选择帐户的 WAM 弹出窗口并不容易找到。 最小化其他窗口以找到弹出窗口。

Installation

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

Az 和 AzureRM 共存

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

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

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 中，则会出现此消息。

Az 和 AzureRM 可同时存在于同一 Windows 系统上，但前提必须是 AzureRM 安装在 Windows PowerShell 的 CurrentUser 范围中，Az 安装在 PowerShell 7 中。 有关详细信息，请参阅 安装 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 上提出问题。