Azure PowerShell objetos de contexto

Azure PowerShell usa Azure PowerShell objetos de contexto (Azure contextos) para armazenar informações de assinatura e autenticação. Se você tiver acesso a várias assinaturas, os contextos do Azure permitirão que você selecione a assinatura para executar cmdlets do Azure PowerShell. Contextos do Azure também são usados para armazenar dados de login em múltiplas sessões do PowerShell e para executar tarefas em segundo plano.

Este artigo aborda o gerenciamento de contextos do Azure, não o gerenciamento de assinaturas ou contas. Se você quiser gerenciar usuários, assinaturas, locatários ou outras informações da conta, consulte a documentação Microsoft Entra ID. Para saber mais sobre como usar contextos para executar tarefas em segundo plano ou paralelas, consulte 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 Azure

Azure contextos 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 Azure. Com contextos do Azure, o Azure PowerShell não precisa autenticar sua conta novamente sempre que você alternar entre assinaturas. Um contexto Azure consiste em:

• O account usado 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 sob a perspectiva da conta.
• O subscription ativo, um contrato de serviço com a Microsoft para criar e executar recursos do Azure, que estão associados a um tenant. Os locatários geralmente são chamados de organizações na documentação ou ao trabalhar com o Microsoft Entra.
• Uma referência a um cache token, um token de autenticação armazenado para acessar uma nuvem Azure. As configurações de salvamento automático de contexto determinam onde o token é armazenado e por quanto tempo ele persiste.

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

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

Obter contextos de Azure

Os contextos de 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 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 de Azure com base nas informações da assinatura

O cmdlet Set-AzContext é usado para criar e definir novos contextos de Azure como o contexto ativo. A maneira mais fácil de criar um novo contexto de Azure é usar informações de assinatura existentes. O cmdlet Set-AzContext foi projetado para tirar o objeto de saída de Get-AzSubscription como um valor pipelinado 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 do 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 Subscription Name (subscription-id).

Alterar o contexto de Azure ativo

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

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

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 em 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. Scope permite modificar o contexto ativo de uma única sessão sem mudar o padrão.

Get-AzContext -Name MyContextName | 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 MyContextName
New-AzVM -Name ExampleVM -AzContext $context

O outro uso primário de contextos com Azure PowerShell cmdlets é executar comandos em segundo plano. Para saber mais sobre como executar trabalhos do PowerShell usando Azure PowerShell, consulte Run Azure PowerShell cmdlets em Trabalhos do PowerShell.

Salvar o contexto do Azure nas sessões do PowerShell

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

• Entrar usando -Scope Process e Connect-AzAccount.

  Connect-AzAccount -Scope Process
  

  O contexto do Azure retornado como parte dessa entrada é válido somente para a sessão atual somente 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 em Azure PowerShell com o cmdlet Disable-AzContextAutosave. Desabilitar o salvamento automático de contexto não limpa nenhum token armazenado. Para saber como limpar informações de contexto de Azure armazenadas, consulte Emove Azure contextos e credenciais armazenadas.

• Para habilitar explicitamente o autossalvamento de contexto do Azure, use 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 os quais serão usados em sessões futuras do PowerShell, em que elas podem ser carregadas 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 dá suporte ao parâmetro Scope, que pode receber um valor de Process para se aplicar somente ao processo atualmente em execução. Por exemplo, para garantir que os contextos recém-criados não sejam salvos após 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 em 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 Emove Azure contextos e credenciais armazenadas.

Remover contextos do Azure e credenciais armazenadas

Para limpar os contextos e as 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 MyContextName # Disconnect by context name
  
  $context = Get-AzContext
  Disconnect-AzAccount -AzureContext $context # Disconnect using context object information
  

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

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

• Remova 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.

Consulte 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