Configurar parâmetros de entrada de runbook na automação

Artigo
09/10/2024

Os parâmetros de entrada do runbook aumentam a flexibilidade de um runbook, permitindo que os dados sejam passados para ele quando ele é iniciado. Esses parâmetros permitem que as ações do runbook sejam direcionadas para cenários e ambientes específicos. Este artigo descreve a configuração e o uso de parâmetros de entrada em seus runbooks.

Você pode configurar parâmetros de entrada para PowerShell, fluxo de trabalho do PowerShell, gráficos e runbooks do Python. Um runbook pode ter vários parâmetros com diferentes tipos de dados ou sem parâmetros. Os parâmetros de entrada podem ser obrigatórios ou opcionais, e você pode usar valores padrão para parâmetros opcionais.

Você atribui valores aos parâmetros de entrada para um runbook quando o inicia. Você pode iniciar um runbook no portal do Azure, em um serviço Web ou no PowerShell. Você também pode iniciar um como um runbook filho que é chamado inline em outro runbook.

Tipos de entrada

A Automação do Azure dá suporte a vários valores de parâmetros de entrada nos diferentes tipos de runbook. Os tipos de entrada suportados para cada tipo de runbook estão listados na tabela a seguir.

Tipo de runbook	Entradas de parâmetros suportadas
PowerShell	- Corda - Security.SecureString - INT32 - Booleano - DateTime - Matriz - Collections.Hashtable - Management.Automation.SwitchParameter
Fluxo de Trabalho do PowerShell	- Corda - Security.SecureString - INT32 - Booleano - DateTime - Matriz - Collections.Hashtable - Management.Automation.SwitchParameter
PowerShell gráfico	- Corda - INT32 - INT64 - Booleano - Decimal - DateTime - Objeto
Python	- Corda

Configurar parâmetros de entrada em runbooks do PowerShell

Os runbooks do PowerShell e do Fluxo de Trabalho do PowerShell na Automação do Azure dão suporte a parâmetros de entrada definidos por meio das seguintes propriedades.

Propriedade	Descrição
Type	Necessário. O tipo de dados é esperado para o valor do parâmetro. Qualquer tipo .NET é válido.
Nome	Necessário. O nome do parâmetro. Esse nome deve ser exclusivo dentro do runbook, deve começar com uma letra e pode conter apenas letras, números ou caracteres sublinhados.
Obrigatório	Opcional. O valor booleano especifica se o parâmetro requer um valor. Se você definir isso como True, um valor deverá ser fornecido quando o runbook for iniciado. Se você definir isso como False, um valor será opcional. Se você não especificar um valor para a propriedade, o `Mandatory` PowerShell considerará o parâmetro de entrada opcional por padrão.
Default value	Opcional. Um valor que é usado para o parâmetro se nenhum valor de entrada for passado quando o runbook for iniciado. O runbook pode definir um valor padrão para qualquer parâmetro.

O Windows PowerShell oferece suporte a mais atributos de parâmetros de entrada do que os listados acima, como validação, aliases e conjuntos de parâmetros. No entanto, a Automação do Azure atualmente dá suporte apenas às propriedades de parâmetros de entrada listadas.

Como exemplo, vamos examinar uma definição de parâmetro em um runbook de fluxo de trabalho do PowerShell. Esta definição tem a seguinte forma geral, onde vários parâmetros são separados por vírgulas.

Param
(
  [Parameter (Mandatory= $true/$false)]
  [Type] $Name1 = <Default value>,

  [Parameter (Mandatory= $true/$false)]
  [Type] $Name2 = <Default value>
)

Agora vamos configurar os parâmetros de entrada para um runbook de fluxo de trabalho do PowerShell que produz detalhes sobre máquinas virtuais, uma única VM ou todas as VMs dentro de um grupo de recursos. Este runbook tem dois parâmetros, conforme mostrado na captura de tela a seguir: o nome da máquina virtual (VMName) e o nome do grupo de recursos (resourceGroupName).

Fluxo de trabalho do PowerShell de automação

Nesta definição de parâmetro, os parâmetros de entrada são parâmetros simples do tipo string.

Observe que os runbooks do PowerShell e do Fluxo de Trabalho do PowerShell oferecem suporte a todos os tipos simples e tipos complexos, como Object ou PSCredential para parâmetros de entrada. Se o runbook tiver um parâmetro de entrada de objetos, terá de utilizar uma tabela hash do PowerShell com pares nome-valor para transmitir um valor. Por exemplo, você tem o seguinte parâmetro em um runbook.

[Parameter (Mandatory = $true)]
[object] $FullName

Nesse caso, você pode passar o seguinte valor para o parâmetro.

@{"FirstName"="Joe";"MiddleName"="Bob";"LastName"="Smith"}

Para runbooks do PowerShell 7.1, forneça parâmetros de entrada de matriz no formato abaixo:

Nome	Valor
TESTPARAMETER	faz, este, mesmo, trabalho

Nota

Quando você não passa um valor para um parâmetro String opcional com um valor padrão nulo, o valor do parâmetro é uma cadeia de caracteres vazia em vez de Null.

Configurar parâmetros de entrada em runbooks gráficos

Para ilustrar a configuração de parâmetros de entrada para um runbook gráfico, vamos criar um runbook que produz detalhes sobre máquinas virtuais, uma única VM ou todas as VMs dentro de um grupo de recursos. Para obter detalhes, consulte Meu primeiro runbook gráfico.

Um runbook gráfico usa estas principais atividades de runbook:

Autentique-se com o Azure usando a identidade gerenciada configurada para conta de automação.
Definição de um cmdlet Get-AzVM para obter propriedades de VM.
Uso da atividade Write-Output para gerar os nomes da VM.

A Get-AzVM atividade define duas entradas, o nome da VM e o nome do grupo de recursos. Como esses nomes podem ser diferentes cada vez que o runbook é iniciado, você deve adicionar parâmetros de entrada ao seu runbook para aceitar essas entradas. Consulte Criação gráfica na Automação do Azure.

Siga estas etapas para configurar os parâmetros de entrada.

Selecione o runbook gráfico na página Runbooks e clique em Editar.
No editor gráfico, clique no botão Entrada e saída e, em seguida , em Adicionar entrada para abrir o painel Parâmetro de entrada do Runbook.
O controle Input and Output exibe uma lista de parâmetros de entrada definidos para o runbook. Aqui você pode adicionar um novo parâmetro de entrada ou editar a configuração de um parâmetro de entrada existente. Para adicionar um novo parâmetro para o runbook, clique em Adicionar entrada para abrir a folha Parâmetro de entrada Runbook, onde você pode configurar parâmetros usando as propriedades definidas em Criação gráfica na Automação do Azure.
Crie dois parâmetros com as seguintes propriedades a serem usadas pela Get-AzVM atividade e clique em OK.
- Parâmetro 1:
  - Nome: -- VMName
  - Type -- String
  - N.º obrigatório --
- Parâmetro 2:
  - Nome -- resourceGroupName
  - Type -- String
  - N.º obrigatório --
  - Valor padrão -- Personalizado
  - Valor padrão personalizado -- Nome do grupo de recursos que contém as VMs
Exiba os parâmetros no controle de entrada e saída.
Clique em OK novamente e, em seguida, clique em Salvar.
Clique em Publicar para publicar seu runbook.

Configurar parâmetros de entrada em runbooks Python

Ao contrário do PowerShell, do Fluxo de Trabalho do PowerShell e dos runbooks gráficos, os runbooks do Python não usam parâmetros nomeados. O editor de runbook analisa todos os parâmetros de entrada como uma matriz de valores de argumento. Você pode acessar a matriz importando o módulo para seu sys script Python e, em seguida, usando a sys.argv matriz. É importante notar que o primeiro elemento da matriz, sys.argv[0], é o nome do script. Portanto, o primeiro parâmetro de entrada real é sys.argv[1].

Para obter um exemplo de como usar parâmetros de entrada em um runbook Python, consulte Meu primeiro runbook Python na Automação do Azure.

Nota

No momento, não há suporte para argumentos com espaços. Como solução alternativa, você pode usar \\t além de \\n.

Atribuir valores a parâmetros de entrada em runbooks

Esta seção descreve várias maneiras de passar valores para parâmetros de entrada em runbooks. Você pode atribuir valores de parâmetro quando:

Iniciar um runbook
Testar um runbook
Vincular um cronograma para o runbook
Criar um webhook para o runbook

Iniciar um runbook e atribuir parâmetros

Um runbook pode ser iniciado de várias maneiras: por meio do portal do Azure, com um webhook, com cmdlets do PowerShell, com a API REST ou com o SDK.

Iniciar um runbook publicado usando o portal do Azure e atribuir parâmetros

Quando você inicia o runbook no portal do Azure, a folha Start Runbook é aberta e você pode inserir valores para os parâmetros que você criou.

Comece a utilizar o portal

No rótulo abaixo da caixa de entrada, você pode ver as propriedades que foram definidas para definir atributos de parâmetro, por exemplo, obrigatório ou opcional, tipo, valor padrão. O balão de ajuda ao lado do nome do parâmetro também define as principais informações necessárias para tomar decisões sobre valores de entrada de parâmetros.

Nota

Os parâmetros de cadeia de caracteres suportam valores vazios do tipo String. Inserir [EmptyString] na caixa de parâmetro de entrada passa uma cadeia de caracteres vazia para o parâmetro. Além disso, os parâmetros de cadeia de caracteres não suportam Null. Se você não passar nenhum valor para um parâmetro de cadeia de caracteres, o PowerShell o interpretará como Nulo.

Iniciar um runbook publicado usando cmdlets do PowerShell e atribuir parâmetros

Cmdlets do Azure Resource Manager: você pode iniciar um runbook de automação que foi criado em um grupo de recursos usando Start-AzAutomationRunbook.

   $params = @{"VMName"="WSVMClassic";"resourceGroupeName"="WSVMClassicSG"}

   Start-AzAutomationRunbook -AutomationAccountName "TestAutomation" -Name "Get-AzureVMGraphical" –ResourceGroupName $resourceGroupName -Parameters $params

Cmdlets do modelo de implantação clássico do Azure: você pode iniciar um runbook de automação que foi criado em um grupo de recursos padrão usando Start-AzureAutomationRunbook.

   $params = @{"VMName"="WSVMClassic"; "ServiceName"="WSVMClassicSG"}

   Start-AzureAutomationRunbook -AutomationAccountName "TestAutomation" -Name "Get-AzureVMGraphical" -Parameters $params

Nota

Quando você inicia um runbook usando cmdlets do PowerShell, um parâmetro padrão, MicrosoftApplicationManagementStartedBy, é criado com o valor PowerShell. Você pode exibir esse parâmetro no painel Detalhes do trabalho.

Iniciar um runbook usando um SDK e atribuir parâmetros

Método do Azure Resource Manager: você pode iniciar um runbook usando o SDK de uma linguagem de programação. Abaixo está um trecho de código C# para iniciar um runbook em sua conta de automação. Você pode visualizar todo o código em nosso repositório GitHub.

public Job StartRunbook(string runbookName, IDictionary<string, string> parameters = null)
{
  var response = AutomationClient.Jobs.Create(resourceGroupName, automationAccount, new JobCreateParameters
  {
    Properties = new JobCreateProperties
    {
      Runbook = new RunbookAssociationProperty
      {
        Name = runbookName
      },
      Parameters = parameters
    }
  });
  return response.Job;
}

Método de modelo de implantação clássico do Azure: você pode iniciar um runbook usando o SDK de uma linguagem de programação. Abaixo está um trecho de código C# para iniciar um runbook em sua conta de automação. Você pode visualizar todo o código em nosso repositório GitHub.

public Job StartRunbook(string runbookName, IDictionary<string, string> parameters = null)
{
  var response = AutomationClient.Jobs.Create(automationAccount, new JobCreateParameters
  {
    Properties = new JobCreateProperties
    {
      Runbook = new RunbookAssociationProperty
      {
        Name = runbookName
      },
      Parameters = parameters
    }
  });
  return response.Job;
}

Para iniciar esse método, crie um dicionário para armazenar os parâmetros VMName do runbook e resourceGroupName seus valores. Em seguida, inicie o runbook. Abaixo está o trecho de código C# para chamar o método definido acima.

IDictionary<string, string> RunbookParameters = new Dictionary<string, string>();

// Add parameters to the dictionary.
RunbookParameters.Add("VMName", "WSVMClassic");
RunbookParameters.Add("resourceGroupName", "WSSC1");

//Call the StartRunbook method with parameters
StartRunbook("Get-AzureVMGraphical", RunbookParameters);

Inicie um runbook usando a API REST e atribua parâmetros

Você pode criar e iniciar um trabalho de runbook com a API REST de Automação do Azure usando o PUT método com o seguinte URI de solicitação: https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Automation/automationAccounts/{automationAccountName}/jobs/{jobName}?api-version=2017-05-15-preview

No URI de solicitação, substitua os seguintes parâmetros:

subscriptionId: Sua ID de assinatura do Azure.
resourceGroupName: O nome do grupo de recursos para a conta de automação.
automationAccountName: O nome da conta de automação hospedada no serviço de nuvem especificado.
jobName: O GUID para o trabalho. Os GUIDs no PowerShell podem ser criados usando [GUID]::NewGuid().ToString()*o .

Para passar parâmetros para o trabalho de runbook, use o corpo da solicitação. Ele usa as seguintes informações, fornecidas no formato JSON:

Nome do runbook: Obrigatório. O nome do runbook para o trabalho iniciar.
Parâmetros do runbook: Opcional. Um dicionário da lista de parâmetros no formato (nome, valor), onde name é do tipo String e value pode ser qualquer valor JSON válido.

Se você quiser iniciar o runbook Get-AzureVMTextual criado anteriormente com VMName e resourceGroupName como parâmetros, use o seguinte formato JSON para o corpo da solicitação.

    {
      "properties":{
        "runbook":{
        "name":"Get-AzureVMTextual"},
      "parameters":{
         "VMName":"WindowsVM",
         "resourceGroupName":"ContosoSales"}
        }
    }

Um código de status HTTP 201 será retornado se o trabalho for criado com êxito. Para obter mais informações sobre cabeçalhos de resposta e o corpo da resposta, consulte Criar um trabalho de runbook usando a API REST.

Testar um runbook e atribuir parâmetros

Quando você testa a versão de rascunho do seu runbook usando a opção de teste, a página Teste é aberta. Use esta página para configurar valores para os parâmetros que você criou.

Testar e atribuir parâmetros

Vincular uma agenda a um runbook e atribuir parâmetros

Você pode vincular um cronograma ao seu runbook para que o runbook comece em um horário específico. Você atribui parâmetros de entrada quando cria a agenda, e o runbook usa esses valores quando é iniciado pela agenda. Não é possível salvar o agendamento até que todos os valores de parâmetros obrigatórios sejam fornecidos.

Programar e atribuir parâmetros

Criar um webhook para um runbook e atribuir parâmetros

Você pode criar um webhook para seu runbook e configurar os parâmetros de entrada do runbook. Não é possível salvar o webhook até que todos os valores de parâmetros obrigatórios sejam fornecidos.

Criar webhook e atribuir parâmetros

Quando você executa um runbook usando um webhook, o parâmetro [WebhookData](automation-webhooks.md) de entrada predefinido é enviado, juntamente com os parâmetros de entrada que você define.

Parâmetro WebhookData

Transmitir um objeto JSON para um runbook

Pode ser útil armazenar dados que você deseja passar para um runbook em um arquivo JSON. Por exemplo, você pode criar um arquivo JSON que contenha todos os parâmetros que deseja passar para um runbook. Para fazer isso, você deve converter o código JSON em uma cadeia de caracteres e, em seguida, converter a cadeia de caracteres em um objeto do PowerShell antes de passá-lo para o runbook.

Esta seção usa um exemplo no qual um script do PowerShell chama Start-AzAutomationRunbook para iniciar um runbook do PowerShell, passando o conteúdo do arquivo JSON para o runbook. O runbook do PowerShell inicia uma VM do Azure recuperando os parâmetros para a VM do objeto JSON.

Criar o arquivo JSON

Digite o código a seguir em um arquivo de texto e salve-o como test.json em algum lugar no computador local.

{
   "VmName" : "TestVM",
   "ResourceGroup" : "AzureAutomationTest"
}

Criar o runbook

Crie um novo runbook do PowerShell chamado Test-Json na Automação do Azure.

Para aceitar os dados JSON, o runbook deve tomar um objeto como um parâmetro de entrada. O runbook pode usar as propriedades definidas no arquivo JSON.

Param(
     [parameter(Mandatory=$true)]
     [object]$json
)

# Ensures you do not inherit an AzContext in your runbook
Disable-AzContextAutosave -Scope Process

# Connect to Azure with system-assigned managed identity
$AzureContext = (Connect-AzAccount -Identity).context

# set and store context
$AzureContext = Set-AzContext -SubscriptionName $AzureContext.Subscription -DefaultProfile $AzureContext

# Convert object to actual JSON
$json = $json | ConvertFrom-Json

# Use the values from the JSON object as the parameters for your command
Start-AzVM -Name $json.VMName -ResourceGroupName $json.ResourceGroup -DefaultProfile $AzureContext

Se você quiser que o runbook seja executado com a identidade gerenciada atribuída ao sistema, deixe o código como está. Se preferir usar uma identidade gerenciada atribuída pelo usuário, então:

Da linha 10, remover $AzureContext = (Connect-AzAccount -Identity).context,
Substitua-o por $AzureContext = (Connect-AzAccount -Identity -AccountId <ClientId>).context, e
Insira a ID do cliente.

Salve e publique este runbook em sua conta de automação.

Chamar o runbook do PowerShell

Agora você pode chamar o runbook de sua máquina local usando o Azure PowerShell.

Entre no Azure conforme mostrado. Depois, você será solicitado a inserir suas credenciais do Azure.
```
Connect-AzAccount
```
Nota

Para runbooks do PowerShell, Add-AzAccount e Add-AzureRMAccount são aliases para Connect-AzAccount. Observe que esses aliases não estão disponíveis para runbooks gráficos. Um runbook gráfico só pode usar Connect-AzAccount a si mesmo.
Obtenha o conteúdo do arquivo JSON salvo e converta-o em uma cadeia de caracteres. JsonPath indica o caminho onde você salvou o arquivo JSON.
```
$json =  (Get-content -path 'JsonPath\test.json' -Raw) | Out-string
```
Converta o conteúdo da cadeia de caracteres em $json um objeto do PowerShell.
```
$JsonParams = @{"json"=$json}
```
Crie uma tabela hash para os parâmetros de Start-AzAutomationRunbook.
```
$RBParams = @{
     AutomationAccountName = 'AATest'
     ResourceGroupName = 'RGTest'
     Name = 'Test-Json'
     Parameters = $JsonParams
}
```
Observe que você está definindo o valor de para o objeto do Parameters PowerShell que contém os valores do arquivo JSON.

Inicie o runbook.

$job = Start-AzAutomationRunbook @RBParams

Próximos passos

Para preparar um runbook textual, consulte Editar runbooks textuais na Automação do Azure.
Para preparar um runbook gráfico, consulte Autor de runbooks gráficos na Automação do Azure.

Partilhar via

Configurar parâmetros de entrada de runbook na automação

Tipos de entrada

Configurar parâmetros de entrada em runbooks do PowerShell

Configurar parâmetros de entrada em runbooks gráficos

Configurar parâmetros de entrada em runbooks Python

Atribuir valores a parâmetros de entrada em runbooks

Iniciar um runbook e atribuir parâmetros

Iniciar um runbook publicado usando o portal do Azure e atribuir parâmetros

Iniciar um runbook publicado usando cmdlets do PowerShell e atribuir parâmetros

Iniciar um runbook usando um SDK e atribuir parâmetros

Inicie um runbook usando a API REST e atribua parâmetros

Testar um runbook e atribuir parâmetros

Vincular uma agenda a um runbook e atribuir parâmetros

Criar um webhook para um runbook e atribuir parâmetros

Transmitir um objeto JSON para um runbook

Criar o arquivo JSON

Criar o runbook

Chamar o runbook do PowerShell

Próximos passos

Comentários

Recursos adicionais