Solução de problemas do módulo Az PowerShell
Ativar o registo de depuração
Uma das primeiras etapas que você deve tomar na solução de um problema com o módulo Az PowerShell é habilitar o log de 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'
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
Gerente de Conta 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 de dispositivo.
- A janela pop-up 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 ISE do Windows PowerShell.
A solução alternativa para esses problemas é desabilitar o WAM:
Update-AzConfig -EnableLoginByWam $false
- A janela pop-up 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
Aviso
Não suportamos os módulos do AzureRM e do Az instalados em simultâneo no PowerShell 5.1 para Windows.
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.
Aviso
O módulo AzureRM do 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 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 você receber erros de que a Galeria do PowerShell está inacessível, você pode estar atrás de Install-Module
um proxy. Diferentes sistemas operativos e ambientes de rede têm requisitos diferentes para configurar um proxy ao nível do sistema. Contacte o administrador de sistema para obter as suas definições de proxy e saber como configurá-las para o seu ambiente.
O PowerShell não pode ser configurado para utilizar este proxy automaticamente. Com o PowerShell 5.1 e posterior, pode configurar a sessão do PowerShell para utilizar um proxy com o seguinte comando:
$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 definida como 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 Get-AzResource
cmdlet para verificar se o recurso especificado do Azure existe.
Get-AzResource -ResourceId $resourceId
Problemas de permissão 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 oferecem 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 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.
Importante
Quando o AllUsers
AzureRM é instalado no escopo do Windows PowerShell, ele é instalado em um local que faz parte do $env:PSModulePath
PowerShell 7. Esta localização não é suportada devido a conflitos entre os módulos AzureRM e Az PowerShell.
Az e AzureRM podem coexistir no mesmo sistema Windows, mas somente se o CurrentUser
AzureRM estiver instalado no escopo do Windows PowerShell e Az instalado no PowerShell 7. Para obter mais informações, consulte Instalar o módulo Az PowerShell.
Aviso
O módulo AzureRM do 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, 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 uma solução para este problema, pode desativar o armazenamento de credenciais entre sessões ao executar o comando seguinte. 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: Os valores da propriedade identifierUris devem usar um domínio verificado da organização ou seu subdomínio é exibido durante a execução New-AzADServicePrincipal
ou New-AzADApplication
.
Devido à alteração de quebra do Microsoft Entra que exige que o AppId Uri em aplicativos de locatário único exija o uso do 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 New-AzADServicePrincipal
ou New-AzADApplication
cmdlets.
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:
- Az.Resources PowerShell módulo versão 3.5.1-preview ou inferior.
- Az PowerShell módulo 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 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 uma entidade de serviço referente a este aplicativo
Outros problemas
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.
Azure PowerShell