Compartilhar via

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 .

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

Observação

Como solução temporária, instale o módulo a partir de outro repositório, como o PowerShell Gallery, até que o problema seja resolvido.

Para mais informações, consulte a Correção de erro para comparar o nome do caminho do arquivo e determinar a correspondência exata.

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

Falhas de login interativo

Se encontrar erros ao executar cmdlets do Azure PowerShell que criam, modificam ou eliminam 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 foi rejeitado 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

  • Pede ao teu administrador do Azure para aplicar o 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 mais informações, consulte Planeamento para autenticação multifator obrigatória para portais de Azure e outros portais administrativos

Erro ROPC: Devido a uma alteração de configuração feita pelo administrador

Utiliza o fluxo de credenciais de palavra-passe do proprietário do recurso (ROPC) ao efetuar login no Azure usando uma palavra-passe. Este método de autenticação não suporta MFA. Eis 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 tiver acesso a vários inquilinos, e um deles exigir MFA, o Azure PowerShell pode apresentar 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 iniciar sessão com o primeiro inquilino encontrado durante o login. 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 ligar-se ao Azure com o Azure PowerShell, as mensagens de anúncio são exibidas usando o fluxo de informação do PowerShell para evitar que alterem a saída baseada em objetos devolvida. 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 conseguem correr depois de iniciar sessão com nome de utilizador, palavra-passe 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 interativo de início de sessão não consegue abrir uma janela WAM na consola Windows PowerShell ISE.

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.

Instalação

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

Advertência

Não suportamos ter instalados simultaneamente os módulos AzureRM e Az PowerShell no Windows PowerShell 5.1.

Num cenário em que precisas de instalar tanto o AzureRM como o módulo PowerShell do Arizona no mesmo sistema Windows:

  • O AzureRM deve ser instalado apenas no âmbito de utilizador atual do PowerShell 5.1 do Windows.
  • Instale o módulo Az PowerShell no PowerShell 7.2 ou superior.

Advertência

O módulo AzureRM PowerShell foi oficialmente preterido a partir de 29 de fevereiro de 2024. Os usuários são aconselhados a migrar do AzureRM para o módulo Az PowerShell para garantir suporte e atualizações contínuos.

Embora o módulo AzureRM ainda possa funcionar, ele não é mais mantido ou suportado, colocando qualquer uso continuado a critério e risco do usuário. Consulte nossos recursos de migração para obter orientação sobre a transição para o módulo Az.

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 Apps & funcionalidades. 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 receberes erros de Install-Module de que o PowerShell Gallery está inacessível, podes 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 "object reference not set to an instance of an object" significa que te estás a referir a um objeto que é nulo ou a um recurso Azure que não existe ou ao qual não tens permissões de acesso.

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

Pode usar o cmdlet Get-AzResource para verificar se o recurso de Azure especificado existe.

Get-AzResource -ResourceId $resourceId

Problemas de permissões com cmdlets AzAD

O módulo Az PowerShell utiliza a Microsoft Graph API. Administrar ou gerir recursos no Azure com o módulo Az PowerShell requer as mesmas permissões que realizar a mesma tarefa a partir do portal do Azure ou de qualquer outra ferramenta de linha de comandos do Azure. Para perguntas específicas sobre permissões, consulte a referência de permissões 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 identidades 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 Graph API.

O exemplo a seguir requer o módulo Az PowerShell. Substitua 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'.

Esta mensagem ocorre quando tens os módulos PowerShell Az e AzureRM instalados no mesmo sistema baseado em Windows e eles existem no $env:PSModulePath para a mesma versão do PowerShell.

Importante

Quando o AzureRM é instalado no âmbito AllUsers do Windows PowerShell, é instalado numa localização que faz parte do $env:PSModulePath para o PowerShell 7. Isso não é suportado devido a conflitos entre os módulos AzureRM e Az PowerShell.

Tanto o Az como o AzureRM podem coexistir no mesmo sistema Windows, mas apenas se o AzureRM estiver instalado no âmbito CurrentUser do Windows PowerShell e do Az instalados no PowerShell 7. Para obter mais informações, consulte Instalar o módulo Az PowerShell.

Advertência

O módulo AzureRM PowerShell foi oficialmente preterido a partir de 29 de fevereiro de 2024. Os usuários são aconselhados a migrar do AzureRM para o módulo Az PowerShell para garantir suporte e atualizações contínuos.

Embora o módulo AzureRM ainda possa funcionar, ele não é mais mantido ou suportado, colocando qualquer uso continuado a critério e risco do usuário. Consulte nossos recursos de migração para obter orientação sobre a transição para o módulo Az.

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

Ao executar o Azure PowerShell no MacOS, pode encontrar uma mensagem de erro ao tentar iniciar sessão na sua conta Azure a partir de uma sessão 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 sempre que iniciar uma nova sessão do PowerShell.

Disable-AzContextAutosave

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

Quando o seu navegador predefinido está Microsoft Edge, pode encontrar o seguinte erro ao tentar iniciar sessão para Azure interativamente com Connect-AzAccount: "A ligação a este site não é segura." Para resolver este problema, visite edge://net-internals/#hsts em Microsoft Edge. Adicione 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 ou .

Devido à alteração de compatibilidade do Microsoft Entra, que exige que o AppId Uri em aplicações de tenant único utilize o esquema padrão ou domínios verificados, deve atualizar o módulo Az.Resources para a versão 4.1.0 ou posterior para continuar a usar os 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 de quebra 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 ainda estiveres a ter problemas após a atualização, sente-te à vontade para abrir um issue.

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:

Outras questões

Se tiver um problema com o produto com Azure PowerShell não listados neste artigo ou precisar de mais assistência, apresenta uma reclamação em GitHub.

  • Last updated on