Partilhar via

Iniciar um runbook a partir de um webhook

  • Artigo

Um webhook permite a um serviço externo iniciar um runbook específico na Automatização do Azure através de um único pedido HTTP. Os serviços externos incluem os Serviços do Azure DevOps, o GitHub, os registos do Azure Monitor e as aplicações personalizadas. Esse serviço pode usar um webhook para iniciar um runbook sem implementar a API de Automação do Azure completa. Você pode comparar webhooks com outros métodos de iniciar um runbook em Iniciando um runbook na Automação do Azure.

WebhooksVisão geral

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

Propriedades do Webhook

A tabela seguinte descreve as propriedades que tem de configurar para um webhook.

Propriedade Descrição
Nome Nome do webhook. Você pode fornecer o nome que quiser, desde que não seja exposto ao cliente. Só é utilizado para identificar o runbook na Automatização do Azure. Como melhor prática, deve dar ao webhook um nome relacionado com o cliente que o utiliza.
URL URL do webhook. Este é o endereço exclusivo que um cliente chama com um HTTP POST para iniciar o runbook associado ao webhook. É gerado automaticamente quando cria o webhook. Não pode especificar um URL personalizado.

O URL contém um token de segurança que permite que um sistema de terceiros invoque o runbook sem autenticação adicional. Por este motivo, deve tratar o URL como uma palavra-passe. Por motivos de segurança, você só pode exibir a URL no portal do Azure ao criar o webhook. Observe o URL em um local seguro para uso futuro.
Data de validade Data de expiração do webhook, após a qual já não poderá ser utilizado. Pode modificar a data de expiração após a criação do webhook, desde que o webhook não tenha expirado.
Ativado Configuração que indica se o webhook está habilitado por padrão quando é criado. Se você definir essa propriedade como Disabled, nenhum cliente poderá usar o webhook. Você pode 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 para quaisquer parâmetros de runbook obrigatórios e pode incluir valores para parâmetros opcionais. Um valor de parâmetro configurado para um webhook pode ser modificado mesmo após a criação do webhook. Vários webhooks vinculados a um único runbook podem usar valores de parâmetros de runbook diferentes. 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 suporta um único parâmetro chamado WebhookData. Este parâmetro define um objeto que contém dados que o cliente inclui em uma solicitação POST.

Propriedades WebhookData

O WebhookData parâmetro tem as seguintes propriedades:

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

Não há nenhuma configuração do webhook necessária para suportar o WebhookData parâmetro, e o runbook não é necessário para aceitá-lo. Se o runbook não definir o parâmetro, todos os detalhes da solicitação enviada pelo cliente serão ignorados.

Nota

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

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

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

Por exemplo, se você estiver iniciando o runbook a seguir no portal do Azure e quiser passar alguns dados de webhook de exemplo para teste, deverá passar 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 passamos o seguinte objeto JSON na interface do usuário para o WebhookData parâmetro. Este exemplo, com retornos de carro e caracteres de nova linha, corresponde ao formato que é passado 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 da interface do usuário

Nota

A Automação do Azure registra os valores de todos os parâmetros de entrada com o trabalho de runbook. Assim, qualquer entrada fornecida pelo cliente na solicitação webhook é registrada e disponível para qualquer pessoa com acesso ao trabalho de automação. Por esse motivo, você deve ser cauteloso ao incluir informações confidenciais em chamadas webhook.

Segurança do webhook

A segurança de um webhook depende da privacidade do URL, que contém um token de segurança que permite invocar o webhook. 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 este motivo, os clientes não devem utilizar webhooks para runbooks que executam operações altamente confidenciais sem utilizar um meio alternativo de validar o pedido.

Considere as seguintes estratégias:

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

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

  • A Automação do Azure dá suporte a tags de serviço de rede virtual do Azure, especificamente GuestAndHybridManagement. Você pode usar marcas de serviço para definir controles de acesso à rede em grupos de segurança de rede ou no Firewall do Azure e acionar webhooks de dentro de sua rede virtual. É possível utilizar etiquetas de serviço em vez de endereços IP específicos quando criar regras de segurança. Ao especificar o nome da etiqueta de serviço GuestAndHybridManagement no campo de origem ou destino adequado de uma regra, pode permitir ou negar o tráfego para o serviço de Automatização. Esta etiqueta de serviço não suporta permitir um controlo mais granular ao restringir os intervalos de IP a uma região específica.

Criar um webhook

Nota

Quando você usa o webhook com o runbook do PowerShell 7, ele converte automaticamente o parâmetro de entrada do webhook em um JSON inválido. Para obter mais informações, consulte Problemas conhecidos - PowerShell 7.1 (visualização). Recomendamos que você use o webhook com o runbook do PowerShell 5.

  1. Crie o 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 PowerShell ou API REST. Um webhook requer um runbook publicado. Este passo a passo usa uma versão modificada do runbook criado a partir de Criar um runbook de Automação do Azure.

    1. Inicie sessão no portal do Azure.

    2. No portal do Azure, navegue até sua conta de automação.

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

    4. Selecione seu runbook na lista para abrir a página 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.

      Adicione a página do webhook com a criação realçada.

    7. Digite o Nome do webhook. A data de expiração do campo Expira por padrão para um ano a partir da data atual.

    8. Clique no ícone de cópia ou pressione Ctrl + C copie o URL do webhook. Em seguida, salve o URL em um local seguro.

      Crie uma página de webhook com o URL realçado.

      Importante

      Depois de criar o webhook, não é possível recuperar o URL novamente. Certifique-se de copiá-lo e gravá-lo como acima.

    9. Selecione OK para retornar à página Adicionar Webhook .

    10. Na página Adicionar Webhook, selecione Configurar parâmetros e executar configurações para abrir a página Parâmetros.

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

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

    12. Na página Adicionar Webhook, selecione Criar. O webhook é criado e você retorna à página Visão geral do Runbook.

Use um webhook

Este exemplo usa o cmdlet do PowerShell Invoke-WebRequest para enviar a solicitação POST para seu novo webhook.

  1. Prepare os valores para passar para o runbook como o corpo para a chamada webhook. Para valores relativamente simples, você pode criar scripts para os valores da seguinte maneira:

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

$body = ConvertTo-Json -InputObject $Names

  2. Para conjuntos maiores, você pode querer usar um arquivo. Crie um arquivo chamado names.json e, em seguida, cole o seguinte código:

    [
    { "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 seguintes comandos do PowerShell.

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

  3. Execute os seguintes comandos do PowerShell 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, foram feitas duas chamadas para os dois métodos diferentes de produção do corpo. Para a produção, use apenas um método. A saída deve ser semelhante da seguinte forma (apenas uma saída é mostrada):

    Saída da chamada webhook.

    O cliente recebe um dos seguintes códigos de devolução do POST pedido.

    Código Texto Description
    202 Aceite A solicitação foi aceita e o runbook foi enfileirado com êxito.
    400 Pedido Incorreto O pedido não foi aceite por uma das seguintes razões:
    • O webhook expirou.
    • O webhook está desativado.
    • O token no URL é inválido.
    404 Não Encontrado O pedido não foi aceite por uma das seguintes razões:
    • O webhook não foi encontrado.
    • O runbook não foi encontrado.
    • A conta não foi encontrada.
    500 Erro de Servidor Interno O URL era válido, mas ocorreu um erro. Reenvie a solicitação.

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

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

  4. O cmdlet do PowerShell Get-AzAutomationJobOutput será usado para obter a saída. A API de Automação do Azure também pode ser usada.

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

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

    Quando você aciona um runbook criado na etapa anterior, ele criará um trabalho e a saída deverá ser semelhante à seguinte:

    Saída do trabalho webhook.

Atualizar um webhook

Quando um webhook é criado, tem um período de validade de 10 anos, após o qual expira automaticamente. Depois que um webhook expirar, você não poderá reativá-lo. Você só pode removê-lo e, em seguida, recriá-lo. Pode expandir um webhook que ainda não atingiu o tempo de expiração. Para estender um webhook, execute as seguintes etapas.

  1. Navegue para o runbook que contém o webhook.
  2. Em Recursos, selecione Webhooks e, em seguida, o webhook que você deseja estender.
  3. Na página Webhook, escolha uma nova data e hora de expiração e selecione Salvar.

Analise a chamada de API Webhook - Update e o cmdlet do PowerShell Set-AzAutomationWebhook para outras possíveis modificações.

Clean up resources (Limpar recursos)

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

  • Usando o PowerShell, o cmdlet Remove-AzAutomationWebhook pode ser usado conforme mostrado abaixo. Nenhuma saída é retornada.

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

  • Usando REST, o REST Webhook - Delete API pode ser usado como mostrado abaixo.

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

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

Criar runbook e webhook com modelo ARM

Webhooks de automação também podem ser criados usando modelos do Azure Resource Manager . Este 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, em seguida, cole o seguinte código:

    {
    "$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 da sua máquina. 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

    Nota

    Por motivos de segurança, o URI só é retornado na primeira vez que um modelo é implantado.

Próximos passos