Spuštění runbooku z webhooku

  • Článek

Webhook umožňuje externí službě spustit konkrétní runbook v Azure Automation prostřednictvím jediného požadavku HTTP. Mezi externí služby patří Azure DevOps Services, GitHub, protokoly služby Azure Monitor a vlastní aplikace. Taková služba může pomocí webhooku spustit runbook bez implementace úplného rozhraní API služby Azure Automation. Webhooky můžete porovnat s jinými metodami spuštění runbooku ve spuštění runbooku ve službě Azure Automation.

WebhooksOverview

Pokud chcete porozumět požadavkům klientů na protokol TLS 1.2 nebo vyšší s webhooky, přečtěte si téma TLS pro Azure Automation.

Vlastnosti webhooku

Následující tabulka popisuje vlastnosti, které musíte pro webhook nakonfigurovat.

Vlastnost Popis
Název Název webhooku. Můžete zadat libovolný název, protože není vystavený klientovi. Používá se jenom k identifikaci runbooku v Azure Automation. Osvědčeným postupem je dát webhooku název související s klientem, který ho používá.
URL Adresa URL webhooku. Jedná se o jedinečnou adresu, kterou klient volá pomocí protokolu HTTP POST, aby spustil runbook propojený s webhookem. Automaticky se vygeneruje při vytváření webhooku. Nemůžete zadat vlastní adresu URL.

Adresa URL obsahuje token zabezpečení, který umožňuje systému třetí strany vyvolat runbook bez dalšího ověřování. Z tohoto důvodu byste s adresou URL měli zacházet jako s heslem. Z bezpečnostních důvodů můžete adresu URL zobrazit jenom na webu Azure Portal při vytváření webhooku. Poznamenejte si adresu URL v zabezpečeném umístění pro budoucí použití.
Datum vypršení platnosti Datum vypršení platnosti webhooku, po jehož uplynutí už se nedá použít. Po vytvoření webhooku můžete datum vypršení platnosti upravit, pokud nevypršela platnost webhooku.
Povoleno Nastavení označující, jestli je webhook ve výchozím nastavení povolený při jeho vytvoření. Pokud tuto vlastnost nastavíte na Zakázáno, nebude moct webhook používat žádný klient. Tuto vlastnost můžete nastavit při vytváření webhooku nebo kdykoli po jeho vytvoření.

Parametry používané při spuštění runbooku webhookem

Webhook může definovat hodnoty pro parametry runbooku, které se použijí při spuštění runbooku. Webhook musí obsahovat hodnoty pro všechny povinné parametry runbooku a může obsahovat hodnoty volitelných parametrů. Hodnotu parametru nakonfigurovanou pro webhook lze upravit i po vytvoření webhooku. Několik webhooků propojených s jedním runbookem může používat různé hodnoty parametrů sady Runbook. Když klient spustí runbook pomocí webhooku, nemůže přepsat hodnoty parametrů definované v webhooku.

Pro příjem dat z klienta runbook podporuje jeden parametr volaný WebhookData. Tento parametr definuje objekt obsahující data, která klient zahrne do požadavku POST.

Vlastnosti WebhookData

Parametr WebhookData má následující vlastnosti:

Vlastnost Popis
Název webhooku Název webhooku.
RequestHeader PSCustomObject obsahující hlavičky příchozího požadavku POST.
RequestBody Text příchozího požadavku POST. Tento text uchovává veškeré formátování dat, jako je řetězec, JSON, XML nebo formát. Runbook musí být zapsán, aby fungoval s očekávaným formátem dat.

Pro podporu WebhookData parametru není nutná žádná konfigurace webhooku a runbook se nevyžaduje k jeho přijetí. Pokud runbook nedefinuje parametr, budou ignorovány žádné podrobnosti požadavku odeslaného z klienta.

Poznámka:

Při volání webhooku by klient měl vždy ukládat všechny hodnoty parametrů v případě, že volání selže. Pokud dojde k výpadku sítě nebo problému s připojením, aplikace nemůže načíst neúspěšná volání webhooku.

Pokud zadáte hodnotu pro WebhookData vytvoření webhooku, přepíše se při spuštění webhooku runbook s daty z požadavku POST klienta. K tomu dochází i v případě, že aplikace neobsahuje žádná data v textu požadavku.

Pokud spustíte runbook, který definuje WebhookData použití jiného mechanismu než webhooku, můžete zadat hodnotu WebhookData , kterou runbook rozpozná. Tato hodnota by měla být objekt se stejnými vlastnostmi jako WebhookData parametr, aby s ním runbook mohl pracovat stejně jako se skutečnými WebhookData objekty předanými webhookem.

Pokud například spouštíte následující runbook z webu Azure Portal a chcete pro účely testování předat ukázková data webhooku, musíte data předat ve formátu JSON v uživatelském rozhraní.

Parametr WebhookData z uživatelského rozhraní

V dalším příkladu runbooku nadefinujme následující vlastnosti pro WebhookData:

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

Teď pro parametr předáme následující objekt JSON v uživatelském WebhookData rozhraní. Tento příklad s návratem na začátek řádku a znaky nového řádku odpovídá formátu předávaného z webhooku.

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

Spuštění parametru WebhookData z uživatelského rozhraní

Poznámka:

Azure Automation protokoluje hodnoty všech vstupních parametrů pomocí úlohy runbooku. Každý vstup poskytnutý klientem v požadavku webhooku je tedy protokolován a dostupný komukoli, kdo má přístup k úloze automatizace. Z tohoto důvodu byste měli být opatrní ohledně zahrnutí citlivých informací do volání webhooku.

Zabezpečení webhooku

Zabezpečení webhooku závisí na ochraně osobních údajů jeho adresy URL, která obsahuje token zabezpečení umožňující vyvolání webhooku. Azure Automation neprovádí u požadavku žádné ověřování, pokud se provede na správnou adresu URL. Z tohoto důvodu by vaši klienti neměli používat webhooky pro runbooky, které provádějí vysoce citlivé operace, aniž by se použil alternativní způsob ověření požadavku.

Zvažte následující strategie:

  • Do runbooku můžete zahrnout logiku, která určuje, jestli je volána webhookem. Nechte runbook zkontrolovat WebhookName vlastnost parametru WebhookData . Runbook může provést další ověření vyhledáním konkrétních informací v objektech RequestHeader a RequestBody vlastnostech.

  • Požádejte runbook, aby provedl ověření externí podmínky, když obdrží požadavek webhooku. Představte si například runbook, který je volána GitHubem, kdykoli existuje nové potvrzení do úložiště GitHub. Runbook se může připojit k GitHubu, aby ověřil, že došlo k novému potvrzení, než budete pokračovat.

  • Azure Automation podporuje značky služeb virtuální sítě Azure, konkrétně GuestAndHybridManagement. Značky služeb můžete použít k definování řízení přístupu k síti ve skupinách zabezpečení sítě nebo službě Azure Firewall a aktivaci webhooků z vaší virtuální sítě. Značky služeb se dají používat místo konkrétních IP adres při vytváření pravidel zabezpečení. Zadáním názvu značky služby GuestAndHybridManagement v příslušném zdrojovém nebo cílovém poli pravidla můžete povolit nebo odepřít provoz pro službu Automation. Tato značka služby nepodporuje možnost podrobnějšího řízení omezením rozsahů IP na konkrétní oblast.

Vytvoření webhooku

Poznámka:

Když použijete webhook s runbookem PowerShellu 7, automaticky převede vstupní parametr webhooku na neplatný json. Další informace najdete v tématu Známé problémy – PowerShell 7.1 (Preview). Doporučujeme použít webhook s runbookem PowerShellu 5.

  1. Vytvořte runbook PowerShellu s následujícím kódem:

    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. Vytvořte webhook pomocí webu Azure Portal, PowerShellu nebo rozhraní REST API. Webhook vyžaduje publikovaný runbook. Tento návod používá upravenou verzi runbooku vytvořenou z vytvoření runbooku Azure Automation.

    1. Přihlaste se k portálu Azure.

    2. Na webu Azure Portal přejděte ke svému účtu Automation.

    3. V části Automatizace procesů vyberte Runbooky a otevřete stránku Runbooků .

    4. Výběrem runbooku ze seznamu otevřete stránku Přehled runbooku.

    5. Výběrem možnosti Přidat webhook otevřete stránku Přidat webhook .

      Stránka přehledu runbooku se zvýrazněnou možností Přidat webhook

    6. Na stránce Přidat webhook vyberte Vytvořit nový webhook.

      Přidat stránku webhooku se zvýrazněnou možností Vytvořit

    7. Zadejte název webhooku. Datum vypršení platnosti pole Vyprší ve výchozím nastavení na jeden rok od aktuálního data.

    8. Klikněte na ikonu kopírování nebo stiskněte Ctrl+C , zkopírujte adresu URL webhooku. Pak adresu URL uložte do zabezpečeného umístění.

      Stránka webhooku Creaye se zvýrazněnou adresou URL

      Důležité

      Po vytvoření webhooku nemůžete adresu URL znovu načíst. Ujistěte se, že ho zkopírujete a zaznamenáte jako výše.

    9. Kliknutím na tlačítko OK se vrátíte na stránku Přidat webhook .

    10. Na stránce Přidat webhook vyberte Konfigurovat parametry a spusťte nastavení a otevřete stránku Parametry.

      Přidání stránky webhooku se zvýrazněnými parametry

    11. Zkontrolujte stránku Parametry. V příkladu runbooku použitého v tomto článku nejsou potřeba žádné změny. Kliknutím na tlačítko OK se vrátíte na stránku Přidat webhook .

    12. Na stránce Přidat webhook vyberte Vytvořit. Webhook se vytvoří a vrátíte se na stránku Přehled runbooku.

Použití webhooku

Tento příklad používá rutinu PowerShellu Invoke-WebRequest k odeslání požadavku POST do nového webhooku.

  1. Připravte hodnoty, které se předají runbooku jako tělo volání webhooku. U relativně jednoduchých hodnot můžete hodnoty skriptovat následujícím způsobem:

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

$body = ConvertTo-Json -InputObject $Names

  2. U větších sad můžete chtít použít soubor. Vytvořte soubor s názvem names.json a vložte následující kód:

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

    Před spuštěním následujících příkazů PowerShellu změňte hodnotu proměnné $file skutečnou cestou k souboru JSON.

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

  3. Spuštěním následujících příkazů PowerShellu volejte webhook pomocí rozhraní REST API.

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

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

    Pro ilustrativní účely byly provedeny dvě volání pro dvě různé metody výroby těla. V produkčním prostředí použijte pouze jednu metodu. Výstup by měl vypadat nějak takto (zobrazí se jenom jeden výstup):

    Výstup z volání webhooku

    Klient obdrží z požadavku jeden z následujících návratových kódů POST .

    Kód Text Popis
    202 Přijato Požadavek byl přijat a runbook byl úspěšně zařazen do fronty.
    400 Nesprávná žádost Žádost nebyla přijata z jednoho z následujících důvodů:
    • Platnost webhooku vypršela.
    • Webhook je zakázaný.
    • Token v adrese URL je neplatný.
    404 Nenalezeno Žádost nebyla přijata z jednoho z následujících důvodů:
    • Webhook nebyl nalezen.
    • Runbook nebyl nalezen.
    • Účet nebyl nalezen.
    500 Vnitřní chyba serveru Adresa URL byla platná, ale došlo k chybě. Znovu odešlete požadavek.

    Za předpokladu, že požadavek proběhne úspěšně, obsahuje odpověď webhooku ID úlohy ve formátu JSON, jak je znázorněno níže. Obsahuje jedno ID úlohy, ale formát JSON umožňuje potenciální budoucí vylepšení.

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

  4. K získání výstupu se použije rutina PowerShellu Get-AzAutomationJobOutput . Můžete také použít rozhraní API služby Azure Automation.

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

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

    Když aktivujete runbook vytvořený v předchozím kroku, vytvoří se úloha a výstup by měl vypadat nějak takto:

    Výstup z úlohy webhooku

Aktualizace webhooku

Když webhook vytvoříte, má dobu platnosti 10 let, po jejímž uplynutí jeho platnost automaticky vyprší. Jakmile vyprší platnost webhooku, nemůžete ho znovu aktivovat. Můžete ho odebrat a pak ho znovu vytvořit. Platnost webhooku, jehož platnost ještě nevypršela, můžete prodloužit. Pokud chcete webhook rozšířit, proveďte následující kroky.

  1. Přejděte na runbook, který obsahuje webhook.
  2. V části Prostředky vyberte Webhooky a potom webhook, který chcete rozšířit.
  3. Na stránce Webhooku zvolte nové datum a čas vypršení platnosti a pak vyberte Uložit.

Zkontrolujte webhook volání rozhraní API – aktualizace a rutina PowerShellu Set-AzAutomationWebhook , kde najdete další možné úpravy.

Vyčištění prostředků

Tady jsou příklady odebrání webhooku z runbooku Automation.

  • Pomocí PowerShellu je možné použít rutinu Remove-AzAutomationWebhook , jak je znázorněno níže. Nevrátí se žádný výstup.

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

  • Pomocí rest webhooku REST – Rozhraní API pro odstranění je možné použít, jak je znázorněno níže.

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

    Výstup StatusCode : 200 znamená úspěšné odstranění.

Vytvoření runbooku a webhooku pomocí šablony ARM

Webhooky Automation je možné vytvořit také pomocí šablon Azure Resource Manageru . Tato ukázková šablona vytvoří účet Automation, čtyři runbooky a webhook pro pojmenovaný runbook.

  1. Vytvořte soubor s názvem webhook_deploy.json a vložte následující kód:

    {
    "$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. Následující ukázka kódu PowerShellu nasadí šablonu z vašeho počítače. Zadejte odpovídající hodnotu pro proměnné a pak spusťte skript.

    $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

    Poznámka:

    Z bezpečnostních důvodů se identifikátor URI vrátí pouze při prvním nasazení šablony.

Další kroky