Compartilhar via

Gerenciar variáveis na Automação do Azure

  • Artigo

Ativos de variáveis são valores que estão disponíveis para todos os runbooks e configurações DSC em sua conta de Automação. Você pode gerenciá-los no portal do Azure, no PowerShell, em um runbook ou em uma configuração DSC.

As variáveis de automação são úteis para os seguintes cenários:

  • Compartilhando um valor entre vários runbooks ou configurações DSC.

  • Compartilhando um valor entre vários trabalhos do mesmo runbook ou configuração DSC.

  • Gerenciando um valor usado por runbooks ou configurações DSC acessando o portal ou a linha de comando do PowerShell. Um exemplo é um conjunto de itens de configuração comuns, como uma lista específica de nomes de VM, um grupo de recursos específico, um nome de domínio do AD e muito mais.

A Automação do Azure persiste variáveis e as disponibiliza mesmo quando um runbook ou uma configuração DSC falha. Esse comportamento permite que um runbook ou uma configuração DSC defina um valor que será usado por outro runbook ou pelo mesmo runbook ou configuração DSC na próxima vez em que for executado.

A Automação do Azure armazena cada variável criptografada com segurança. Ao criar uma variável, você pode especificar sua criptografia e armazenamento pela Automação do Azure como um ativo protegido. Após criar a variável, você não pode alterar seu status de criptografia sem recriá-la. Se tiver variáveis de conta de Automação que armazenam dados confidenciais que ainda não foram criptografados, você precisará excluí-los e recriá-los como variáveis criptografadas. Uma recomendação do Microsoft Defender para Nuvem é criptografar todas as variáveis de Automação do Azure, conforme descrito em As variáveis da conta de automação devem ser criptografadas. Se você tiver variáveis não criptografadas que deseja excluir dessa recomendação de segurança, confira Isentar um recurso das recomendações e da classificação de segurança para criar uma regra de isenção.

Observação

Os ativos protegidos na Automação do Azure incluem credenciais, certificados, conexões e variáveis criptografadas. Esses ativos são criptografados e armazenados na Automação do Azure usando uma chave exclusiva que é gerada para cada conta da Automação do Azure. A Automação do Azure armazena a chave no Key Vault gerenciado pelo sistema. Antes de armazenar um ativo seguro, a Automação do Azure carrega a chave do Key Vault e depois a usa para criptografar o ativo.

Tipos de variáveis

Quando você cria uma variável com o portal do Azure, deve especificar um tipo de dados na lista suspensa para que o portal possa exibir o controle adequado para a inserção do valor da variável. Veja a seguir os tipos de variáveis disponíveis na Automação do Azure:

  • String
  • Inteiro
  • DateTime
  • Booliano
  • Nulo

A variável não está restrita ao tipo de dados especificado. Você deve definir a variável usando o Windows PowerShell para especificar um valor de tipo diferente. Se você indicar Not defined, o valor da variável será definido como NULL. Você deve definir o valor com o cmdlet Set-AzAutomationVariable ou o cmdlet Set-AutomationVariable interno. Você usa o Set-AutomationVariable em seus runbooks que devem ser executados no ambiente de área restrita do Azure ou em um Hybrid Runbook Worker do Windows.

Você não pode usar o portal do Azure para criar ou alterar o valor de um tipo de variável complexa. No entanto, você pode fornecer um valor de qualquer tipo usando o Windows PowerShell. Tipos complexos são recuperados como um Newtonsoft.Jsem.LINQ.JProperty para um tipo de objeto complexo em vez de um tipo de PSObject PSCustomObject.

Você pode armazenar vários valores para uma única variável criando uma matriz ou hashtable e salvando-a na variável.

Observação

As variáveis de nome da VM podem ter, no máximo, 80 caracteres. As variáveis do grupo de recursos podem ter, no máximo, 90 caracteres. Confira as Regras de nomenclatura e restrições para recursos do Azure.

Cmdlets do PowerShell para acessar variáveis

Os cmdlets na tabela a seguir são usados para criar e gerenciar variáveis de Automação com o PowerShell. Eles são fornecidos como parte de módulos Az.

Cmdlet Descrição
Get-AzAutomationVariable Recupera o valor de uma variável existente. Se o valor for de um tipo simples, o mesmo tipo será recuperado. Se for de um tipo complexo, um tipo PSCustomObject será recuperado. 1
New-AzAutomationVariable Cria uma nova variável e define o seu valor.
Remove-AzAutomationVariable Remove uma variável existente.
Set-AzAutomationVariable Define o valor de uma variável existente.

1 Não é possível usar esse cmdlet para recuperar o valor de uma variável criptografada. A única maneira de fazer isso é usando o cmdlet interno Get-AutomationVariable em um runbook ou configuração DSC. Por exemplo, para ver o valor de uma variável criptografada, você pode criar um runbook para obter a variável e, em seguida, gravá-la no fluxo de saída:

$encryptvar = Get-AutomationVariable -Name TestVariable
Write-output "The encrypted value of the variable is: $encryptvar"

Cmdlets internos para acessar variáveis

Os cmdlets internos na tabela a seguir são usados para acessar variáveis em seus runbooks ou configurações DSC. Esses cmdlets são fornecidos com o módulo global Orchestrator.AssetManagement.Cmdlets. Para obter mais informações, confira Cmdlets internos.

Cmdlet Interno Descrição
Get-AutomationVariable Recupera o valor de uma variável existente.
Set-AutomationVariable Define o valor de uma variável existente.

Observação

Evite usar variáveis no parâmetro Name do cmdlet Get-AutomationVariable em um runbook ou em uma configuração DSC. O uso das variáveis pode complicar a descoberta das dependências entre runbooks e variáveis de Automação no tempo de design.

Funções do Python para acessar variáveis

As funções na tabela a seguir são usadas para acessar variáveis em um runbook no Python 2 e 3. Atualmente, os runbooks do Python 3 estão em versão prévia.

Funções do Python Descrição
automationassets.get_automation_variable Recupera o valor de uma variável existente.
automationassets.set_automation_variable Define o valor de uma variável existente.

Observação

É necessário importar o módulo automationassets, na parte superior do runbook do Python para acessar as funções do ativo.

Criar e obter uma variável

Observação

Para remover a criptografia de uma variável, exclua a variável e crie novamente como não criptografada.

Criar e obter uma variável usando o portal do Azure

  1. Na sua conta da Automação do Azure, no painel esquerdo, selecione Variáveis em Recursos Compartilhados.
  2. Na página Variáveis, selecioneAdicionar uma variável.
  3. Complete as opções na página Nova Variável e clique em Criar para salvar a nova variável.

Observação

Depois de salva, variável criptografada não pode ser exibida no Portal. Ela só pode ser atualizada.

Criar e obter uma variável no Windows PowerShell

O runbook ou a configuração DSC usa o cmdlet New-AzAutomationVariable para criar uma nova variável e definir seu valor inicial. Se a variável for criptografada, a chamada deverá usar o parâmetro Encrypted. O script pode recuperar o valor da variável usando Get-AzAutomationVariable.

Observação

Um script do PowerShell não pode recuperar um valor criptografado. A única maneira de fazer isso é usar o cmdlet interno Get-AutomationVariable.

O exemplo a seguir mostra como criar uma variável de cadeia de caracteres e retornar seu valor.

$rgName = "ResourceGroup01"
$accountName = "MyAutomationAccount"
$variableValue = "My String"

New-AzAutomationVariable -ResourceGroupName "ResourceGroup01" 
-AutomationAccountName "MyAutomationAccount" -Name 'MyStringVariable' `
-Encrypted $false -Value 'My String'
$string = (Get-AzAutomationVariable -ResourceGroupName "ResourceGroup01" `
-AutomationAccountName "MyAutomationAccount" -Name 'MyStringVariable').Value

O exemplo a seguir mostram como criar uma variável de tipo complexo e recuperar as suas propriedades. Nesse caso, um objeto de máquina virtual de Get-AzVM é usado e especifica um subconjunto de suas propriedades.

$rgName = "ResourceGroup01"
$accountName = "MyAutomationAccount"

$vm = Get-AzVM -ResourceGroupName "ResourceGroup01" -Name "VM01" | Select Name, Location, Extensions
New-AzAutomationVariable -ResourceGroupName "ResourceGroup01" -AutomationAccountName "MyAutomationAccount" -Name "MyComplexVariable" -Encrypted $false -Value $vm

$vmValue = Get-AzAutomationVariable -ResourceGroupName "ResourceGroup01" `
-AutomationAccountName "MyAutomationAccount" -Name "MyComplexVariable"

$vmName = $vmValue.Value.Name
$vmTags = $vmValue.Value.Tags

Exemplos de runbook textual

O exemplo a seguir mostra como definir e recuperar uma variável em um runbook textual. Este exemplo supõe a criação de variáveis inteiras chamadas numberOfIterations e numberOfRunnings e uma variável de cadeia de caracteres chamada sampleMessage.

$rgName = "ResourceGroup01"
$accountName = "MyAutomationAccount"

$numberOfIterations = Get-AutomationVariable -Name "numberOfIterations"
$numberOfRunnings = Get-AutomationVariable -Name "numberOfRunnings"
$sampleMessage = Get-AutomationVariable -Name "sampleMessage"

Write-Output "Runbook has been run $numberOfRunnings times."

for ($i = 1; $i -le $numberOfIterations; $i++) {
    Write-Output "$i`: $sampleMessage"
}
Set-AutomationVariable -Name numberOfRunnings -Value ($numberOfRunnings += 1)

Exemplos de runbook gráfico

Em um runbook gráfico, você pode adicionar atividades para os cmdlets internos Get-AutomationVariable ou Set-AutomationVariable. Basta clicar com o botão direito do mouse em cada variável no painel Biblioteca do editor gráfico e selecionar a atividade desejada.

Adicionar variável à tela

A imagem a seguir mostra exemplos de atividades para atualizar uma variável com um valor simples em um runbook gráfico. Neste exemplo, a atividade de Get-AzVM recupera uma única máquina virtual do Azure e salva o nome do computador em uma variável de cadeia de caracteres existente na Automação. Não importa se o link é um pipeline ou uma sequência, já que esperamos somente um objeto na saída.

Definir variável simples

Próximas etapas