Запуск runbook через веб-перехватчик

Веб-перехватчик позволяет внешней службе запускать определенный модуль Runbook в Cлужба автоматизации Azure через один HTTP-запрос. Внешние службы включают службы Azure DevOps, GitHub, журналы Azure Monitor и пользовательские приложения. Такая служба может использовать веб-перехватчик для запуска модуля Runbook без реализации полного Cлужба автоматизации Azure API. Вы можете сравнить веб-перехватчики с другими методами запуска модуля Runbook в Starting a Runbook в Cлужба автоматизации Azure.

Сведения о требованиях клиента для TLS 1.2 или более поздней версии с веб-перехватчиками см. в разделе TLS для Cлужба автоматизации Azure.

Свойства вебхука

В следующей таблице описаны свойства, которые необходимо настроить для объекта Webhook.

Параметры, используемые при запуске сценария веб-хуком

Веб-перехватчик может определять значения для параметров runbook, которые используются при запуске runbook. Веб-перехватчик должен содержать значения всех обязательных параметров ранбука и может содержать значения для необязательных параметров. Значение параметра, настроенного для веб-перехватчика, можно изменить даже после создания веб-перехватчика. Несколько веб-перехватчиков, привязанных к одному runbook, могут использовать разные значения параметров. Когда клиент запускает модуль Runbook с помощью веб-перехватчика, клиент не может переопределить значения параметров, определяемые веб-перехватчиком.

Чтобы получать данные от клиента, runbook поддерживает один параметр с именем WebhookData. Этот параметр определяет объект с данными, которые клиент добавляет в запрос POST.

Параметр WebhookData содержит следующие свойства:

Веб-перехватчик не требует настройки для поддержки параметра WebhookData, и runbook не обязан его принимать. Если runbook не определяет параметр, любые сведения в запросе клиента игнорируются.

Если вы укажете значение WebhookData при создании веб-перехватчика, оно будет переопределено данными из POST-запроса от клиента, когда веб-перехватчик запускает план выполнения. Это происходит даже в том случае, если приложение не передает данные в тексте запроса.

При запуске runbook, который определяет WebhookData, любым способом, кроме веб-перехватчика, вы можете указать распознаваемое runbook значение для WebhookData. Это значение должно быть объектом с такими же свойствами, как у параметра WebhookData, чтобы runbook мог работать с ним так же, как с фактическими объектами WebhookData, переданными веб-перехватчиком.

Например, если вы запускаете следующий планировщик задач на портале Azure и хотите передать примеры данных веб-перехватчика для тестирования, необходимо указать данные в формате JSON в пользовательском интерфейсе.

Для следующего примера runbook давайте определим следующие свойства для WebhookData.

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

Эти данные мы передаем в виде следующего объекта JSON через параметр WebhookData в пользовательском интерфейсе. Этот пример с символами возврата каретки и новой строки соответствует формату, который передается из вебхука.

{"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]"}

Безопасность вебхука

Безопасность веб-перехватчика зависит от защищенности URL-адреса, который содержит маркер безопасности, позволяющий вызывать этот веб-перехватчик. Cлужба автоматизации Azure не выполняет проверку подлинности запроса, если он сделан по правильному URL-адресу. По этой причине клиентам не следует использовать вебхуки для runbooks, которые выполняют критически важные операции, без использования альтернативного способа проверки запроса.

Рассмотрите следующие стратегии:

• Вы можете включить в последовательность runbook дополнительную логику для проверки, вызывается ли она веб-перехватчиком. Убедитесь, что runbook проверяет свойство WebhookName из параметра WebhookData. Для дополнительной проверки runbook может искать наличие определенной информации в свойствах RequestHeader или RequestBody.

• При получении запроса от веб-перехватчика runbook должен выполнять проверку внешнего условия. Например, рассмотрим инструкции Runbook, которые вызываются GitHub всякий раз, когда в репозитории GitHub есть новый коммит. Модуль Runbook может подключиться к GitHub, чтобы проверить, произошла ли новая фиксация, прежде чем продолжить.

• Cлужба автоматизации Azure поддерживает теги службы виртуальной сети Azure, в частности GuestAndHybridManagement. Теги служб можно использовать для определения элементов управления доступом к сети в группах безопасности network или Брандмауэр Azure и активации веб-перехватчиков из виртуальной сети. Теги служб можно использовать вместо определенных IP-адресов при создании правил безопасности. Указав имя тега службы GuestAndHybridManagement в соответствующем поле источника или поле назначения правила, можно разрешить или запретить трафик для Службы автоматизации. Этот тег службы не поддерживает предоставление более детализированного контроля путем ограничения диапазонов IP-адресов до конкретного региона.

Создание вебхука

Чтобы создать вебхук, выполните следующие действия.

1. Создайте рабочую книгу PowerShell со следующим кодом:

   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. Создайте вебхук с помощью портала Azure, PowerShell или REST API. Для веб-перехватчика требуется опубликованный рундбук. В этом пошаговом руководстве используется измененная версия модуля Runbook, созданная из Create Cлужба автоматизации Azure runbook.

   • портал Azure
   • PowerShell
   • REST API

   Чтобы создать вебхук с помощью портала Azure, сделайте следующее:

   1. Войдите на портал Azure.

   2. На портале Azure перейдите к учетной записи службы автоматизации.

   3. В разделе Автоматизация процессов выберите Рунбуки, чтобы открыть страницу Рунбуки.

   4. Выберите модуль Runbook из списка, чтобы открыть страницу Обзор.

   5. Выберите Добавить веб-перехватчик, чтобы открыть страницу Добавление веб-перехватчика.

      

   6. На странице Добавление веб-перехватчика выберите Создать новый веб-перехватчик.

      

   7. Введите значение в поле Имя для веб-перехватчика. Дата истечения срока действия для поля Истекает по умолчанию равна одному году с текущей даты.

   8. Выберите значок копирования или нажмите клавиши CTRL+C, чтобы скопировать URL-адрес вебхука. Затем сохраните URL-адрес в безопасном расположении.

      

      Внимание

      Как только веб-перехватчик будет создан, получить URL-адрес повторно будет невозможно. Обязательно скопируйте и запишите его, как указано выше.

   9. Нажмите ОК, чтобы вернуться на страницу Добавление вебхука.

   10. На странице Добавление веб-перехватчика выберите Настроить параметры и параметры запуска, чтобы открыть страницу Параметры.

       

   11. Просмотрите страницу Параметры. Для примера модуля Runbook, используемого в этой статье, изменения не требуются. Нажмите ОК, чтобы вернуться на страницу Добавление вебхука.

   12. На странице Добавление веб-перехватчика выберите Создать. Будет создан веб-перехватчик, и вы вернетесь на страницу Обзор Runbook.

Используйте веб-перехватчик

В этом примере командлет PowerShell Invoke-WebRequest используется для отправки запроса POST в ваш новый вебхук.

Чтобы использовать вебхук, выполните следующие действия.

1. Подготовьте значения для передачи в модуль Runbook в качестве текста для вызова веб-перехватчика. Для относительно простых значений вы можете задать их следующим образом:

   $Names  = @(
               @{ Name="Hawaii"},
               @{ Name="Seattle"},
               @{ Name="Florida"}
           )
   
   $body = ConvertTo-Json -InputObject $Names
   

2. Для более крупных наборов вы можете захотеть использовать файл. Создайте файл с именем names.json и вставьте в него следующий код.

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

   Перед выполнением следующих команд PowerShell измените значение переменной $file на фактический путь к JSON-файлу.

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

3. Выполните следующие команды PowerShell, чтобы вызвать веб-перехватчик с помощью REST API.

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

   Для демонстрационных целей были выполнены два вызова для двух различных методов создания текстовой области. Для производственной среды используйте только один метод. Результат должен выглядеть следующим образом (показаны только одни выходные данные):

   

   В ответ на запрос POST клиент получит один из следующих кодов возврата.

   Код	Текст	Описание
   202	Принято	Запрос был принят, и модуль Runbook успешно поставлен в очередь.
   400	ошибка запроса	Запрос не был принят по одной из следующих причин: Срок действия вебхука истек. Вебхук отключен. Недопустимый токен в URL-адресе.
   404	Не найдено	Запрос не был принят по одной из следующих причин: Веб-перехватчик не найден. Модуль Runbook не найден. Учетная запись не найдена.
   500	Внутренняя ошибка сервера	URL-адрес допустимый, но произошла ошибка. Отправьте запрос повторно.

   Если запрос выполняется успешно, то ответ веб-перехватчика будет содержать идентификатор задания в формате JSON, как показано далее. Это будет только один идентификатор задания, но формат JSON позволяет в будущем расширить эти возможности.

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

4. Для получения выходных данных используется командлет PowerShell Get-AzAutomationJobOutput. Можно также использовать API Cлужба автоматизации Azure.

   #isolate job ID
   $jobid = (ConvertFrom-Json ($response.Content)).jobids[0]
   
   # Get output
   Get-AzAutomationJobOutput `
       -AutomationAccountName $automationAccount `
       -Id $jobid `
       -ResourceGroupName $resourceGroup `
       -Stream Output
   

   При запуске модуля Runbook, созданного на предыдущем шаге, он создаст задание, и выходные данные должны выглядеть следующим образом:

   

Обновление вебхука

При создании веб-перехватчика устанавливается срок действия 10 лет, по истечении которого он автоматически прекращает действие. Веб-перехватчик, у которого истек срок действия, невозможно активировать повторно. Можно лишь удалить его и создать заново. Вы можете продлить срок действия веб-перехватчика, пока этот срок еще не истек. Чтобы расширить вебхук, выполните следующие действия.

1. Перейдите к runbook, который содержит вебхук.
2. В разделе Ресурсы выберите Веб-перехватчики, а затем выберите веб-перехватчик, который требуется расширить.
3. На странице Веб-перехватчик введите новую дату окончания срока действия и щелкните Сохранить.

Рассмотрите вызов API Webhook - Update и командлет PowerShell Set-AzAutomationWebhook для других возможных изменений.

Очистка ресурсов

Ниже приведены примеры удаления вебхука из рабочей тетради службы автоматизации.

• Если используется PowerShell, командлет Remove-AzAutomationWebhook можно использовать, как показано ниже. Выходные данные не возвращаются.

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

• При использовании REST можно использовать REST API Веб-перехватчик — удалить, как показано ниже.

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

  Выходные данные StatusCode : 200 свидетельствуют об успешном удалении.

Создайте Runbook и вебхук с помощью шаблона ARM

Веб-перехватчики автоматизации также можно создавать с помощью шаблонов Azure Resource Manager. Этот пример шаблона создает учетную запись службы автоматизации, четыре модуля Runbook и веб-перехватчик для именованного модуля Runbook.

Чтобы создать веб-перехватчик с помощью шаблона ARM, выполните следующие действия.

1. Создайте файл с именем webhook_deploy.json и вставьте в него следующий код.

   {
       "$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. Следующий пример кода PowerShell выполняет развертывание шаблона с вашего компьютера. Укажите соответствующие значения для переменных, а затем выполните скрипт.

   $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
   

   Примечание.

   По соображениям безопасности URI возвращается только при первом развертывании шаблона.

Следующие шаги

• Чтобы активировать модуль Runbook из оповещения, см. статью Использовать оповещение для активации модуля Runbook Cлужба автоматизации Azure.
• Сведения об устранении неполадок, связанных с запуском рабочих книг Cлужба автоматизации Azure с помощью веб-хуков, см. в статье Troubleshoot runbook issues.