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 Az do MAR

Ao instalar determinados módulos do Az PowerShell do MAR (Registro de Artefatos Microsoft) usando 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 do Microsoft Entra ID 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 no 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, 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.'

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 a Azure com 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.
• Azure PowerShell cmdlets não podem ser executados após o login com credenciais de usuário ou código de 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 de 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 Azure PowerShell como parte da carga de trabalho de desenvolvimento Azure, que instala o módulo AzureRM. Azure PowerShell pode ser removido usando o instalador de Visual Studio ou usando "Desinstalar" em aplicativos e 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ê receber erros de Install-Module indicando que o Galeria do PowerShell está inacessível, você pode estar atrás de 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 ao qual você não tem direitos 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 cmdlet Get-AzResource para verificar se o recurso de Azure especificado existe.

Get-AzResource -ResourceId $resourceId

Problemas de permissão com cmdlets do AzAD

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

parâmetros de consulta 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 o API do Graph atual, as entidades de serviço não são retornadas por Get-AzAdGroupMember no Az 7.x. Como solução alternativa, Invoke-AzRestMethod pode ser usado com a versão beta do Microsoft API do 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 do Az e do AzureRM instalados no mesmo sistema baseado em Windows e eles existem no $env:PSModulePath para a mesma versão do PowerShell.

O Az e o AzureRM podem coexistir no mesmo sistema de Windows, mas somente se o AzureRM estiver instalado no escopo CurrentUser do Windows PowerShell e do Az instalados 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 Azure PowerShell no MacOS, você pode encontrar uma mensagem de erro ao tentar entrar em sua conta Azure de 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 estiver Microsoft Edge, você poderá encontrar o seguinte erro ao tentar fazer logon para Azure interativamente com Connect-AzAccount: "A conexão para este site não é segura." Para resolver esse problema, visite edge://net-internals/#hsts em 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 significativa do Microsoft Entra que requer que o Uri do AppId em aplicativos de locatário único utilize o esquema padrão ou domínios verificados, você deve atualizar o módulo Az.Resources para a versão 4.1.0 ou posterior para continuar usando os cmdlets ou .

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 disruptiva 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 issue.

Workaround

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ê tiver um problema com o produto Azure PowerShell não estiver listado neste artigo ou precisar de assistência adicional, file um problema no GitHub.