Solução de problemas do módulo do Az PowerShell

Habilitar o log de depuração

Uma das primeiras etapas que você deve executar para solucionar um problema com o módulo Az PowerShell do Azure é habilitar o registro em log da depuração.

Para habilitar o log de depuração por comando, especifique o parâmetro Debug.

Get-AzResource -Name 'DoesNotExist' -Debug

Para habilitar o log de depuração para uma sessão inteira do PowerShell, defina o valor da variável DebugPreference como Continue.

$DebugPreference = 'Continue'

Problema conhecido: Falha na instalação de módulos do Az do MAR

Ao instalar determinados módulos do Az PowerShell do Registro de Artefatos da Microsoft (MAR) usando o PSResourceGet, você pode encontrar um erro como:

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

Para obter mais informações, consulte Bugfix para comparar o nome do caminho do arquivo para determinar a correspondência exata.

Solução de problemas de MFA (autenticação multifator)

Falhas de logon interativas

Se você encontrar erros ao executar cmdlets do Azure PowerShell que criam, modificam ou excluem recursos, o problema pode ser causado por uma política de Acesso Condicional da ID do Microsoft Entra que requer autenticação multifator (MFA).

Esses erros normalmente ocorrem quando a MFA é exigida pela política, mas não é imposta durante o logon.

Autenticação SharedTokenCacheCredential indisponível

Você pode ver esse erro ao usar:

• Az Módulo do PowerShell versão 14.2.0 ou anterior
• Az.Accounts módulo PowerShell 5.1.1 ou anterior

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.

Atualize para as seguintes versões ou posteriores para receber mais mensagens de erro informativas e detalhes da política:

• Az Módulo do PowerShell: versão 14.3.0 ou posterior
• Módulo Az.Accounts : versão 5.2.0 ou posterior

O recurso não foi permitido pela política

Esse erro ocorre em versões de módulo mais recentes (Az 14.3.0+ e Az.Accounts 5.2.0+), em que a MFA é exigida pelo Acesso Condicional para operações específicas.

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>"

Opções de resolução

• Peça ao administrador do Azure para impor a MFA na entrada. Isso permite que sua sessão atenda aos requisitos de Acesso Condicional sem etapas adicionais.

• Se a imposição de MFA na entrada não for possível, use o parâmetro ClaimsChallenge para autenticar interativamente:

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

Para obter mais informações, consulte Planejamento para autenticação multifator obrigatória para o Azure e outros portais de administração

Erro ropc: devido a uma alteração de configuração feita pelo administrador

Você usa o fluxo ROPC (Credencial de Senha do Proprietário do Recurso) ao fazer login no Azure usando uma senha. Esse método de autenticação não dá suporte à MFA. Veja um exemplo:

Connect-AzAccount -Credential $Credential

Se a conta de usuário exigir MFA, o comando falhará com o seguinte erro:

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

solução : usar um método de autenticação compatível com a MFA.

Aviso entre locatários: falha na autenticação no locatário

Se você tiver acesso a vários locatários e um deles exigir MFA, o Azure PowerShell poderá exibir o seguinte aviso:

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

O Azure PowerShell tenta entrar com o primeiro locatário encontrado durante o logon. Se esse locatário impor a MFA, a autenticação poderá falhar. Para evitar esse problema, especifique explicitamente o locatário de destino usando o parâmetro TenantId:

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

Isso garante que a autenticação seja tentada em relação ao locatário correto, reduzindo a probabilidade de falhas relacionadas à MFA.

Mensagens de anúncio em cenários de automação

Ao se conectar ao Azure com o Azure PowerShell, as mensagens de anúncio são exibidas usando o fluxo de informações do PowerShell para impedir que alterem a saída baseada em objeto retornada. Embora tenhamos feito todos os esforços para garantir que as mensagens de anúncio não afetem sua experiência, há alguns cenários de automação em que elas podem afetar o uso. Se você tiver problemas, recomendamos suprimir o fluxo de informações nesses cenários:

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

Gerenciador de Contas Web (WAM)

• O método de entrada interativo não pode abrir uma janela para wam e retorna o erro: autenticação cancelada pelo usuário.
• Os cmdlets do Azure PowerShell não podem ser executados depois de fazer logon com um nome de usuário e senha ou código do dispositivo.
• A janela pop-up do WAM não exibe a opção Conta corporativa e de estudante .
• O método de entrada interativo não pode abrir uma janela WAM no console do ISE do Windows PowerShell.

A solução alternativa para esses problemas é desabilitar o WAM:

Update-AzConfig -EnableLoginByWam $false

• A janela pop-up do WAM para selecionar uma conta não é fácil de encontrar. Minimize outras janelas para localizar a janela pop-up.

Installation

Esta seção contém uma lista de soluções para problemas comuns ao instalar o módulo do Az PowerShell.

Coexistência do Az e do AzureRM

Em um cenário em que você precisa instalar o módulo do AzureRM e do Az PowerShell no mesmo sistema Windows:

• O AzureRM deve ser instalado apenas no escopo de usuário atual do Windows PowerShell 5.1.
• Instale o módulo do Az PowerShell no PowerShell 7.2 ou superior.

Visual Studio

Versões mais antigas do Visual Studio podem instalar o Azure PowerShell como parte da carga de trabalho de desenvolvimento do Azure, que instala o módulo AzureRM. O Azure PowerShell pode ser removido usando o instalador do Visual Studio ou usando "Desinstalar" em Aplicativos > recursos. Se você já instalou o PowerShell 7.x, talvez seja necessário instalar manualmente o módulo do Az PowerShell.

Proxy bloqueia conexão

Se você encontrar erros de Install-Module que indicam que a Galeria do PowerShell está inacessível, talvez você esteja protegido por um proxy. Sistemas operacionais e ambientes de rede diferentes têm requisitos diferentes para configurar um proxy para todo o sistema. Entre em contato com o administrador do sistema para obter as configurações de proxy e saber como defini-las para seu ambiente.

O próprio PowerShell pode não ser configurado para usar esse proxy automaticamente. Com o PowerShell 5.1 e posterior, configure a sessão do PowerShell para usar um proxy por meio dos seguintes comandos:

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

Se as credenciais do sistema operacional estiverem configuradas corretamente, essa configuração roteia as solicitações do PowerShell por meio do proxy. Para que essa configuração persista entre as sessões, adicione os comandos ao seu perfil do PowerShell.

Para instalar o pacote, seu proxy precisa permitir conexões HTTPS para www.powershellgallery.com.

Referência de objeto não definida para uma instância de objeto

A mensagem "referência de objeto não definida para uma instância de um objeto" significa que você está se referindo a um objeto nulo ou um recurso do Azure que não existe ou que você não tem permissões para acessar.

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

Você pode usar o Get-AzResource cmdlet para verificar se o recurso do Azure especificado existe.

Get-AzResource -ResourceId $resourceId

Problemas de permissão com cmdlets do AzAD

O módulo do Az PowerShell usa a API do Microsoft Graph. Administrar ou gerenciar recursos no Azure com o módulo do Az PowerShell requer as mesmas permissões que executar a tarefa idêntica do portal do Azure ou de qualquer outra ferramenta de linha de comando do Azure. Para perguntas específicas sobre permissões, consulte a referência de permissões do Microsoft Graph.

Parâmetros de consulta do Microsoft Graph

Os cmdlets do AzAd em Az.Resources agora dão suporte a parâmetros de consulta e parâmetros de consulta de pesquisa. Para obter detalhes sobre a sintaxe, consulte os links referenciados anteriormente.

Get-AzAdGroupMember não retorna entidades de serviço

Devido a limitações com a API do Graph atual, as entidades de serviço não são retornadas por Get-AzAdGroupMember no Az 7.x. Como alternativa, Invoke-AzRestMethod pode ser usado com a versão beta da API do Microsoft Graph.

O exemplo a seguir requer o módulo do Az PowerShell. Substitua myGroupName na primeira linha pelo nome do grupo.

$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'}}

Comando encontrado, mas não pôde ser carregado

A mensagem a seguir é retornada pelo PowerShell quando você tenta executar qualquer um dos comandos do Az 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'.

Essa mensagem ocorre quando você tem os módulos do PowerShell Az e AzureRM instalados no mesmo sistema Windows e eles existem no $env:PSModulePath para a mesma versão do PowerShell.

O Az e o AzureRM podem coexistir no mesmo sistema Windows, mas somente se o CurrentUser AzureRM estiver instalado no escopo do Windows PowerShell e do Az instalado no PowerShell 7. Para obter mais informações, consulte Instalar o módulo do Az PowerShell.

No MacOS, um erro retorna quando a autorização do KeyChain falha

Ao executar o Azure PowerShell no MacOS, você pode encontrar uma mensagem de erro ao tentar entrar em sua conta do Azure em uma sessão do PowerShell.

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

Como solução alternativa para esse problema, é possível desabilitar o armazenamento de credenciais entre sessões executando o comando a seguir. No entanto, depois de fazer essa alteração, você precisa executar Connect-AzAccount cada vez que iniciar uma nova sessão do PowerShell.

Disable-AzContextAutosave

A conexão deste site não é segura

Quando o navegador padrão for o Microsoft Edge, você poderá encontrar o seguinte erro ao tentar fazer logon no Azure interativamente com Connect-AzAccount: "A conexão para este site não é segura". Para resolver esse problema, visite edge://net-internals/#hsts no Microsoft Edge. Adicione localhost em "Excluir política de segurança de domínio" e clique em Excluir.

Erro de domínio verificado de IdentifierUri da entidade de serviço

Erro: os valores da propriedade identifierUris devem usar um domínio verificado da organização ou seu subdomínio é exibido ao executar New-AzADServicePrincipal ou New-AzADApplication.

Devido à alteração interruptiva do Microsoft Entra que exige o URI do AppId em aplicativos de locatário único para exigir o uso de esquema padrão ou de domínios verificados, é necessário atualizar o módulo Az.Resources para a versão 4.1.0 ou posterior, a fim de continuar usando os cmdlets New-AzADServicePrincipal ou New-AzADApplication.

Você também pode atualizar para o módulo do Az PowerShell versão 6.0 ou superior.

Linha do tempo

O requisito entrou em vigor em 15 de outubro de 2021.

Versões afetadas

As seguintes versões do Azure PowerShell são afetadas pela alteração interruptiva do AzureAD:

• Módulo Az.Resources do PowerShell versão 3.5.1-preview ou anterior.
• Módulo do Az PowerShell versão 5.9.0 ou menor.

Se você ainda estiver encontrando problemas após a atualização, fique à vontade para abrir um problema.

Solução Alternativa

Se você não puder atualizar para os módulos do PowerShell descritos anteriormente, poderá seguir essas etapas ao criar uma entidade de serviço:

• Se necessário, adicione seu nome de domínio personalizado usando o Centro de administração do Microsoft Entra
• Criar um aplicativo com um IdentifierUri aceito
• Criar um principal de serviço referenciando este aplicativo

Outros problemas

Se você enfrentar um problema de produto com o Azure PowerShell não listado neste artigo ou precisar de assistência adicional, registre um problema no GitHub.