Inicie um runbook na Automação do Azure

A tabela a seguir o ajuda a determinar o método para inicializar um runbook na Automação do Azure, que seja mais adequado ao seu cenário específico. Este artigo inclui detalhes sobre como iniciar um runbook com o portal do Azure e com o Windows PowerShell. Detalhes sobre outros métodos são fornecidos em outros documentos que você pode acessar através dos links abaixo.

Método	Características
Portal do Azure	Método mais simples com interface do usuário interativa. Formulário para fornecer valores de parâmetro simples. Controle facilmente o estado do trabalho. Acesso autenticado com o logon do Azure.
Windows PowerShell	Chame da linha de comando com os cmdlets do Windows PowerShell. Pode ser incluído em um recurso automatizado com várias etapas. A solicitação é autenticada com certificado ou entidade de usuário/entidade de serviço OAuth. Fornece valores de parâmetro simples e complexos. Acompanhe o estado do trabalho. É necessário um cliente para dar suporte a cmdlets do PowerShell.
API de Automação do Azure	Método mais flexível, mas também o mais complexo. Chame de qualquer código personalizado que possa fazer solicitações HTTP. A solicitação autenticada com certificado ou entidade de usuário/entidade de serviço OAuth. Fornece valores de parâmetro simples e complexos. Se você estiver chamando um runbook Python usando a API, o conteúdo JSON deve ser serializado. Acompanhe o estado do trabalho.
Webhooks	Inicie o runbook de uma solicitação HTTP única. Autenticado com token de segurança na URL. O cliente não pode substituir valores de parâmetro especificados quando o webhook foi criado. O runbook pode definir um único parâmetro que é preenchido com os detalhes da solicitação HTTP. Sem capacidade de acompanhar o estado do trabalho por meio da URL do webhook.
Responder a um Alerta do Azure	Inicie um runbook em resposta a um alerta do Azure. Configure o webhook para o runbook e vincule ao alerta. Autenticado com token de segurança na URL.
Agendar	Inicie automaticamente o runbook em um cronograma horário, diário, semanal ou mensal. Manipule a agenda pelo portal do Azure, por cmdlets do PowerShell ou pela a API do Azure. Fornece os valores de parâmetro a serem usados com a agenda.
De Outro Runbook	Use um runbook como uma atividade em outro runbook. É útil para funcionalidades usadas por vários runbooks. Forneça valores de parâmetro para o runbook filho e use a saída no runbook pai.

A imagem a seguir ilustra o processo passo a passo detalhado no ciclo de vida de um runbook. Ela inclui as diferentes formas como um runbook é iniciado na Automação do Azure, que componentes são necessários para que o Hybrid Runbook Worker execute runbooks da Automação do Azure e as interações entre diferentes componentes. Para saber mais sobre a execução de runbooks de Automação em seu datacenter, veja hybrid runbook workers

Trabalhar com parâmetros do runbook

Quando você inicia um runbook por meio do Portal do Azure ou do Windows PowerShell, a instrução é enviada pelo serviço Web da Automação do Azure. Esse serviço não dá suporte a parâmetros com tipos de dados complexos. Se você precisa fornecer um valor para um parâmetro complexo, você deve chamá-lo embutido de outro runbook, como descrito em Runbooks filho na Automação do Azure.

O serviço Web da Automação do Azure fornece uma funcionalidade especial para os parâmetros usando certos tipos de dados, conforme descrito nas seções a seguir.

Valores nomeados

Se o parâmetro é do tipo de dados [object], você pode usar o seguinte formato JSON para enviar-lhe uma lista de valores nomeados: {Name1:'Value1', Name2:'Value2', Name3:'Value3'}. Esses valores devem ser tipos simples. O runbook recebe o parâmetro como um PSCustomObject com propriedades que correspondem a cada valor nomeado.

Considere o runbook de teste a seguir que aceita um parâmetro chamado user.

Workflow Test-Parameters
{
   param (
      [Parameter(Mandatory=$true)][object]$user
   )
    $userObject = $user | ConvertFrom-JSON
    if ($userObject.Show) {
        foreach ($i in 1..$userObject.RepeatCount) {
            $userObject.FirstName
            $userObject.LastName
        }
    }
}

O texto a seguir pode ser usado para o parâmetro user.

{FirstName:'Joe',LastName:'Smith',RepeatCount:'2',Show:'True'}

Isso resulta na seguinte saída:

Joe
Smith
Joe
Smith

Matrizes

Se o parâmetro é uma matriz, como [array] ou [string[]], você pode usar o seguinte formato JSON para enviar-lhe uma lista de valores: [Value1, Value2, Value3]. Esses valores devem ser tipos simples.

Considere o runbook de teste a seguir que aceita um parâmetro chamado user.

Workflow Test-Parameters
{
   param (
      [Parameter(Mandatory=$true)][array]$user
   )
    if ($user[3]) {
        foreach ($i in 1..$user[2]) {
            $ user[0]
            $ user[1]
        }
    }
}

O texto a seguir pode ser usado para o parâmetro user.

["Joe","Smith",2,true]

Isso resulta na seguinte saída:

Joe
Smith
Joe
Smith

Credenciais

Se o parâmetro é do tipo de dados PSCredential, forneça o nome de um ativo de credencial da Automação do Azure. O runbook recupera as credenciais com o nome que você especifica. O runbook de teste a seguir aceita um parâmetro chamado credential.

Workflow Test-Parameters
{
   param (
      [Parameter(Mandatory=$true)][PSCredential]$credential
   )
   $credential.UserName
}

O texto a seguir pode ser usado para o parâmetro user supondo que havia um ativo de credencial chamado My Credential.

My Credential

Supondo que o nome de usuário na credencial seja jsmith, a saída a seguir é exibida.

jsmith

Iniciar um runbook com o portal do Azure

1. No Portal do Azure, selecione Automação e, em seguida, selecione no nome de uma Conta de automação.
2. No painel esquerdo, selecione Runbooks.
3. Na página Runbooks, selecione um runbook e, em seguida, clique em Iniciar.
4. Se o runbook tiver parâmetros, você será solicitado a fornecer valores com uma caixa de texto a cada parâmetro. Para obter mais informações sobre parâmetros, confira Parâmetros de runbook.
5. Veja o status do trabalho do runbook no painel Trabalho.

Iniciar um runbook com o PowerShell

Use Start-AzAutomationRunbook para iniciar um runbook com o Windows PowerShell. O código de exemplo a seguir inicia um runbook chamado Test-Runbook.

Start-AzAutomationRunbook -AutomationAccountName "MyAutomationAccount" -Name "Test-Runbook" -ResourceGroupName "ResourceGroup01"

Start-AzAutomationRunbook retorna um objeto de trabalho que você pode usar para controlar o status depois que o runbook é iniciado. Você pode usar esse objeto de trabalho com Get-AzAutomationJob para determinar o status do trabalho e Get-AzAutomationJobOutput para recuperar sua saída. O código de exemplo a seguir inicia um runbook chamado Test-Runbook, aguarda até que ele seja concluído e exibe a sua saída.

$runbookName = "Test-Runbook"
$ResourceGroup = "ResourceGroup01"
$AutomationAcct = "MyAutomationAccount"

$job = Start-AzAutomationRunbook -AutomationAccountName $AutomationAcct -Name $runbookName -ResourceGroupName $ResourceGroup

$doLoop = $true
While ($doLoop) {
   $job = Get-AzAutomationJob -AutomationAccountName $AutomationAcct -Id $job.JobId -ResourceGroupName $ResourceGroup
   $status = $job.Status
   $doLoop = (($status -ne "Completed") -and ($status -ne "Failed") -and ($status -ne "Suspended") -and ($status -ne "Stopped"))
}

Get-AzAutomationJobOutput -AutomationAccountName $AutomationAcct -Id $job.JobId -ResourceGroupName $ResourceGroup -Stream Output

Se o runbook exigir parâmetros, você deve fornecê-los como uma tabela de hash. A chave da tabela de hash deve corresponder ao nome do parâmetro e o valor é o valor do parâmetro. O exemplo a seguir mostra como iniciar um runbook com dois parâmetros de cadeia de caracteres chamados FirstName e LastName, um número inteiro denominado RepeatCount e um parâmetro booliano denominado Show. Para obter mais informações sobre parâmetros, confira Parâmetros de runbook.

$params = @{"FirstName"="Joe";"LastName"="Smith";"RepeatCount"=2;"Show"=$true}
Start-AzAutomationRunbook -AutomationAccountName "MyAutomationAccount" -Name "Test-Runbook" -ResourceGroupName "ResourceGroup01" -Parameters $params

Próximas etapas

• Para obter detalhes sobre o gerenciamento de runbooks, consulte Gerenciamento de runbooks na Automação do Azure.
• Para obter detalhes do PowerShell, veja Documentos do PowerShell.
• Para solucionar problemas com a execução do runbook, confira Solução de problemas de runbook.