Iniciar runbook a partir de um webhook

Um webhook permite que um serviço externo inicie um runbook específico no Automação do Azure por meio de uma única solicitação HTTP. Os serviços externos incluem Azure DevOps Services, GitHub, logs de 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 webhooks em relação a outros métodos de iniciar um runbook em Iniciando um runbook no Automação do Azure.

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

Propriedades de webhook

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

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.

O parâmetro WebhookData tem as seguintes propriedades:

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.

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 quiser passar alguns dados de exemplo do webhook para teste, deverá passar os dados em JSON na interface de 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]"}

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. Automação do Azure não executa nenhuma autenticação em uma solicitação desde que ela seja feita na 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.

Considerar 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 chamado pelo GitHub sempre que houver um novo commit em um repositório GitHub. O runbook pode se conectar ao GitHub para verificar se ocorreu um novo commit antes de continuar.

• Automação do Azure dá suporte a marcas de serviço de rede virtual Azure, especificamente GuestAndHybridManagement. Você pode usar marcas de serviço para definir controles de acesso à rede em grupos de segurança de rede ou 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 são criadas 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

Para criar um webhook, siga estas etapas:

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

   • Azure portal
   • PowerShell
   • REST API

   Para criar um webhook usando o portal Azure, faça o seguinte:

   1. Entre no portal Azure.

   2. No portal do Azure, navegue até 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.

      

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

      

   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. Selecione o ícone de cópia ou pressione Ctrl + C para copiar a URL do webhook. Em seguida, salve a URL em um local seguro.

      

      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.

       

   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.

Para usar um webhook, siga estas etapas:

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):

   

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

   Code	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. A API 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
   

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

   

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 seguintes etapas:

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

Webhooks de automação também podem ser criados usando modelos Azure Resource Manager. O modelo de exemplo cria uma conta de automação, quatro runbooks e um webhook para o runbook nomeado.

Para criar um webhook usando um modelo do ARM, siga estas etapas:

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

• Para disparar um runbook a partir de um alerta, consulte Use um alerta para disparar um runbook do Automação do Azure.
• Para solucionar problemas relacionados ao início de runbooks do Automação do Azure usando webhooks, consulte Solucionar problemas de runbook.