Gerenciar variáveis na Automação do Azure

  • Artigo

Ativos variáveis são valores que estão disponíveis para todos os runbooks e configurações de 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 da mesma configuração de runbook ou DSC.

  • Gerenciando um valor usado por runbooks ou configurações DSC do portal ou da 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 se uma configuração de runbook ou DSC falhar. Esse comportamento permite que um runbook ou configuração DSC defina um valor que é usado por outro runbook ou pela mesma configuração de runbook ou DSC na próxima vez 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 seguro. Depois de criar a variável, não é possível alterar seu status de criptografia sem recriar a variável. Se você tiver variáveis de conta de automação armazenando dados confidenciais que ainda não estão criptografados, precisará excluí-los e recriá-los como variáveis criptografadas. Uma recomendação do Microsoft Defender for Cloud é criptografar todas as variáveis de Automação do Azure, conforme descrito em As variáveis de conta de automação devem ser criptografadas. Se você tiver variáveis não criptografadas que deseja excluir desta recomendação de segurança, consulte Isentar um recurso de recomendações e proteger a pontuação para criar uma regra de isenção.

Nota

Os recursos protegidos na Automatização do Azure incluem credenciais, certificados, ligações e variáveis encriptadas. Esses ativos são criptografados e armazenados na Automação do Azure usando uma chave exclusiva gerada para cada conta de Automação. A Automação do Azure armazena a chave no Cofre de Chaves gerenciado pelo sistema. Antes de armazenar um ativo seguro, a Automação carrega a chave do Cofre da Chave e a usa para criptografar o ativo.

Tipos de variáveis

Ao criar uma variável com o portal do Azure, você deve especificar um tipo de dados na lista suspensa para que o portal possa exibir o controle apropriado para inserir o valor da variável. A seguir estão os tipos de variáveis disponíveis na Automação do Azure:

  • String
  • Número inteiro
  • DateTime
  • Boolean
  • Nulo

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

Não é possível 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.Json.Linq.JProperty para um tipo de objeto complexo em vez de um tipo PSObject PSCustomObject.

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

Nota

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. Consulte Regras e restrições de nomenclatura para recursos do Azure.

Cmdlets do PowerShell para acessar variáveis

Os cmdlets na tabela a seguir criam e gerenciam variáveis de automação com o PowerShell. Eles são enviados como parte dos módulos Az.

Cmdlet Descrição
Get-AzAutomationVariable Recupera o valor de uma variável existente. Se o valor for um tipo simples, esse mesmo tipo será recuperado. Se for um tipo complexo, um PSCustomObject tipo será recuperado. 1
New-AzAutomationVariable Cria uma nova variável e define 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 e configurações de DSC. Esses cmdlets vêm com o módulo Orchestrator.AssetManagement.Cmdletsglobal . Para obter mais informações, consulte 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.

Nota

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

Funções Python para acessar variáveis

As funções na tabela a seguir são usadas para acessar variáveis em um runbook Python 2 e 3. Os runbooks do Python 3 estão atualmente em visualização.

Funções 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.

Nota

Você deve importar o automationassets módulo na parte superior do seu runbook Python para acessar as funções do ativo.

Criar e obter uma variável

Nota

Se quiser remover a criptografia de uma variável, exclua a variável e recrie-a como não criptografada.

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

  1. Na sua conta de automação, no painel esquerdo, selecione Variáveis em Recursos compartilhados.
  2. Na página Variáveis, selecione Adicionar uma variável.
  3. Conclua as opções na página Nova variável e selecione Criar para salvar a nova variável.

Nota

Depois de salvar uma variável criptografada, ela não pode ser visualizada no portal. Só pode ser atualizado.

Criar e obter uma variável no Windows PowerShell

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

Nota

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, em seguida, 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 mostra como criar uma variável com um tipo complexo e, em seguida, recuperar suas propriedades. Nesse caso, um objeto de máquina virtual de Get-AzVM é usado especificando 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 pressupõ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 gráficos de runbook

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.

Add variable to canvas

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

Set simple variable

Próximos passos