Objetos de contexto do Azure PowerShell

  • Artigo

O Azure PowerShell utiliza objetos de contexto do Azure PowerShell (contextos do Azure) para manter as informações de subscrição e autenticação. Se tiver mais do que uma subscrição, os contextos do Azure permitem-lhe selecionar a subscrição na qual executar os cmdlets do Azure PowerShell. Os contextos do Azure também servem para armazenar informações de início de sessão em várias sessões do PowerShell e executar tarefas em segundo plano.

Este artigo aborda a gestão de contextos do Azure, não a gestão de subscrições ou contas. Se você deseja gerenciar usuários, assinaturas, locatários ou outras informações de conta, consulte a documentação do Microsoft Entra ID . Para saber mais sobre como usar contextos para executar tarefas em segundo plano ou paralelas, consulte Executar cmdlets do Azure PowerShell em Trabalhos do PowerShell depois de se familiarizar com os contextos do Azure.

Descrição geral dos objetos de contexto do Azure

Os contextos do Azure são objetos do PowerShell que representam a sua subscrição ativa na qual executar comandos e as informações de autenticação necessárias para se ligar a uma cloud do Azure. Com os contextos do Azure, o Azure PowerShell não precisa de reautenticar a sua conta sempre que muda de subscrição. Um contexto do Azure é composto por:

  • A conta que foi utilizada para iniciar sessão no Azure com Connect-AzAccount. Os contextos do Azure tratam os utilizadores, IDs de aplicação e principais de serviço da mesma forma de uma perspetiva de conta.
  • A subscrição ativa, um contrato de serviço com a Microsoft para criar e executar recursos do Azure, que estão associados a um inquilino. Os inquilinos são frequentemente designados por organizações na documentação ou ao trabalhar com o Active Directory.
  • Uma referência a uma cache de tokens, um token de autenticação armazenado para aceder a uma cloud do Azure. As definições de gravação automática do contexto determinam o local onde este token é armazenado e o tempo durante o qual persiste.

Para obter mais informações sobre esses termos, consulte Terminologia do Microsoft Entra. Os tokens de autenticação utilizados pelos contextos do Azure são os mesmos que outros tokens armazenados que fazem parte de uma sessão persistente.

Quando inicia sessão com Connect-AzAccount, pelo menos um contexto do Azure é criado para a sua subscrição predefinida. O objeto devolvido por Connect-AzAccount é o contexto predefinido do Azure utilizado durante o resto da sessão do PowerShell.

Obter contextos do Azure

Os contextos disponíveis do Azure são obtidos com o cmdlet Get-AzContext. Liste os contextos disponíveis com o parâmetro ListAvailable :

Get-AzContext -ListAvailable

Ou obtenha um contexto por nome:

Get-AzContext -Name 'mycontext'

Os nomes dos contextos podem ser diferentes do nome da subscrição associada.

Importante

Os contextos do Azure disponíveis não são sempre as suas subscrições disponíveis. Os contextos do Azure representam apenas informações armazenadas localmente. Pode obter as suas subscrições com o cmdlet Get-AzSubscription.

Criar um novo contexto do Azure a partir de informações de subscrição

O cmdlet Set-AzContext serve para criar novos contextos do Azure e para defini-los como o contexto ativo. A forma mais fácil de criar um novo contexto do Azure é utilizar as informações de subscrição existentes. O cmdlet destina-se a retirar o objeto de saída de Get-AzSubscription como um valor encaminhado e configurar um novo contexto do Azure:

Get-AzSubscription -SubscriptionName 'MySubscriptionName' |
  Set-AzContext -Name 'MyContextName'

Ou indique o ID ou nome da subscrição e o ID do inquilino, se necessário:

Set-AzContext -Name 'MyContextName' -Subscription 'MySubscriptionName' -Tenant '00000000-0000-0000-0000-000000000000'

Se o parâmetro Name for omitido, o nome e a ID da assinatura serão usados como o nome do contexto no formato Nome da Assinatura (ID da assinatura).

Alterar o contexto ativo do Azure

Tanto Set-AzContext como Select-AzContext podem ser utilizados para alterar o contexto ativo do Azure. Conforme descrito em Criar um novo contexto do Azure, cria um novo contexto do Azure para uma assinatura, Set-AzContext se não existir, e alterna o contexto ativo para esse contexto.

Select-AzContext destina-se a ser usado apenas com contextos existentes do Azure e funciona de forma semelhante ao uso do Set-AzContext -Context, mas foi projetado para uso com tubulação:

Set-AzContext -Context $(Get-AzContext -Name 'mycontext') # Set a context with an inline Azure context object
Get-AzContext -Name 'mycontext' | Select-AzContext # Set a context with a piped Azure context object

Como muitos outros comandos de gerenciamento de conta e contexto no Azure PowerShell, Set-AzContext e Select-AzContext dão suporte ao parâmetro Scope para que você possa controlar por quanto tempo o contexto está ativo. O escopo permite alterar o contexto ativo de uma única sessão sem alterar o padrão:

Get-AzContext -Name 'mycontext' | Select-AzContext -Scope Process

Para evitar alternar contextos para uma sessão inteira do PowerShell, os comandos do Azure PowerShell com um parâmetro AzContext podem ser executados em um determinado contexto:

$context = Get-AzContext -Name "mycontext"
New-AzVM -Name ExampleVM -AzContext $context

A outra principal utilização dos contextos com os cmdlets do Azure PowerShell é para executar comandos em segundo plano. Para obter mais informações sobre a execução de Tarefas do PowerShell com o Azure PowerShell, veja Executar cmdlets do Azure PowerShell em Tarefas do PowerShell.

Guardar contextos do Azure entre sessões do PowerShell

Por predefinição, os contextos do Azure são guardados para serem utilizados entre as sessões do PowerShell. Pode alterar este comportamento das seguintes formas:

  • Iniciar sessão com -Scope Process com Connect-AzAccount.

    Connect-AzAccount -Scope Process

    O contexto do Azure retornado como parte dessa entrada é válido apenas para a sessão atual e não será salvo automaticamente, independentemente da configuração de salvamento automático de contexto do Azure PowerShell.

  • Desabilite o salvamento automático de contexto no Azure PowerShell com o cmdlet Disable-AzContextAutosave . A desativação da gravação automática do contexto não limpa os tokens armazenados. Para saber como limpar as informações de contexto do Azure armazenadas, veja Remover as credenciais e os contextos do Azure.

  • Pode ativar explicitamente a gravação automática do contexto do Azure com o cmdlet Enable-AzContextAutosave. Com o salvamento automático habilitado, os contextos de um usuário são armazenados localmente para sessões posteriores do PowerShell.

  • Guarde manualmente os contextos com Save-AzContext para serem utilizados em sessões futuras do PowerShell, onde podem ser carregados com Import-AzContext:

    Save-AzContext -Path current-context.json # Save the current context
Save-AzContext -Profile $profileObject -Path other-context.json # Save a context object
Import-AzContext -Path other-context.json # Load the context from a file and set it to the current context

Aviso

Desativar a gravação automática do contexto não limpa as informações de contexto armazenadas que foram guardadas. Para remover as informações armazenadas, utilize o cmdlet Clear-AzContext. Para obter mais informações sobre como remover contextos guardados, veja Remover credenciais e contextos.

Cada um desses comandos suporta o parâmetro Scope , que pode ter um valor de para se aplicar apenas ao processo em Process execução atual. Por exemplo, para garantir que os contextos recém-criados não são guardados depois de sair de uma sessão do PowerShell:

Disable-AzContextAutosave -Scope Process
$context2 = Set-AzContext -Subscription 'sub-id' -Tenant 'other-tenant'

As informações de contexto e os tokens são armazenados no diretório $env:USERPROFILE\.Azure no Windows e em $HOME/.Azure noutras plataformas. Informações confidenciais, como IDs de assinatura e IDs de locatário, ainda podem ser expostas em informações armazenadas, por meio de logs ou contextos salvos. Para saber como limpar as informações armazenadas, veja a secção Remover credenciais e contextos.

Remover credenciais armazenadas e contextos do Azure

Para limpar as credenciais e os contextos do Azure:

  • Termine sessão de uma conta com Disconnect-AzAccount. Pode terminar sessão de qualquer conta através da conta ou do contexto:

    Disconnect-AzAccount # Disconnect active account
Disconnect-AzAccount -Username 'user@contoso.com' # Disconnect by account name

Disconnect-AzAccount -ContextName 'subscription2' # Disconnect by context name
Disconnect-AzAccount -AzureContext $contextObject # Disconnect using context object information

    Desligar remove sempre os tokens de autenticação armazenados e limpa os contextos guardados associados ao contexto ou utilizador desligado.

  • Utilize Clear-AzContext. Esse cmdlet sempre remove contextos armazenados, tokens de autenticação e faz logout.

  • Remova um contexto com Remove-AzContext:

    Remove-AzContext -Name 'mycontext' # Remove by name
Get-AzContext -Name 'mycontext' | Remove-AzContext # Remove by piping Azure context object

    Se você remover o contexto ativo, será desconectado do Azure e precisará se autenticar novamente com Connect-AzAccounto .

Consulte também