Iniciar runbook a partir de um webhookStart a runbook from a webhook

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.A webhook allows an external service to start a particular runbook in Azure Automation through a single HTTP request. Os serviços externos incluem Azure DevOps Services, GitHub, logs do Azure Monitor e aplicativos personalizados.External services include Azure DevOps Services, GitHub, Azure Monitor logs, and custom applications. Esse serviço pode usar um webhook para iniciar um runbook sem implementar a API de Automação do Azure completa.Such a service can use a webhook to start a runbook without implementing the full Azure Automation API. Você pode comparar os webhooks a outros métodos para iniciar um runbook em Como iniciar um runbook na Automação do Azure.You can compare webhooks to other methods of starting a runbook in Starting a runbook in Azure Automation.

Observação

O uso de um webhook para iniciar um runbook do Python não é compatível.Using a webhook to start a Python runbook is not supported.

WebhooksOverview

Para entender os requisitos do cliente para o TLS 1,2 com WebHooks, confira imposição TLS 1,2 para a automação do Azure.To understand client requirements for TLS 1.2 with webhooks, see TLS 1.2 enforcement for Azure Automation.

Propriedades de webhookWebhook properties

A tabela a seguir descreve as propriedades que devem ser configuradas para um webhook.The following table describes the properties that you must configure for a webhook.

PropriedadeProperty DescriçãoDescription
NomeName Nome do webhook.Name of the webhook. É possível fornecer qualquer nome desejado, já que ele não é exposto ao cliente.You can provide any name you want, since it isn't exposed to the client. Ele é usado apenas por você para identificar o runbook na Automação do Azure.It's only used for you to identify the runbook in Azure Automation. Como melhor prática, você deve atribuir ao webhook um nome relacionado ao cliente que o utiliza.As a best practice, you should give the webhook a name related to the client that uses it.
URLURL URL do webhook.URL of the webhook. É o endereço exclusivo que um cliente chama com um HTTP POST para iniciar o runbook vinculado ao webhook.This is the unique address that a client calls with an HTTP POST to start the runbook linked to the webhook. Ele é gerado automaticamente quando você cria o webhook.It's automatically generated when you create the webhook. Você não pode especificar uma URL personalizada.You can't specify a custom URL.

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.The URL contains a security token that allows a third-party system to invoke the runbook with no further authentication. Por esse motivo, você deve tratar a URL como uma senha.For this reason, you should treat the URL like a password. Por motivos de segurança, só é possível exibir a URL no portal do Azure ao criar o webhook.For security reasons, you can only view the URL in the Azure portal when creating the webhook. Anote a URL em um local seguro para uso futuro.Note the URL in a secure location for future use.
Data de validadeExpiration date Data de validade do webhook, após a qual ele não pode mais ser usado.Expiration date of the webhook, after which it can no longer be used. É possível mudar a data de validade após a criação do webhook, desde que o webhook não tenha expirado.You can modify the expiration date after the webhook is created, as long as the webhook has not expired.
habilitadoEnabled Configuração que indica se o webhook está habilitado por padrão quando é criado.Setting indicating if the webhook is enabled by default when it's created. Se você definir essa propriedade como desabilitada, nenhum cliente poderá usar o webhook.If you set this property to Disabled, no client can use the webhook. É possível definir essa propriedade ao criar o webhook ou em qualquer outro momento após sua criação.You can set this property when you create the webhook or any other time after its creation.

Parâmetros usados quando o webhook inicia um runbookParameters used when the webhook starts a runbook

Um webhook pode definir valores para parâmetros de runbook que são usados quando o runbook é iniciado.A webhook can define values for runbook parameters that are used when the runbook starts. O webhook deve incluir valores de parâmetros obrigatórios do runbook e pode incluir valores de parâmetros opcionais.The webhook must include values for any mandatory runbook parameters and can include values for optional parameters. Um valor de parâmetro configurado para um webhook pode ser modificado até mesmo depois da criação do webhook.A parameter value configured to a webhook can be modified even after webhook creation. Vários webhooks vinculados a um único runbook podem usar valores de parâmetros diferentes de runbook.Multiple webhooks linked to a single runbook can each use different runbook parameter values. Quando um cliente inicia um runbook usando um webhook, ele não pode substituir os valores de parâmetro definidos no webhook.When a client starts a runbook using a webhook, it can't override the parameter values defined in the webhook.

Para receber dados do cliente, o runbook pode aceitar um único parâmetro chamado WebhookData.To receive data from the client, the runbook supports a single parameter called WebhookData. Esse parâmetro define um objeto que contém dados que o cliente inclui em uma solicitação POST.This parameter defines an object containing data that the client includes in a POST request.

Propriedades de WebhookData

O parâmetro WebhookData tem as seguintes propriedades:The WebhookData parameter has the following properties:

PropriedadeProperty DescriçãoDescription
WebhookName Nome do webhook.Name of the webhook.
RequestHeader Tabela de hash contendo os cabeçalhos da solicitação POST de entrada.Hashtable containing the headers of the incoming POST request.
RequestBody Corpo da solicitação POST de entrada.Body of the incoming POST request. Esse corpo mantém qualquer formatação de dados, como cadeia de caracteres, JSON, XML ou dados codificados de formulário.This body retains any data formatting, such as string, JSON, XML, or form-encoded. 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.The runbook must be written to work with the data format that is expected.

Nenhuma configuração do webhook é necessária para compatibilidade com o parâmetro WebhookData, e o runbook não precisa aceitá-lo.There's no configuration of the webhook required to support the WebhookData parameter, and the runbook isn't required to accept it. Se o runbook não definir o parâmetro, os detalhes da solicitação enviada pelo cliente serão ignorados.If the runbook doesn't define the parameter, any details of the request sent from the client are ignored.

Observação

Ao chamar um webhook, o cliente sempre deve armazenar qualquer valor de parâmetro em caso de falha da chamada.When calling a webhook, the client should always store any parameter values in case the call fails. Se houver uma interrupção de rede ou um problema de conexão, o aplicativo não poderá recuperar chamadas de webhook com falha.If there is a network outage or connection issue, the application can't retrieve failed webhook calls.

Se você especificar um valor para WebhookData na criação do webhook, ele será substituído quando o webhook iniciar o runbook com os dados da solicitação POST do cliente.If you specify a value for WebhookData at webhook creation, it is overridden when the webhook starts the runbook with the data from the client POST request. Isso acontece mesmo que o aplicativo não inclua dados no corpo da solicitação.This happens even if the application does not include any data in the request body.

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.If you start a runbook that defines WebhookData using a mechanism other than a webhook, you can provide a value for WebhookData that the runbook recognizes. 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.This value should be an object with the same properties as the WebhookData parameter so that the runbook can work with it just as it works with actual WebhookData objects passed by a webhook.

Por exemplo, se você estiver iniciando o runbook a seguir no portal do Azure e desejar transmitir alguns dados de webhook de exemplo para teste, deverá transmitir os dados em JSON na interface do usuário.For example, if you are starting the following runbook from the Azure portal and want to pass some sample webhook data for testing, you must pass the data in JSON in the user interface.

Parâmetro WebhookData da interface do usuário

Para o próximo exemplo de runbook, vamos definir as seguintes propriedades para WebhookData:For the next runbook example, let's define the following properties for WebhookData:

  • WebhookName: MyWebhookWebhookName: MyWebhook
  • RequestBody: *[{'ResourceGroup': 'myResourceGroup','Name': 'vm01'},{'ResourceGroup': 'myResourceGroup','Name': 'vm02'}]*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.Now we pass the following JSON object in the UI for the WebhookData parameter. Este exemplo, com retornos de carro e caracteres de nova linha, corresponde ao formato que é transmitido de um webhook.This example, with carriage returns and newline characters, matches the format that is passed in from a 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.Azure Automation logs the values of all input parameters with the runbook job. 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.Thus any input provided by the client in the webhook request is logged and available to anyone with access to the automation job. Por esse motivo, você deve ter cuidado ao incluir informações confidenciais em chamadas webhook.For this reason, you should be cautious about including sensitive information in webhook calls.

Segurança de webhookWebhook security

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.The security of a webhook relies on the privacy of its URL, which contains a security token that allows the webhook to be invoked. A Automação do Azure não executa nenhuma autenticação em uma solicitação desde que ela seja feita para a URL correta.Azure Automation does not perform any authentication on a request as long as it is made to the correct URL. 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.For this reason, your clients should not use webhooks for runbooks that perform highly sensitive operations without using an alternate means of validating the request.

Considere as seguintes estratégias:Consider the following strategies:

  • Será possível incluir lógica em um runbook para determinar se ele é chamado por um webhook.You can include logic within a runbook to determine if it is called by a webhook. Faça com que o runbook verifique a propriedade WebhookName do parâmetro WebhookData.Have the runbook check the WebhookName property of the WebhookData parameter. O runbook pode executar uma validação adicional procurando informações específicas nas propriedades RequestHeader e RequestBody.The runbook can perform further validation by looking for particular information in the RequestHeader and RequestBody properties.

  • Faça com que o runbook execute algumas validações de uma condição externa quando receber uma solicitação de webhook.Have the runbook perform some validation of an external condition when it receives a webhook request. Por exemplo, considere um runbook que é chamado pelo GitHub sempre que houver uma nova confirmação para um repositório GitHub.For example, consider a runbook that is called by GitHub any time there's a new commit to a GitHub repository. O runbook pode se conectar ao GitHub para validar se uma nova confirmação ocorreu antes de continuar.The runbook might connect to GitHub to validate that a new commit has occurred before continuing.

  • A automação do Azure dá suporte a marcas de serviço de rede virtual do Azure, especificamente GuestAndHybridManagement.Azure Automation supports Azure virtual network service tags, specifically GuestAndHybridManagement. Você pode 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.You can use service tags to define network access controls on network security groups or Azure Firewall and trigger webhooks from within your virtual network. As marcas de serviço podem ser usadas no lugar de endereços IP específicos quando você cria regras de segurança.Service tags can be used in place of specific IP addresses when you create security rules. Ao especificar o nome da marca de serviço GuestAndHybridManagement no campo de origem ou de destino apropriado de uma regra, você pode permitir ou negar o tráfego para o serviço de automação.By specifying the service tag name GuestAndHybridManagement in the appropriate source or destination field of a rule, you can allow or deny the traffic for the Automation service. Essa marca de serviço não dá suporte à permissão de controle mais granular restringindo intervalos de IP para uma região específica.This service tag does not support allowing more granular control by restricting IP ranges to a specific region.

Criar um webhookCreate a webhook

Use o procedimento a seguir para criar um novo webhook vinculado a um runbook no Portal do Azure.Use the following procedure to create a new webhook linked to a runbook in the Azure portal.

  1. Na página Runbooks no portal do Azure, clique no runbook que o webhook inicia para exibir seus detalhes.From the Runbooks page in the Azure portal, click the runbook that the webhook starts to view the runbook details. Verifique se o campo Status do runbook está definido como Publicado.Ensure that the runbook Status field is set to Published.

  2. Clique em Webhook na parte superior da página para abrir a página Adicionar Webhook.Click Webhook at the top of the page to open the Add Webhook page.

  3. Clique em Criar novo webhook para abrir a página Criar Webhook.Click Create new webhook to open the Create Webhook page.

  4. Preencha os campos Nome e Data de Validade para o webhook e especifique se ele deve ser habilitado.Fill in the Name and Expiration Date fields for the webhook and specify if it should be enabled. Veja Propriedades do webhook para obter mais informações sobre essas propriedades.See Webhook properties for more information about these properties.

  5. Clique no ícone copiar e pressione Ctrl + C para copiar a URL do webhook.Click the copy icon and press Ctrl+C to copy the URL of the webhook. Em seguida, anote-o em um local seguro.Then record it in a safe place.

    Observação

    Quando você cria o webhook, não é possível recuperar a URL novamente.Once you create the webhook, you cannot retrieve the URL again.

    URL de Webhook

  6. Clique em Parâmetros para fornecer valores para os parâmetros do runbook.Click Parameters to provide values for the runbook parameters. Se o runbook tiver parâmetros obrigatórios, não será possível criar o webhook, a menos que você forneça valores.If the runbook has mandatory parameters, you can't create the webhook unless you provide values.

  7. Clique em Criar para criar o webhook.Click Create to create the webhook.

Usar um webhookUse a webhook

Para usar um webhook depois que ele tiver sido criado, o cliente deverá emitir uma solicitação HTTP POST com a URL para o webhook.To use a webhook after it has been created, your client must issue an HTTP POST request with the URL for the webhook. A sintaxe do é:The syntax is:

http://<Webhook Server>/token?=<Token Value>

O cliente recebe um dos seguintes códigos de retorno da solicitação POST.The client receives one of the following return codes from the POST request.

CódigoCode TextoText DescriçãoDescription
202202 AceitaAccepted A solicitação foi aceita e o runbook foi enfileirado com êxito.The request was accepted, and the runbook was successfully queued.
400400 Solicitação incorretaBad Request A solicitação não foi aceita por um dos motivos a seguir:The request was not accepted for one of the following reasons:
  • O webhook expirou.The webhook has expired.
  • O webhook está desabilitado.The webhook is disabled.
  • O token na URL é inválido.The token in the URL is invalid.
404404 Não encontradoNot Found A solicitação não foi aceita por um dos motivos a seguir:The request was not accepted for one of the following reasons:
  • O webhook não foi encontrado.The webhook was not found.
  • O runbook não foi encontrado.The runbook was not found.
  • A conta não foi encontrada.The account was not found.
500500 Erro interno do servidorInternal Server Error A URL era válida, mas ocorreu um erro.The URL was valid, but an error occurred. Envie a solicitação novamente.Please resubmit the request.

Supondo que a solicitação seja bem-sucedida, a resposta do webhook conterá a ID de trabalho no formato JSON conforme mostrado abaixo.Assuming the request is successful, the webhook response contains the job ID in JSON format as shown below. Ela contém uma ID de trabalho única, mas o formato JSON permite possíveis aprimoramentos futuros.It contains a single job ID, but the JSON format allows for potential future enhancements.

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

O cliente não pode determinar o status da conclusão do webhook ou quando o trabalho de runbook é concluído.The client can't determine when the runbook job completes or its completion status from the webhook. Ele pode descobrir essas informações usando a ID de trabalho com outro mecanismo, como Windows PowerShell ou a API de Automação do Azure.It can find out this information using the job ID with another mechanism, such as Windows PowerShell or the Azure Automation API.

Renovar um webhookRenew a webhook

Quando um webhook é criado, ele tem um período de validade de dez anos, após o qual ele expira automaticamente.When a webhook is created, it has a validity time period of ten years, after which it automatically expires. Depois que um webhook vencer, você não poderá reativá-lo.Once a webhook has expired, you can't reactivate it. Só é possível removê-lo e, depois, recriá-lo.You can only remove and then recreate it.

Você pode estender um webhook que não atingiu seu prazo de validade.You can extend a webhook that has not reached its expiration time. Para estender um webhook:To extend a webhook:

  1. Navegue até o runbook que contém o webhook.Navigate to the runbook that contains the webhook.
  2. Selecione Webhooks em Recursos.Select Webhooks under Resources.
  3. Clique no webhook que você deseja estender.Click the webhook that you want to extend.
  4. Na página Webhook, escolha uma nova data e hora de validade e clique em Salvar.In the Webhook page, choose a new expiration date and time and click Save.

Runbook de exemploSample runbook

O runbook de exemplo a seguir aceita os dados do webhook e inicia as máquinas virtuais especificadas no corpo da solicitação.The following sample runbook accepts the webhook data and starts the virtual machines specified in the request body. Para testar esse runbook em sua conta de Automação, em Runbooks, clique em Criar um Runbook.To test this runbook, in your Automation account under Runbooks, click Create a runbook. Se você não souber como criar um runbook, confira Criando um runbook.If you don't know how to create a runbook, see Creating a runbook.

Observação

Para runbooks não gráficos do PowerShell, Add-AzAccount e Add-AzureRMAccount são aliases para Connect-AzAccount.For non-graphical PowerShell runbooks, Add-AzAccount and Add-AzureRMAccount are aliases for Connect-AzAccount. Você pode usar esses cmdlets ou pode atualizar seus módulos em sua conta de Automação para as versões mais recentes.You can use these cmdlets or you can update your modules in your Automation account to the latest versions. Talvez você precise atualizar os módulos mesmo que você tenha acabado de criar uma conta de Automação.You might need to update your modules even if you have just created a new Automation account.

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

# If runbook was called from Webhook, WebhookData will not be null.
if ($WebhookData) {

    # Check header for message to validate request
    if ($WebhookData.RequestHeader.message -eq 'StartedbyContoso')
    {
        Write-Output "Header has required information"}
    else
    {
        Write-Output "Header missing required information";
        exit;
    }

    # Retrieve VMs from Webhook request body
    $vms = (ConvertFrom-Json -InputObject $WebhookData.RequestBody)

    # Authenticate to Azure by using the service principal and certificate. Then, set the subscription.

    Write-Output "Authenticating to Azure with service principal and certificate"
    $ConnectionAssetName = "AzureRunAsConnection"
    Write-Output "Get connection asset: $ConnectionAssetName"

    $Conn = Get-AutomationConnection -Name $ConnectionAssetName
            if ($Conn -eq $null)
            {
                throw "Could not retrieve connection asset: $ConnectionAssetName. Check that this asset exists in the Automation account."
            }
            Write-Output "Authenticating to Azure with service principal."
            Add-AzAccount -ServicePrincipal -Tenant $Conn.TenantID -ApplicationId $Conn.ApplicationID -CertificateThumbprint $Conn.CertificateThumbprint | Write-Output

        # Start each virtual machine
        foreach ($vm in $vms)
        {
            $vmName = $vm.Name
            Write-Output "Starting $vmName"
            Start-AzVM -Name $vm.Name -ResourceGroup $vm.ResourceGroup
        }
}
else {
    # Error
    write-Error "This runbook is meant to be started from an Azure alert webhook only."
}

O exemplo de testeTest the sample

O exemplo a seguir usa o Windows PowerShell para iniciar um runbook com um webhook.The following example uses Windows PowerShell to start a runbook with a webhook. Qualquer linguagem que possa fazer uma solicitação HTTP pode usar um webhook.Any language that can make an HTTP request can use a webhook. O Windows PowerShell é usado aqui como exemplo.Windows PowerShell is used here as an example.

O runbook está esperando uma lista de máquinas virtuais formatadas em JSON no corpo da solicitação.The runbook is expecting a list of virtual machines formatted in JSON in the body of the request. O runbook também valida que os cabeçalhos contêm uma mensagem definida para confirmar que o chamador de webhook é válido.The runbook validates as well that the headers contain a defined message to validate that the webhook caller is valid.

$uri = "<webHook Uri>"

$vms  = @(
            @{ Name="vm01";ResourceGroup="vm01"},
            @{ Name="vm02";ResourceGroup="vm02"}
        )
$body = ConvertTo-Json -InputObject $vms
$header = @{ message="StartedbyContoso"}
$response = Invoke-WebRequest -Method Post -Uri $uri -Body $body -Headers $header
$jobid = (ConvertFrom-Json ($response.Content)).jobids[0]

O exemplo a seguir mostra o corpo da solicitação que está disponível para o runbook na propriedade RequestBody de WebhookData.The following example shows the body of the request that is available to the runbook in the RequestBody property of WebhookData. Esse valor é formatado em JSON para ser compatível com o formato incluído no corpo da solicitação.This value is formatted in JSON to be compatible with the format included in the body of the request.

[
    {
        "Name":  "vm01",
        "ResourceGroup":  "myResourceGroup"
    },
    {
        "Name":  "vm02",
        "ResourceGroup":  "myResourceGroup"
    }
]

A imagem a seguir mostra a solicitação sendo enviada do Windows PowerShell e a resposta resultante.The following image shows the request being sent from Windows PowerShell and the resulting response. A ID do trabalho é extraída da resposta e convertida em uma cadeia de caracteres.The job ID is extracted from the response and converted to a string.

Botão Webhooks

Próximas etapasNext steps