Запуск runbook с помощью веб-перехватчика

  • Статья

Веб-перехватчик позволяет внешним службам запускать определенную последовательность runbook в службе автоматизации Azure с помощью одного HTTP-запроса. Роль внешней службы могут выполнять Azure DevOps Services, GitHub, журналы Azure Monitor и пользовательские приложения. Эта служба будет вызывать веб-перехватчик для запуска runbook, и для этого ей не нужна полная реализация API службы автоматизации Azure. Сравнение веб-перехватчиков с другими методами запуска runbook см. в статье Запуск модуля Runbook в службе автоматизации Azure.

Обзор веб-перехватчиков

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

Свойства веб-перехватчика

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

Свойство Описание
Имя Имя веб-перехватчика. Вы можете указать любое имя, так как оно не предоставляется клиенту. Имя используется для идентификации модуля Runbook в службе автоматизации Azure. Рекомендуется задать веб-перехватчику имя, связанное с клиентом, который будет его использовать.
URL-адрес URL-адрес веб-перехватчика. Это уникальный адрес, на который клиент отправляет HTTP-запрос POST для запуска последовательности runbook, связанной с этим веб-перехватчиком. URL-адрес создается автоматически при создании веб-перехватчика. Нельзя указать другой URL-адрес.

URL-адрес содержит маркер безопасности, который позволяет сторонней системе вызывать runbook без дополнительной проверки подлинности. Это означает, что URL-адрес следует рассматривать как пароль. По соображениям безопасности просмотреть URL-адрес на портале Azure можно только при создании веб-перехватчика. Запишите URL-адрес в надежном месте, чтобы использовать его в дальнейшем.
Срок действия Дата окончания срока действия веб-перехватчика, после которой он не может больше использоваться. Вы можете изменить срок действия после создания веб-перехватчика, если он еще не истек.
Активировано Этот параметр обозначает, будет ли веб-перехватчик автоматически включен после создания. Если задать для этого свойства значение Disabled (Отключено), клиенты не смогут использовать веб-перехватчик. Это свойство можно задать при создании веб-перехватчика или изменить в любое время позднее.

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

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

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

Свойства WebhookData

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

Свойство Description
WebhookName Имя веб-перехватчика.
RequestHeader PSCustomObject, содержащий заголовки входящего запроса POST.
RequestBody Текст входящего запроса POST. В нем сохраняется любое форматирование (строка, JSON, XML, кодировка данных в форме и т. п.). Модуль Runbook должен быть написан для работы с форматом данных, который ожидается.

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

Примечание.

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

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

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

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

Параметр WebhookData из пользовательского интерфейса

Для следующего примера 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]"}

Запуск параметра WebhookData из пользовательского интерфейса

Примечание.

Служба автоматизации Azure сохраняет в журнал значения всех входных параметров вместе с заданием runbook. Таким образом, любые предоставленные клиентом входные данные из запроса веб-перехватчика будут записаны в журнал и станут доступны любому пользователю с доступом к заданию автоматизации. По этой причине необходимо соблюдать осторожность при указании критических данных в вызовах Webhook.

Безопасность веб-перехватчика

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

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

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

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

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

Создание веб-перехватчика

Примечание.

При использовании веб-перехватчика с runbook PowerShell 7 он автоматически преобразует входной параметр веб-перехватчика в недопустимый JSON. Дополнительные сведения см. в статье "Известные проблемы с PowerShell 7.1 (предварительная версия)". Рекомендуется использовать веб-перехватчик с runbook PowerShell 5.

  1. Создайте модуль Runbook 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. В этом пошаговом руководстве используется измененная версия модуля Runbook, созданного на основе раздела Создание модуля Runbook службы автоматизации Azure.

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

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

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

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

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

      Страница обзора Runbook с выделенным элементом

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

      Страница

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

    8. Щелкните значок копирования или нажмите клавиши CTRL+C скопировать URL-адрес веб-перехватчика. Затем сохраните 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 клиент получит один из следующих кодов возврата.

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

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

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

  4. Для получения выходные данных используется командлет PowerShell Get-AzAutomationJobOutput. Можно также использовать API службы автоматизации 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 Веб-перехватчик — обновить и командлет PowerShell Set-AzAutomationWebhook на предмет других возможных изменений.

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

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

  • Если используется 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.

  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 возвращается только при первом развертывании шаблона.

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