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

  • Artigo

Ativar o registo de depuração

Uma das primeiras etapas que você deve seguir na solução de um problema com o módulo Azure 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'

Instalação

Esta seção contém uma lista de soluções para problemas comuns ao instalar o módulo Azure 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 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 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:

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.