Objetos de contexto do Azure PowerShell

  • Artigo

O Azure PowerShell usa objetos de contexto do Azure PowerShell (contextos do Azure) para armazenar as informações de assinatura e autenticação. Se tiver mais de uma assinatura, os contextos do Azure permitirão que você selecione a assinatura na qual executar os cmdlets do Azure PowerShell. Os contextos do Azure também são usados para armazenar informações de conexão em várias sessões do PowerShell e executar tarefas em segundo plano.

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

Visão geral de objetos de contexto do Azure

Os contextos do Azure são objetos do PowerShell que representam sua assinatura ativa na qual executar comandos e as informações de autenticação necessárias para se conectar a uma nuvem do Azure. Com os contextos do Azure, o Azure PowerShell não precisa autenticar novamente sua conta sempre que você mudar de assinaturas. Um contexto do Azure é composto:

  • Pela conta que foi usada para entrar no Azure com Connect-AzAccount. Os contextos do Azure tratam usuários, IDs de aplicativo e entidades de serviço da mesma maneira de uma perspectiva de conta.
  • Pela assinatura ativa, um contrato de serviço com a Microsoft para criar e executar recursos do Azure, que estão associados a um locatário. Os locatários costumam ser chamados de organizações na documentação ou ao trabalhar com o Active Directory.
  • Por uma referência a um cache de token, um token de autenticação armazenado para acessar uma nuvem do Azure. O local em que esse token é armazenado e por quanto tempo ele persiste é determinado pelas configurações de salvamento automático de contexto.

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

Quando você entra com Connect-AzAccount, pelo menos um contexto do Azure é criado para sua assinatura padrão. O objeto retornado por Connect-AzAccount é o contexto padrão do Azure usado para o restante da sessão do PowerShell.

Obter contextos do Azure

Os contextos do Azure disponíveis são recuperados 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 de contexto podem ser diferentes do nome da assinatura associada.

Importante

Os contextos do Azure disponíveis nem sempre são suas assinaturas disponíveis. Os contextos do Azure representam apenas informações armazenadas localmente. Você pode obter suas assinaturas com o cmdlet Get-AzSubscription.

Criar um contexto do Azure com base em informações de assinatura

O cmdlet Set-AzContext é usado para criar contextos do Azure e defini-los como o contexto ativo. A maneira mais fácil de criar um contexto do Azure é usar informações de assinatura existentes. O cmdlet é criado para usar o objeto de saída de Get-AzSubscription como um valor de pipe e configurar um novo contexto do Azure:

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

Ou forneça o nome ou a ID da assinatura e a ID de locatário, 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 de contexto no formato Nome da Assinatura (assinatura-id).

Alterar o contexto do Azure ativo

Tanto Set-AzContext quanto Select-AzContext podem ser usados para alterar o contexto do Azure ativo. Conforme descrito em Criar um contexto do Azure, Set-AzContext cria um contexto do Azure para uma assinatura (caso ainda não exista nenhum) e o contexto ativo passa a ser esse.

Select-AzContext deve ser usado apenas com contextos existentes do Azure e funciona de modo semelhante ao uso do Set-AzContext -Context, mas foi projetado para ser usado com redirecionamento:

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 são compatíveis com o parâmetro Scope para que seja possível controlar por quanto tempo o contexto fica ativo. Scope permite alterar o contexto ativo de uma só sessão sem alterar o padrão:

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

Para evitar a mudança de contexto em uma sessão inteira do PowerShell, todos os comandos do Azure PowerShell podem ser executados em um determinado contexto com o parâmetro AzContext:

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

O outro uso principal de contextos com cmdlets do Azure PowerShell é executar comandos em segundo plano. Para saber mais sobre como executar Trabalhos do PowerShell usando o Azure PowerShell, confira Executar cmdlets do Azure PowerShell nos Trabalhos do PowerShell.

Salvar contextos do Azure em sessões do PowerShell

Por padrão, os contextos do Azure são salvos para uso entre sessões do PowerShell. Você muda esse comportamento das seguintes maneiras:

  • Entre usando o -Scope Process com o 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 é salvo automaticamente, seja qual for a configuração de salvamento automático de contexto do Azure PowerShell.

  • Desabilite o salvamento automático de contexto do Azure PowerShell com o cmdlet Disable-AzContextAutosave. Desabilitar o salvamento automático de contexto não limpa os tokens armazenados. Para saber como limpar informações de contexto do Azure armazenadas, confira Remover contextos e credenciais do Azure.

  • Habilitar explicitamente o salvamento automático de contexto do Azure pode ser habilitado com o cmdlet Disable-AzContextAutosave. Com o salvamento automático habilitado, os contextos de um usuário são armazenados localmente para sessões posteriores do PowerShell.

  • Salve manualmente contextos com Save-AzContext para serem usados em sessões futuras do PowerShell, em que eles 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

Desabilitar o salvamento automático de contexto não limpa as informações de contexto armazenadas que foram salvas. Para remover informações armazenadas, use o cmdlet Clear-AzContext. Para saber mais sobre como remover contextos salvos, confira Remover contextos e credenciais.

Cada um desses comandos dá suporte ao parâmetro Scope, que pode usar um valor Process a ser aplicado apenas ao processo de execução atual. Por exemplo, para garantir que contextos recém-criados não sejam salvos após 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 tokens são armazenados no diretório $env:USERPROFILE\.Azure no Windows e no $HOME/.Azure em outras 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 de contextos salvos. Para saber como limpar informações armazenadas, confira a seção Remover contextos e credenciais.

Remover contextos e credenciais armazenadas do Azure

Para limpar contextos e credenciais do Azure:

  • Saia de uma conta com Disconnect-AzAccount. Você pode sair de qualquer conta por conta ou 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

    A desconexão sempre remove tokens de autenticação armazenados e limpa contextos salvos associados ao usuário desconectado ou ao contexto.

  • Use Clear-AzContext. Esse cmdlet sempre remove os contextos armazenados e os tokens de autenticação e faz a sua saída.

  • 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 remover o contexto ativo, você será perderá a conexão com o Azure e precisará autenticar-se novamente com Connect-AzAccount.

Confira também