Iniciar um runbook a partir de um webhook

  • Artigo

Um webhook permite que um serviço externo inicie um runbook específico na Automação do Azure por meio de uma única solicitação HTTP. Os serviços externos incluem Azure DevOps Services, GitHub, logs do Azure Monitor e aplicativos personalizados. Esse serviço pode usar um webhook para iniciar um runbook sem implementar a API de Automação do Azure completa. Você pode comparar os webhooks a outros métodos para iniciar um runbook em Como iniciar um runbook na Automação do Azure.

WebhooksOverview

Para entender os requisitos do cliente para TLS 1.2 ou posterior com webhooks, confira TLS para Automação do Azure.

Propriedades de webhook

A tabela a seguir descreve as propriedades que devem ser configuradas para um webhook.

Propriedade Descrição
Nome Nome do webhook. É possível fornecer qualquer nome desejado, já que ele não é exposto ao cliente. Ele é usado apenas por você para identificar o runbook na Automação do Azure. Como melhor prática, você deve atribuir ao webhook um nome relacionado ao cliente que o utiliza.
URL URL do webhook. É o endereço exclusivo que um cliente chama com um HTTP POST para iniciar o runbook vinculado ao webhook. Ele é gerado automaticamente quando você cria o webhook. Você não pode especificar uma URL personalizada.

A URL contém um token de segurança que permite que o runbook seja invocado por um sistema de terceiros sem autenticação adicional. Por esse motivo, você deve tratar a URL como uma senha. Por motivos de segurança, só é possível exibir a URL no portal do Azure ao criar o webhook. Anote a URL em um local seguro para uso futuro.
Data de validade Data de validade do webhook, após a qual ele não pode mais ser usado. É possível mudar a data de validade após a criação do webhook, desde que o webhook não tenha expirado.
Enabled Configuração que indica se o webhook está habilitado por padrão quando é criado. Se você definir essa propriedade como desabilitada, nenhum cliente poderá usar o webhook. É possível definir essa propriedade ao criar o webhook ou em qualquer outro momento após sua criação.

Parâmetros usados quando o webhook inicia um runbook

Um webhook pode definir valores para parâmetros de runbook que são usados quando o runbook é iniciado. O webhook deve incluir valores de parâmetros obrigatórios do runbook e pode incluir valores de parâmetros opcionais. Um valor de parâmetro configurado para um webhook pode ser modificado até mesmo depois da criação do webhook. Vários webhooks vinculados a um único runbook podem usar valores de parâmetros diferentes de runbook. Quando um cliente inicia um runbook usando um webhook, ele não pode substituir os valores de parâmetro definidos no webhook.

Para receber dados do cliente, o runbook pode aceitar um único parâmetro chamado WebhookData. Esse parâmetro define um objeto que contém dados que o cliente inclui em uma solicitação POST.

Propriedades de WebhookData

O parâmetro WebhookData tem as seguintes propriedades:

Propriedade Descrição
WebhookName Nome do webhook.
RequestHeader PSCustomObject que contém os cabeçalhos da solicitação POST de entrada.
RequestBody Corpo da solicitação POST de entrada. Esse corpo mantém qualquer formatação de dados, como cadeia de caracteres, JSON, XML ou dados codificados de formulário. O runbook deve ser escrito para trabalhar com o formato de dados esperado. O runbook deve ser escrito para trabalhar com o formato de dados esperado.

Nenhuma configuração do webhook é necessária para compatibilidade com o parâmetro WebhookData, e o runbook não precisa aceitá-lo. Se o runbook não definir o parâmetro, os detalhes da solicitação enviada pelo cliente serão ignorados.

Observação

Ao chamar um webhook, o cliente sempre deve armazenar qualquer valor de parâmetro em caso de falha da chamada. Se houver uma interrupção de rede ou um problema de conexão, o aplicativo não poderá recuperar chamadas de webhook com falha.

Se você especificar um valor para WebhookData na criação do webhook, ele será substituído com os dados da solicitação POST do cliente quando o webhook iniciar o runbook. Isso acontece mesmo que o aplicativo não inclua dados no corpo da solicitação.

Se você iniciar um runbook que define WebhookData usando um mecanismo diferente de um webhook, poderá fornecer um valor para WebhookData que o runbook reconheça. Esse valor deve ser um objeto com as mesmas propriedades que o parâmetro WebhookData para que o runbook possa trabalhar com ele da mesma forma que funciona com os objetos de WebhookData reais transmitidos por um webhook.

Por exemplo, se você estiver iniciando o runbook a seguir no portal do Azure e desejar transmitir alguns dados do webhook de exemplo para teste, você deverá transmitir os dados em JSON na interface do usuário.

Parâmetro WebhookData da interface do usuário

Para o próximo exemplo de runbook, vamos definir as seguintes propriedades para WebhookData:

  • WebhookName: MyWebhook
  • RequestBody: *[{'ResourceGroup': 'myResourceGroup','Name': 'vm01'},{'ResourceGroup': 'myResourceGroup','Name': 'vm02'}]*

Agora, transmitimos o seguinte objeto JSON na interface do usuário para o parâmetro WebhookData. Este exemplo, com retornos de carro e caracteres de nova linha, corresponde ao formato que é transmitido de um webhook.

{"WebhookName":"mywebhook","RequestBody":"[\r\n {\r\n \"ResourceGroup\": \"vm01\",\r\n \"Name\": \"vm01\"\r\n },\r\n {\r\n \"ResourceGroup\": \"vm02\",\r\n \"Name\": \"vm02\"\r\n }\r\n]"}

Iniciar o parâmetro WebhookData na interface do usuário

Observação

A Automação do Azure registra em log os valores de todos os parâmetros de entrada com o trabalho de runbook. Isso significa que qualquer entrada fornecida pelo cliente na solicitação webhook será conectada e estará disponível para qualquer pessoa com acesso ao trabalho de automação. Por esse motivo, você deve ter cuidado ao incluir informações confidenciais em chamadas webhook.

Segurança de webhook

A segurança de um webhook conta com a privacidade da sua URL, que contém um token de segurança que permite que ele seja invocado. A Automação do Azure não executa nenhuma autenticação em uma solicitação desde que ela seja feita para a URL correta. Por esse motivo, os clientes não devem usar webhooks para runbooks que executam operações altamente confidenciais sem usar um meio alternativo de validar a solicitação.

Considere as seguintes estratégias:

  • É possível incluir lógica em um runbook para determinar se ele é chamado por um webhook. Faça com que o runbook verifique a propriedade WebhookName do parâmetro WebhookData. O runbook pode executar uma validação adicional procurando informações específicas nas propriedades RequestHeader e RequestBody.

  • Faça com que o runbook execute alguma validação de uma condição externa ao receber uma solicitação de webhook. Por exemplo, considere um runbook que é chamado pelo GitHub sempre que houver uma nova confirmação para um repositório GitHub. O runbook pode se conectar ao GitHub para validar se uma nova confirmação ocorreu antes de continuar.

  • A Automação do Azure dá suporte a marcas de serviço de rede virtual do Azure, especificamente GuestAndHybridManagement. É possível usar marcas de serviço para definir os controles de acesso à rede em grupos de segurança de rede ou no Firewall do Azure e disparar WebHooks de dentro de sua rede virtual. Marcas de serviço podem ser usadas no lugar de endereços IP específicos quando você cria regras de segurança. Ao especificar o nome da marca de serviço GuestAndHybridManagement no campo apropriado de destino ou origem de uma regra, é possível permitir ou negar o tráfego para o serviço de Automação. Essa marca de serviço restringe intervalos de IP para uma região específica e, com isso, não oferece suporte à permissão de controle mais granular.

Criar um webhook

Observação

Ao usar o webhook com o runbook do PowerShell 7, ele converte automaticamente o parâmetro de entrada do webhook em um JSON inválido. Para saber mais, confira Problemas conhecidos – PowerShell 7.1 (versão prévia). É recomendável usar o webhook com o runbook do PowerShell 5.

  1. Crie um runbook do PowerShell com o seguinte código:

    param
(
    [Parameter(Mandatory=$false)]
    [object] $WebhookData
)

write-output "start"
write-output ("object type: {0}" -f $WebhookData.gettype())
write-output $WebhookData
write-output "`n`n"
write-output $WebhookData.WebhookName
write-output $WebhookData.RequestBody
write-output $WebhookData.RequestHeader
write-output "end"

if ($WebhookData.RequestBody) { 
    $names = (ConvertFrom-Json -InputObject $WebhookData.RequestBody)

        foreach ($x in $names)
        {
            $name = $x.Name
            Write-Output "Hello $name"
        }
}
else {
    Write-Output "Hello World!"
}

  2. Crie um webhook usando o portal do Azure, ou o PowerShell ou a API REST. Um webhook requer um runbook publicado. Essa orientação usa uma versão modificada do runbook criado em Criar um runbook de automação do Azure.

    1. Entre no portal do Azure.

    2. No portal do Azure, abra sua Conta de Automação.

    3. Em Automação do Processo, selecione Runbooks para abrir a página Runbooks.

    4. Selecione o runbook na lista para abrir a página de Visão geral do runbook.

    5. Selecione Adicionar webhook para abrir a página Adicionar webhook.

      Página de visão geral do runbook com Adicionar webhook realçado.

    6. Na página Adicionar webhook, selecione Criar novo webhook.

      Página Adicionar webhook com criar realçado.

    7. Insira o nome do webhook. A data de validade do campo Expira em está definida como padrão de um ano a partir da data atual.

    8. Clique no ícone Copiar ou pressione Ctrl + C para copiar a URL do webhook. Em seguida, salve a URL em um local seguro.

      Página Criar webhook com a URL realçada.

      Importante

      Quando você cria o webhook, não é possível recuperar a URL novamente. Certifique-se de copiá-lo e gravá-lo como mostrado acima.

    9. Selecione OK para voltar à página Adicionar webhook.

    10. Na página Adicionar webhook, selecione Definir parâmetros e configurações de execução para abrir a página de parâmetros.

      Página Adicionar webhook com os parâmetros realçados.

    11. Examine a página de Parâmetros. Para o runbook de exemplo usado neste artigo, nenhuma alteração é necessária. Selecione OK para voltar à página Adicionar webhook.

    12. Na página Adicionar webhook, selecione Criar. O webhook é criado e você é levado de volta para a página de Visão geral do Runbook.

Usar um webhook

Este exemplo usa o cmdlet Invoke-WebRequest do PowerShell para enviar a solicitação POST ao webhook recém-criado.

  1. Prepare os valores a serem passados para o runbook como o corpo da chamada de webhook. No caso de valores relativamente simples, você pode gerar o script dos valores da seguinte maneira:

    $Names  = @(
            @{ Name="Hawaii"},
            @{ Name="Seattle"},
            @{ Name="Florida"}
        )

$body = ConvertTo-Json -InputObject $Names

  2. Para conjuntos maiores, é recomendado usar um arquivo. Crie um arquivo chamado names.json e cole o código a seguir:

    [
    { "Name": "Hawaii" },
    { "Name": "Florida" },
    { "Name": "Seattle" }
]

    Altere o valor da variável $file com o caminho real para o arquivo JSON antes de executar os comandos do PowerShell a seguir.

    # Revise file path with actual path
$file = "path\names.json"
$bodyFile = Get-Content -Path $file

  3. Execute os comandos do PowerShell a seguir para chamar o webhook usando a API REST.

    $response = Invoke-WebRequest -Method Post -Uri $webhookURI -Body $body -UseBasicParsing
$response

$responseFile = Invoke-WebRequest -Method Post -Uri $webhookURI -Body $bodyFile -UseBasicParsing
$responseFile

    Para fins ilustrativos, duas chamadas foram feitas para os dois métodos diferentes de produção do corpo. Na produção, use apenas um método. A saída deve ser semelhante à seguinte (apenas uma saída é mostrada):

    Saída de chamada de webhook.

    O cliente recebe um dos seguintes códigos de retorno da solicitação POST.

    Código Texto Descrição
    202 Aceita A solicitação foi aceita e o runbook foi enfileirado com êxito.
    400 Solicitação incorreta A solicitação não foi aceita por um dos motivos a seguir:
    • O webhook expirou.
    • O webhook está desabilitado.
    • O token na URL é inválido.
    404 Não encontrado A solicitação não foi aceita por um dos motivos a seguir:
    • O webhook não foi encontrado.
    • O runbook não foi encontrado.
    • A conta não foi encontrada.
    500 Erro interno do servidor A URL era válida, mas ocorreu um erro. Envie a solicitação novamente.

    Supondo que a solicitação seja bem-sucedida, a resposta do webhook conterá a ID de trabalho no formato JSON conforme mostrado abaixo. Ela contém uma ID de trabalho única, mas o formato JSON permite possíveis aprimoramentos futuros.

    {"JobIds":["<JobId>"]}

  4. Será usado o cmdlet Get-AzAutomationJobOutput do PowerShell para obter a saída. Também é possível usar a API de automação do Azure.

    #isolate job ID
$jobid = (ConvertFrom-Json ($response.Content)).jobids[0]

# Get output
Get-AzAutomationJobOutput `
    -AutomationAccountName $automationAccount `
    -Id $jobid `
    -ResourceGroupName $resourceGroup `
    -Stream Output

    Ao disparar um runbook criado na etapa anterior, ele criará um trabalho e a saída deverá ser semelhante à seguinte:

    Saída de um trabalho do webhook.

Atualizar um webhook

Quando um webhook é criado, ele tem um período de validade de dez anos, após o qual ele expira automaticamente. Depois que um webhook vencer, você não poderá reativá-lo. Só é possível removê-lo e, depois, recriá-lo. Você pode estender um webhook que ainda não atingiu o prazo de validade. Para estender um webhook, execute as etapas a seguir.

  1. Navegue até o runbook que contém o webhook.
  2. Em Recursos, selecione WebHooks e, em seguida, selecione o webhook que você deseja estender.
  3. Na página Webhook, escolha uma nova data e hora de validade e clique em Salvar.

Examine a chamada de API webhook - Atualização e o cmdlet do PowerShell Set-AzAutomationWebhook para demais modificações possíveis.

Limpar os recursos

Aqui estão exemplos de como remover um webhook de um runbook de automação.

  • No PowerShell, é possível usar o cmdlet Remove-AzAutomationWebhook, conforme demonstrado abaixo. Nenhuma saída é retornada.

    Remove-AzAutomationWebhook `
    -ResourceGroup $resourceGroup `
    -AutomationAccountName $automationAccount `
    -Name $psWebhook

  • No caso do REST, a API REST Webhook - Excluir pode ser usada conforme mostrado abaixo.

    Invoke-WebRequest -Method Delete -Uri $restURI -Headers $authHeader

    Uma saída de StatusCode : 200 significa uma exclusão bem-sucedida.

Criar runbooks e webhooks com modelos do ARM

Ele também pode ser criado usando a automação por meio de modelos do Azure Resource Manager. O modelo de exemplo cria uma conta de automação, quatro runbooks e um webhook para o runbook nomeado.

  1. Crie um arquivo chamado webhook_deploy.json e cole o código a seguir:

    {
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "automationAccountName": {
            "type": "String",
            "metadata": {
                "description": "Automation account name"
            }
        },
        "webhookName": {
            "type": "String",
            "metadata": {
                "description": "Webhook Name"
            }
        },
        "runbookName": {
            "type": "String",
            "metadata": {
                "description": "Runbook Name for which webhook will be created"
            }
        },
        "WebhookExpiryTime": {
            "type": "String",
            "metadata": {
                "description": "Webhook Expiry time"
            }
        },
        "_artifactsLocation": {
            "defaultValue": "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.automation/101-automation/",
            "type": "String",
            "metadata": {
                "description": "URI to artifacts location"
            }
        }
    },
    "resources": [
        {
            "type": "Microsoft.Automation/automationAccounts",
            "apiVersion": "2020-01-13-preview",
            "name": "[parameters('automationAccountName')]",
            "location": "[resourceGroup().location]",
            "properties": {
                "sku": {
                    "name": "Free"
                }
            },
            "resources": [
                {
                    "type": "runbooks",
                    "apiVersion": "2018-06-30",
                    "name": "[parameters('runbookName')]",
                    "location": "[resourceGroup().location]",
                    "dependsOn": [
                        "[parameters('automationAccountName')]"
                    ],
                    "properties": {
                        "runbookType": "Python2",
                        "logProgress": "false",
                        "logVerbose": "false",
                        "description": "Sample Runbook",
                        "publishContentLink": {
                            "uri": "[uri(parameters('_artifactsLocation'), 'scripts/AzureAutomationTutorialPython2.py')]",
                            "version": "1.0.0.0"
                        }
                    }
                },
                {
                    "type": "webhooks",
                    "apiVersion": "2018-06-30",
                    "name": "[parameters('webhookName')]",
                    "dependsOn": [
                        "[parameters('automationAccountName')]",
                        "[parameters('runbookName')]"
                    ],
                    "properties": {
                        "isEnabled": true,
                        "expiryTime": "[parameters('WebhookExpiryTime')]",
                        "runbook": {
                            "name": "[parameters('runbookName')]"
                        }
                    }
                }
            ]
        }
    ],
    "outputs": {
        "webhookUri": {
            "type": "String",
            "value": "[reference(parameters('webhookName')).uri]"
        }
    }
}

  2. O exemplo de código do PowerShell a seguir implanta o modelo a partir do seu computador. Forneça um valor apropriado para as variáveis e, em seguida, execute o script.

    $resourceGroup = "resourceGroup"
$templateFile = "path\webhook_deploy.json"
$armAutomationAccount = "automationAccount"
$armRunbook = "ARMrunbookName"
$armWebhook = "webhookName"
$webhookExpiryTime = "12-31-2022"

New-AzResourceGroupDeployment `
    -Name "testDeployment" `
    -ResourceGroupName $resourceGroup `
    -TemplateFile $templateFile `
    -automationAccountName $armAutomationAccount `
    -runbookName $armRunbook `
    -webhookName $armWebhook `
    -WebhookExpiryTime $webhookExpiryTime

    Observação

    Por segurança, o URI é retornado apenas na primeira vez que um modelo é implantado.

Próximas etapas