Objetos de contexto do Azure PowerShell

O Azure PowerShell usa objetos de contexto do Azure PowerShell (contextos do Azure) para armazenar informações de assinatura e autenticação. Se você tiver acesso a várias assinaturas, os contextos do Azure permitem que você selecione a assinatura na qual executar cmdlets do Azure PowerShell. Os contextos do Azure também são usados para armazenar informações de entrada 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 pretender gerir utilizadores, subscrições, inquilinos ou outras informações de conta, consulte a documentação Microsoft Entra ID. Para saber mais sobre como utilizar 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.

Visão geral dos objetos de contexto do Azure

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

• A conta que foi usada para iniciar sessão no Azure com Connect-AzAccount. Os contextos do Azure tratam os utilizadores, os IDs de aplicação e as entidades de serviço da mesma forma do ponto de vista da conta.
• A assinatura ativa , um acordo de serviço com a Microsoft para criar e executar recursos do Azure, que estão associados a um locatário . Os locatários são frequentemente chamados de organizações na documentação ou ao trabalhar com o Microsoft Entra.
• Uma referência a um cache de token , um token de autenticação armazenado para acessar uma nuvem do Azure. As configurações de salvamento automático de contexto determinam em que o token é armazenado e quanto tempo permanece.

Para obter mais informações sobre esses termos, consulte Terminologia do Microsoft Entra. Os tokens de autenticação usados pelos 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 disponíveis do Azure são recuperados com o cmdlet Get-AzContext. Liste com o parâmetro ListAvailable os contextos disponíveis:

Get-AzContext -ListAvailable

Ou obtenha um contexto pelo nome:

Get-AzContext -Name MyContextName

Os nomes de contexto podem ser diferentes do nome da assinatura associada. Para determinar o nome do contexto, use o valor da propriedade Name, que não é exibida por padrão.

Get-AzContext -ListAvailable | Select-Object -Property *

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

O cmdlet Set-AzContext é usado para criar e definir novos contextos do Azure como o contexto ativo. A maneira mais fácil de criar um novo contexto do Azure é usar as informações de assinatura existentes. O cmdlet Set-AzContext foi projetado para tomar o objeto de saída do Get-AzSubscription como um valor canalizado e configurar um novo contexto do Azure:

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

Ou forneça o nome ou ID 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 de contexto no formato Subscription Name (subscription-id).

Alterar o contexto ativo do Azure

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

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 MyContextName) # Set a context with an inline Azure context object
Get-AzContext -Name MyContextName | 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. Escopo permite alterar o contexto ativo de uma única sessão sem mudar o padrão:

Get-AzContext -Name MyContextName | Select-AzContext -Scope Process

Para evitar mudar de contexto para uma sessão inteira do PowerShell, os comandos do Azure PowerShell com um parâmetro AzContext podem ser executados num determinado contexto.

$context = Get-AzContext -Name MyContextName
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 tarefas do PowerShell usando o Azure PowerShell, consulte Executar cmdlets do Azure PowerShell em tarefas 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ê pode alterar esse comportamento das seguintes maneiras:

• Inicie sessão utilizando -Scope Process com Connect-AzAccount.

  Connect-AzAccount -Scope Process
  

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

• Desabilite o salvamento automático de contexto no Azure PowerShell com o cmdlet Disable-AzContextAutosave. A desativação do salvamento automático de contexto não limpa nenhum token armazenado. Para saber como limpar informações de contexto do Azure armazenadas, consulte Remover contextos do Azure e credenciais armazenadas.

• Habilitar explicitamente o salvamento automático de contexto do Azure pode ser habilitado 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.

• Salve manualmente contextos com Save-AzContext para serem usados em futuras sessões do PowerShell, onde eles podem ser carregados com Import-AzContext:

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

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

Disable-AzContextAutosave -Scope Process
Set-AzContext -Subscription 'Subscription ID or Name' -Tenant 00000000-0000-0000-0000-000000000000

Informações de contexto e tokens são armazenados no diretório $env:USERPROFILE\.Azure no Windows e $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 contextos salvos. Para saber como limpar informações armazenadas, consulte Remover contextos do Azure e credenciais armazenadas.

Remover contextos do Azure e credenciais armazenadas

Para limpar contextos e credenciais do Azure:

• Sair 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 MyContextName # Disconnect by context name
  
  $context = Get-AzContext
  Disconnect-AzAccount -AzureContext $context # Disconnect using context object information
  

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

• Use Clear-AzContext. Esse cmdlet sempre remove contextos armazenados e tokens de autenticação e desconecta você.

• Remover um contexto com Remove-AzContext:

  Remove-AzContext -Name MyContextName # Remove by name
  Get-AzContext -Name MyContextName | Remove-AzContext # Remove by piping an Azure context object
  

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

Ver também

• Connect-AzAccount
• Disconnect-AzAccount
• Get-AzContext
• Set-AzContext
• Save-AzContext
• Select-AzContext
• Import-AzContext
• Clear-AzContext
• Remove-AzContext
• Enable-AzContextAutosave
• Disable-AzContextAutosave
• Get-AzSubscription