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

  • Artigo

Habilitar o log de depuração

Uma das primeiras etapas que você deve seguir para solucionar um problema com o módulo Az PowerShell do Azure é 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 de uma sessão inteira do PowerShell, defina o valor da variável DebugPreference como Continue.

$DebugPreference = 'Continue'

Instalação

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

Coexistência do Az e do AzureRM

Aviso

Não há suporte para a instalação simultânea dos módulos AzureRM e Az PowerShell no Windows PowerShell 5.1.

Em um cenário que exige a instalação dos módulos AzureRM e Az PowerShell no mesmo sistema Windows:

  • O AzureRM precisa ser instalado somente no escopo do usuário atual do Windows PowerShell 5.1.
  • Instale o módulo Az PowerShell no PowerShell 7.2 ou posterior.

Aviso

O módulo PowerShell do AzureRM 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 do Az PowerShell para garantir o suporte e as atualizações contínuas.

Embora o módulo AzureRM ainda possa funcionar, ele não tem suporte ou será mantido, colocando qualquer uso contínuo a critério e risco do usuário. Consulte nossos recursos de migração para obter diretrizes 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 e recursos. Se você já instalou o PowerShell 7.x, talvez seja necessário instalar manualmente o módulo Az PowerShell.

Conexão de blocos de proxy

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 PowerShell em si 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

Caso suas credenciais do sistema operacional estejam configuradas corretamente, essa configuração roteará as solicitações do PowerShell por meio do proxy. Para manter essa configuração entre as sessões, adicione os comandos ao seu perfil do PowerShell.

Para instalar o pacote, o proxy precisa permitir conexões HTTPS ao endereço 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 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 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 cmdlet Get-AzResource 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. A administração ou o gerenciamento de recursos no Azure com o módulo Az PowerShell requer as mesmas permissões que a execução da tarefa idêntica do portal do Azure ou de qualquer outra ferramenta de linha de comando do Azure. Para dúvidas específicas sobre permissões, confira a Referência de permissão do Microsoft Graph.

Parâmetros de consulta do Microsoft Graph

Os cmdlets do AzAd contidos em Az.Resources já dão suporte a parâmetros de consulta e a parâmetros de consulta de pesquisa. Para obter detalhes sobre a sintaxe, confira 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, o 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'}}

O comando foi 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 AzureRM e do Az PowerShell instalados no mesmo sistema baseado no Windows e eles existem no $env:PSModulePath para a mesma versão do PowerShell.

Importante

Quando o AzureRM é instalado no escopo AllUsers do Windows PowerShell, ele é instalado em um local que faz parte do $env:PSModulePath para PowerShell 7. Não há suporte devido a conflitos entre os módulos do AzureRM e do Az PowerShell.

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

Aviso

O módulo PowerShell do AzureRM 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 do Az PowerShell para garantir o suporte e as atualizações contínuas.

Embora o módulo AzureRM ainda possa funcionar, ele não tem suporte ou será mantido, colocando qualquer uso contínuo a critério e risco do usuário. Consulte nossos recursos de migração para obter diretrizes sobre a transição para o módulo Az.

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

Ao executar o Azure PowerShell no MacOS, você pode receber uma mensagem de erro ao tentar entrar na sua conta do Azure por meio 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 o Connect-AzAccount cada vez que iniciar uma nova sessão do PowerShell.

Disable-AzContextAutosave

A conexão deste site não é segura

Quando o seu navegador padrão é o Microsoft Edge, você pode encontrar o seguinte erro ao tentar fazer login no Azure interativamente com Connect-AzAccount: "A conexão deste site não é segura".Para resolver esse problema, acesse 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 precisam utilizar um domínio verificado da organização ou o subdomínio dele será exibido durante a execução de 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.

Também é possível atualizar para o módulo Az do PowerShell versão 6.0 ou posterior.

Linha do tempo

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

Versões impactadas

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 Az do PowerShell versão 5.9.0 ou anterior.

Se ainda houver falhas ou erros depois da atualização, abra um problema.

Solução alternativa

Se não for possível fazer a atualização para os módulos do PowerShell descritos anteriormente, siga estas etapas ao criar uma entidade de serviço:

Outros problemas

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