Objetos de contexto do Azure PowerShellAzure PowerShell context objects

O Azure PowerShell usa objetos de contexto do Azure PowerShell (contextos do Azure) para armazenar as informações de assinatura e autenticação.Azure PowerShell uses Azure PowerShell context objects (Azure contexts) to hold subscription and authentication information. 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.If you have more than one subscription, Azure contexts let you select the subscription to run Azure PowerShell cmdlets on. 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.Azure contexts are also used to store sign-in information across multiple PowerShell sessions and run background tasks.

Este artigo aborda o gerenciamento de contextos do Azure, não o gerenciamento de assinaturas ou contas.This article covers managing Azure contexts, not the management of subscriptions or accounts. Se você estiver procurando gerenciar usuários, assinaturas, locatários ou outras informações de conta, confira a documentação do Azure Active Directory.If you're looking to manage users, subscriptions, tenants, or other account information, see the Azure Active Directory documentation. Para saber mais sobre como usar contextos para executar tarefas em segundo plano ou em paralelo, confira Usar cmdlets do Azure PowerShell em trabalhos do PowerShell depois de se familiarizar com os contextos do Azure.To learn about using contexts for running background or parallel tasks, see Use Azure PowerShell cmdlets in PowerShell jobs after becoming familiar with Azure contexts.

Visão geral de objetos de contexto do AzureOverview of Azure context objects

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.Azure contexts are PowerShell objects representing your active subscription to run commands against, and the authentication information needed to connect to an Azure cloud. Com os contextos do Azure, o Azure PowerShell não precisa autenticar novamente sua conta sempre que você mudar de assinaturas.With Azure contexts, Azure PowerShell doesn't need to reauthenticate your account each time you switch subscriptions. Um contexto do Azure é composto:An Azure context consists of:

  • Pela conta que foi usada para entrar no Azure com Connect-AzAccount.The account that was used to sign in to Azure with 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.Azure contexts treat users, application IDs, and service principals the same from an account perspective.
  • 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.The active subscription, a service agreement with Microsoft to create and run Azure resources, which are associated with a tenant. Os locatários costumam ser chamados de organizações na documentação ou ao trabalhar com o Active Directory.Tenants are often referred to as organizations in documentation or when working with Active Directory.
  • Por uma referência a um cache de token, um token de autenticação armazenado para acessar uma nuvem do Azure.A reference to a token cache, a stored authentication token for accessing an Azure cloud. O local em que esse token é armazenado e por quanto tempo ele persiste é determinado pelas configurações de salvamento automático de contexto.Where this token is stored and how long it persists for is determined by the context autosave settings.

Para obter mais informações sobre esses termos, confira Terminologia do Azure Active Directory.For more information on these terms, see Azure Active Directory Terminology. 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.Authentication tokens used by Azure contexts are the same as other stored tokens that are part of a persistent session.

Quando você entra com Connect-AzAccount, pelo menos um contexto do Azure é criado para sua assinatura padrão.When you sign in with Connect-AzAccount, at least one Azure context is created for your default subscription. O objeto retornado por Connect-AzAccount é o contexto padrão do Azure usado para o restante da sessão do PowerShell.The object returned by Connect-AzAccount is the default Azure context used for the rest of the PowerShell session.

Obter contextos do AzureGet Azure contexts

Os contextos do Azure disponíveis são recuperados com o cmdlet Get-AzContext.Available Azure contexts are retrieved with the Get-AzContext cmdlet. Liste todos os contextos disponíveis com -ListAvailable:List all of the available contexts with -ListAvailable:

Get-AzContext -ListAvailable

Ou obtenha um contexto por nome:Or get a context by name:

$context = Get-AzContext -Name "mycontext"

Os nomes de contexto podem ser diferentes do nome da assinatura associada.Context names may be different from the name of the associated subscription.

Importante

Os contextos do Azure disponíveis nem sempre são suas assinaturas disponíveis.The available Azure contexts aren't always your available subscriptions. Os contextos do Azure representam apenas informações armazenadas localmente.Azure contexts only represent locally-stored information. Você pode obter suas assinaturas com o cmdlet Get-AzSubscription.You can get your subscriptions with the Get-AzSubscription cmdlet.

Criar um contexto do Azure com base em informações de assinaturaCreate a new Azure context from subscription information

O cmdlet Set-AzContext é usado para criar contextos do Azure e defini-los como o contexto ativo.The Set-AzContext cmdlet is used to both create new Azure contexts and set them as the active context. A maneira mais fácil de criar um contexto do Azure é usar informações de assinatura existentes.The easiest way to create a new Azure context is to use existing subscription information. 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:The cmdlet is designed to take the output object from Get-AzSubscription as a piped value and configure a new Azure context:

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:Or give the subscription name or ID and the tenant ID if necessary:

Set-AzContext -Name 'MyContextName' -Subscription 'MySubscriptionName' -Tenant '.......'

Se o argumento -Name for omitido, o nome e a ID da assinatura serão usados como o nome do contexto no formato Subscription Name (subscription-id).If the -Name argument is omitted, then the subscription's name and ID are used as the context name in the format Subscription Name (subscription-id).

Alterar o contexto do Azure ativoChange the active Azure context

Tanto Set-AzContext quanto Select-AzContext podem ser usados para alterar o contexto do Azure ativo.Both Set-AzContext and Select-AzContext can be used to change the active Azure context. Conforme descrito em Criar um contexto do Azure, Set-AzContext criará um contexto do Azure para uma assinatura se não existir um e alternará para usar esse contexto como o ativo.As described in Create a new Azure context, Set-AzContext creates a new Azure context for a subscription if one doesn't exist, and then switches to use that context as the active one.

O Select-AzContext destina-se a ser usado somente com contextos existentes do Azure e funciona de forma semelhante ao uso de Set-AzContext -Context, mas foi projetado para uso com o redirecionamento:Select-AzContext is meant to be used with existing Azure contexts only and works similarly to using Set-AzContext -Context, but is designed for use with piping:

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 de contexto no Azure PowerShell, Set-AzContext e Select-AzContext dão suporte ao argumento -Scope para que você possa controlar por quanto tempo o contexto está ativo.Like many other account and context management commands in Azure PowerShell, Set-AzContext and Select-AzContext support the -Scope argument so that you can control how long the context is active. -Scope permite que você altere o contexto ativo de uma única sessão sem alterar o padrão:-Scope lets you change a single session's active context without changing the default:

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

Para evitar alternar contextos para uma sessão inteira do PowerShell, todos os comandos do Azure PowerShell podem ser executados em um contexto determinado com o argumento -AzContext:To avoid switching contexts for a whole PowerShell session, all Azure PowerShell commands can be run against a given context with the -AzContext argument:

$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.The other main use of contexts with Azure PowerShell cmdlets is to run background commands. Para saber mais sobre como executar Trabalhos do PowerShell usando o Azure PowerShell, confira Executar cmdlets do Azure PowerShell nos Trabalhos do PowerShell.To learn more about running PowerShell Jobs using Azure PowerShell, see Run Azure PowerShell cmdlets in PowerShell Jobs.

Salvar contextos do Azure em sessões do PowerShellSave Azure contexts across PowerShell sessions

Por padrão, os contextos do Azure são salvos para uso entre sessões do PowerShell.By default, Azure contexts are saved for use between PowerShell sessions. Você muda esse comportamento das seguintes maneiras:You change this behavior in the following ways:

  • Entre usando o -Scope Process com o Connect-AzAccount.Sign in using -Scope Process with 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 do contexto do Azure PowerShell.The Azure context returned as part of this sign in is valid for the current session only and will not be automatically saved, regardless of the Azure PowerShell context autosave setting.

  • Desabilite o salvamento automático do contexto do AzurePowershell com o cmdlet Disable-AzContextAutosave.Disable AzurePowershell's context autosave with the Disable-AzContextAutosave cmdlet. Desabilitar o salvamento automático de contexto não limpa os tokens armazenados.Disabling context autosave doesn't clear any stored tokens. Para saber como limpar informações de contexto do Azure armazenadas, confira Remover contextos e credenciais do Azure.To learn how to clear stored Azure context information, see Remove Azure contexts and credentials.

  • Habilitar explicitamente o salvamento automático de contexto do Azure pode ser habilitado com o cmdlet Disable-AzContextAutosave.Explicitly enable Azure context autosave can be enabled with the Enable-AzContextAutosave cmdlet. Com o salvamento automático habilitado, todos os contextos de um usuário são armazenados localmente para sessões posteriores do PowerShell.With autosave enabled, all of a user's contexts are stored locally for later PowerShell sessions.

  • Salve manualmente contextos com Save-AzContext para serem usados em sessões futuras do PowerShell, em que eles podem ser carregados com Import-AzContext:Manually save contexts with Save-AzContext to be used in future PowerShell sessions, where they can be loaded with 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.Disabling context autosave doesn't clear any stored context information that was saved. Para remover informações armazenadas, use o cmdlet Clear-AzContext.To remove stored information, use the Clear-AzContext cmdlet. Para saber mais sobre como remover contextos salvos, confira Remover contextos e credenciais.For more on removing saved contexts, see Remove contexts and credentials.

Cada um desses comandos dá suporte ao parâmetro -Scope, que pode usar um valor de Process a ser aplicado apenas ao processo de execução atual.Each of these commands supports the -Scope parameter, which can take a value of Process to only apply to the current running process. Por exemplo, para garantir que contextos recém-criados não sejam salvos após sair de uma sessão do PowerShell:For example, to ensure that newly created contexts aren't saved after exiting a PowerShell session:

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.Context information and tokens are stored in the $env:USERPROFILE\.Azure directory on Windows, and on $HOME/.Azure on other platforms. 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.Sensitive information such as subscription IDs and tenant IDs may still be exposed in stored information, through logs or saved contexts. Para saber como limpar informações armazenadas, confira a seção Remover contextos e credenciais.To learn how to clear stored information, see the Remove contexts and credentials section.

Remover contextos e credenciais armazenadas do AzureRemove Azure contexts and stored credentials

Para limpar contextos e credenciais do Azure:To clear Azure contexts and credentials:

  • Saia de uma conta com Disconnect-AzAccount.Sign out of an account with Disconnect-AzAccount. Você pode sair de qualquer conta por conta ou contexto:You can sign out of any account either by account or context:

    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.Disconnecting always removes stored authentication tokens and clears saved contexts associated with the disconnected user or context.

  • Use Clear-AzContext.Use Clear-AzContext. Esse cmdlet tem a garantia de sempre remover contextos armazenados e tokens de autenticação e também desconectará você.This cmdlet is guaranteed to always remove stored contexts and authentication tokens, and will also sign you out.

  • Remova um contexto com Remove-AzContext:Remove a context with 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á desconectado do Azure e precisará autenticar-se novamente com Connect-AzAccount.If you remove the active context, you will be disconnected from Azure and need to reauthenticate with Connect-AzAccount.

Confira tambémSee also