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

Ativar o registo de depuração

Um dos primeiros passos que você deve realizar na solução de um problema com o módulo Az PowerShell é ativar o log de depuração.

Para habilitar o log de depuração para cada comando individual, 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 a partir do MAR

Ao instalar determinados módulos do Az PowerShell a partir do Microsoft Artifact Registry (MAR) 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 Correção de bugs para comparar o nome do caminho do arquivo para determinar a correspondência exata.

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

Falhas de login interativo

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

A autenticação com SharedTokenCacheCredential está indisponível

Poderá ver este erro ao utilizar:

• 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 mensagens de erro mais 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

Este erro ocorre em versões mais recentes do módulo (Az 14.3.0+ e Az.Accounts 5.2.0+), onde 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 no início de sessão. Isso permite que sua sessão atenda aos requisitos de Acesso Condicional sem etapas adicionais.

• Se a imposição de MFA no início de sessão não for possível, utilize o parâmetro ClaimsChallenge para autenticar de forma interativa:

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

Para obter mais informações, consulte Planejando a 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 (Resource Owner Password Credential) ao entrar no Azure usando uma senha. Este método de autenticação não suporta MFA. Aqui está 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: Use um método de autenticação compatível com MFA.

Aviso importante de interlocatários: Falha na autenticação contra 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 iniciar sessão com o primeiro inquilino encontrado durante o processo de autenticação. Se esse locatário aplicar 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 contra o locatário correto, reduzindo a probabilidade de falhas relacionadas ao 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 que você suprima o fluxo de informações nesses cenários:

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

Gestor de Conta Web (WAM)

• O método de entrada interativo não pode abrir uma janela para WAM e retorna o erro: Usuário cancelou a autenticação.
• 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 de dispositivo.
• A janela pop-up WAM não exibe a opção de Conta de Trabalho e Escolar.
• O método de entrada interativo não pode abrir uma janela WAM no console 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 Az PowerShell.

Coexistência de Az e AzureRM

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

• O AzureRM deve ser instalado somente no escopo de usuário atual do Windows PowerShell 5.1.
• Instale o módulo 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á tiver instalado o PowerShell 7.x, talvez seja necessário instalar manualmente o módulo Az PowerShell.

O proxy bloqueia a ligação

Se receber erros de Install-Module indicando que a Galeria do PowerShell está inacessível, poderá estar atrás de um proxy. Diferentes sistemas operacionais e ambiente de rede têm requisitos diferentes para configurar um proxy em todo o sistema. Contacte o administrador de sistema para obter as suas definições de proxy e saber como configurá-las para o seu ambiente.

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

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

Se as credenciais do seu sistema operativo estiverem configuradas corretamente, esta configuração encaminha os pedidos do PowerShell através do proxy. Para manter esta definição entre 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 associada a uma instância de um objeto

A mensagem "referência de objeto não definida como uma instância de um objeto" significa que você está se referindo a um objeto nulo ou a um recurso do Azure que não existe ou que 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 cmdlet Get-AzResource para verificar se o recurso do Azure especificado existe.

Get-AzResource -ResourceId $resourceId

Problemas de permissões com cmdlets AzAD

O módulo Az PowerShell usa a API do Microsoft Graph. Administrar ou gerenciar recursos no Azure com o módulo Az PowerShell requer as mesmas permissões que executar a tarefa idêntica no portal do Azure ou em 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 AzAd em Az.Resources agora suportam 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 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 da API do Microsoft Graph.

O exemplo a seguir requer o módulo Az PowerShell. Substitua myGroupName na primeira linha pelo nome do seu 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 Az e AzureRM PowerShell instalados no mesmo sistema baseado no Windows e eles existem no $env:PSModulePath para a mesma versão do PowerShell.

Az e AzureRM podem coexistir no mesmo sistema Windows, mas somente se o AzureRM estiver instalado no escopo CurrentUser do Windows PowerShell e Az instalado no PowerShell 7. Para obter mais informações, consulte Instalar o módulo 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 na sua conta do Azure a partir 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, você pode desabilitar o armazenamento de credenciais entre sessões executando o seguinte comando. No entanto, depois de fazer essa alteração, você precisa executar Connect-AzAccount sempre que iniciar uma nova sessão do PowerShell.

Disable-AzContextAutosave

A ligação a este site não é segura

Quando seu navegador padrão é o Microsoft Edge, você pode 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 pelo Service Principal IdentifierUri

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

Devido à mudança crítica do Microsoft Entra que exige que o AppId Uri em aplicativos de instância única utilize o esquema padrão ou domínios verificados, deve-se atualizar o módulo Az.Resources para a versão 4.1.0 ou posterior para continuar utilizando cmdlets New-AzADServicePrincipal ou New-AzADApplication.

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

Linha Cronológica

A exigência 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 PowerShell versão 3.5.1-preview ou inferior.
• módulo Az PowerShell versão 5.9.0 ou inferior.

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

Solução

Se não for possível atualizar para os módulos do PowerShell descritos anteriormente, siga estas etapas ao criar um principal 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 serviço principal referindo-se a esta aplicação

Outras questões

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