Runbook indítása webhookból

  • Cikk

A webhookok használatával a külső szolgáltatások egyetlen HTTP-kérés kiadásával indíthatnak el adott runbookokat az Azure Automationben. A külső szolgáltatások közé tartoznak az Azure DevOps Services, a GitHub, az Azure Monitor-naplók és az egyéni alkalmazások. Egy ilyen szolgáltatás webhook használatával elindíthat egy runbookot a teljes Azure Automation API implementálása nélkül. Összehasonlíthatja a webhookokat a runbookok elindításának más módszereivel az Azure Automationben futó runbook indításakor.

WebhooksOverview

A TLS 1.2 vagy újabb verziójára vonatkozó ügyfélkövetelmények webhookokkal való megismeréséhez tekintse meg az Azure Automation TLS-ét.

Webhook tulajdonságai

Az alábbi táblázat azokat a tulajdonságokat ismerteti, amelyeket konfigurálni kell a webhookokhoz.

Tulajdonság Leírás
Név A webhook neve. Bármilyen nevet megadhat, mivel az nem érhető el az ügyfél számára. Ez a név csak a webhook Azure Automationben való azonosítására szolgál. Ajánlott eljárásként olyan nevet adjon a webhooknak, amely az azt használó ügyfélhez kapcsolódik.
URL-cím A webhook URL-címe. Ez az az egyedi cím, amelyet az ügyfél HTTP POST kérelemmel hív meg a webhookhoz csatolt runbook elindításához. A webhook létrehozásakor automatikusan létrejön. Egyéni URL-címet nem adhat meg.

Az URL-cím tartalmaz egy biztonsági jogkivonatot, amely lehetővé teszi, hogy a külső rendszerek további hitelesítés nélkül meghívják a runbookot. Ezért az URL-címet jelszóként kell kezelni. Biztonsági okokból az URL-címet csak az Azure Portalon tekintheti meg a webhook létrehozásakor. Jegyezze fel az URL-címet egy biztonságos helyen későbbi használatra.
Lejárati dátum A webhook lejárati dátuma, amely után már nem használható. A webhook létrehozása után módosíthatja a lejárati dátumot, feltéve, hogy a webhook még nem járt le.
Engedélyezve A beállítás azt jelzi, hogy a webhook alapértelmezés szerint engedélyezve van-e a létrehozásakor. Ha letiltott értékre állítja ezt a tulajdonságot, egyetlen ügyfél sem használhatja a webhookot. Ezt a tulajdonságot a webhook létrehozásakor vagy a létrehozása után bármikor beállíthatja.

A webhook runbook indításakor használt paraméterek

A webhookok meghatározhatják a runbook-paraméterek értékeit, amelyeket a runbook indításakor használnak. A webhooknak tartalmaznia kell a kötelező runbook-paraméterek értékeit, és tartalmazhat értékeket az opcionális paraméterekhez. A webhookra konfigurált paraméterértékek a webhook létrehozása után is módosíthatók. Egy runbookhoz csatolt webhookok mindegyike különböző runbook paraméterértékeket használhat. Amikor egy ügyfél webhook használatával indít el runbookot, nem tudja felülbírálni a webhookban definiált paraméterértékeket.

Az ügyféltől érkező adatok fogadásához a runbook egyetlen, úgynevezett paramétert WebhookDatatámogat. Ez a paraméter egy olyan objektumot határoz meg, amely adatokat tartalmaz az ügyfél egy POST-kérelemben.

WebhookData tulajdonságai

A WebhookData paraméter a következő tulajdonságokkal rendelkezik:

Tulajdonság Leírás
WebhookName A webhook neve.
RequestHeader PSCustomObject, amely a bejövő POST-kérelem fejléceit tartalmazza.
RequestBody A bejövő POST-kérelem törzse. Ez a törzs minden adatformázást, például sztringet, JSON-t, XML-t vagy űrlapkódoltat tartalmaz. A runbookot úgy kell megírni, hogy a várt adatformátummal működjön.

A paraméter támogatásához WebhookData nincs szükség a webhook konfigurálására, és a runbook nem szükséges annak elfogadásához. Ha a runbook nem határozza meg a paramétert, a rendszer figyelmen kívül hagyja az ügyféltől küldött kérés részleteit.

Feljegyzés

Webhook hívásakor az ügyfélnek mindig tárolnia kell a paraméterértékeket, ha a hívás meghiúsul. Hálózatkimaradás vagy kapcsolati probléma esetén az alkalmazás nem tudja lekérni a sikertelen webhook-hívásokat.

Ha értéket WebhookData ad meg a webhook létrehozásakor, az felül lesz bírálva, amikor a webhook elindítja a runbookot az ügyfél POST kéréséből származó adatokkal. Ez akkor is előfordul, ha az alkalmazás nem tartalmaz adatokat a kérelem törzsében.

Ha olyan runbookot indít el, amely a webhooktól WebhookData eltérő mechanizmust használ, megadhat egy értéket WebhookData , amelyet a runbook felismer. Ennek az értéknek a paraméterrel azonos tulajdonságokkalWebhookData rendelkező objektumnak kell lennie, hogy a runbook ugyanúgy működjön vele, mint a webhook által átadott tényleges WebhookData objektumokkal.

Ha például a következő runbookot az Azure Portalról indítja, és tesztelés céljából szeretne átadni néhány minta webhook-adatot, az adatokat JSON-ban kell átadnia a felhasználói felületen.

WebhookData paraméter a felhasználói felületről

A következő runbook-példában definiáljuk a következő tulajdonságokat WebhookData:

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

Most a következő JSON-objektumot adjuk át a paraméter felhasználói felületén WebhookData . Ez a példa kocsivisszajelekkel és újvonalas karakterekkel megegyezik a webhookból átadott formátummal.

{"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 paraméter indítása a felhasználói felületről

Feljegyzés

Az Azure Automation naplózza az összes bemeneti paraméter értékét a runbook-feladattal. Így az ügyfél által a webhook-kérelemben megadott bemenetek naplózva lesznek, és bárki számára elérhetők, aki hozzáfér az automatizálási feladathoz. Ezért óvatosnak kell lennie a bizalmas információk webhook-hívásokba való beépítésével kapcsolatban.

Webhook biztonsága

A webhook biztonsága az URL-cím biztonságára támaszkodik, amely egy olyan biztonsági jogkivonatot tartalmaz, amely lehetővé teszi a webhook meghívását. Az Azure Automation nem végez hitelesítést a kéréseken, amíg a megfelelő URL-címre történik. Ezért az ügyfeleknek nem szabad webhookokat használniuk olyan runbookokhoz, amelyek rendkívül érzékeny műveleteket hajtanak végre anélkül, hogy alternatív módon érvényesítenék a kérést.

Figyelmébe ajánljuk a következő stratégiákat:

  • A runbookon belül logikát is befoglalhat annak megállapítására, hogy egy webhook hívja-e meg. Ellenőrizze a runbookban a WebhookName paraméter tulajdonságát WebhookData . A runbook további ellenőrzést végezhet, ha konkrét információkat keres a tulajdonságokban és RequestBody a RequestHeader tulajdonságokban.

  • Kérje meg a runbookot, hogy végezzen ellenőrzést egy külső feltételen, amikor webhook-kérést kap. Vegyük például azt a runbookot, amelyet a GitHub hív meg, amikor új véglegesítés történik egy GitHub-adattárban. A runbook a GitHubhoz kapcsolódva ellenőrizheti, hogy történt-e új véglegesítés a folytatás előtt.

  • Az Azure Automation támogatja az Azure-beli virtuális hálózati szolgáltatáscímkéket, különösen a GuestAndHybridManagement szolgáltatást. Szolgáltatáscímkék használatával meghatározhatja a hálózati hozzáférési vezérlőket a hálózati biztonsági csoportokon vagy az Azure Firewallon, és webhookokat aktiválhat a virtuális hálózaton belülről. Biztonsági szabályok létrehozása során használjon szolgáltatáscímkéket az egyes IP-címek helyett. Ha megadja a GuestAndHybridManagement szolgáltatáscímke nevét egy szabály megfelelő forrás- vagy célmezőjében, engedélyezheti vagy letilthatja az Automation szolgáltatás forgalmát. Ez a szolgáltatáscímke nem támogatja a részletesebb szabályozást az IP-címtartományok egy adott régióra való korlátozásával.

Webhook létrehozása

Feljegyzés

Ha a webhookot PowerShell 7-runbooktal használja, az automatikusan átalakítja a webhook bemeneti paraméterét érvénytelen JSON-ra. További információ: Ismert problémák – PowerShell 7.1 (előzetes verzió). Javasoljuk, hogy használja a webhookot a PowerShell 5 runbooktal.

  1. PowerShell-runbook létrehozása a következő kóddal:

    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. Hozzon létre egy webhookot az Azure Portal, a PowerShell vagy a REST API használatával. A webhookok használatához közzétett runbookra van szükség. Ez az útmutató az Azure Automation-runbook létrehozásakor létrehozott runbook módosított verzióját használja.

    1. Jelentkezzen be az Azure Portalra.

    2. Az Azure Portalon lépjen az Automation-fiókjához.

    3. A Folyamatautomatizálás területen válassza a Runbookok lehetőséget a Runbookok lap megnyitásához.

    4. A runbook áttekintési oldalának megnyitásához válassza ki a runbookot a listából.

    5. A Webhook hozzáadása lap megnyitásához válassza a Webhook hozzáadása lehetőséget.

      Runbook áttekintési lap a Webhook hozzáadása elem kiemelésével.

    6. A Webhook hozzáadása lapon válassza az Új webhook létrehozása lehetőséget.

      Weblap hozzáadása kiemelt létrehozással.

    7. Adja meg a webhook nevét . A Lejárat mező lejárati dátuma alapértelmezés szerint az aktuális dátumtól számított egy évre esik.

    8. Kattintson a másolás ikonra, vagy nyomja le a Ctrl + C billentyűkombinációt a webhook URL-címének másolásához. Ezután mentse az URL-címet egy biztonságos helyre.

      Creaye webhook lap kiemelt URL-címmel.

      Fontos

      A webhook létrehozása után nem lehet újból lekérni az URL-címet. Győződjön meg arról, hogy a fenti módon másolja és rögzítse.

    9. Kattintson az OK gombra a Webhook hozzáadása lapra való visszatéréshez.

    10. A Webhook hozzáadása lapon válassza a Paraméterek konfigurálása és a futtatási beállítások lehetőséget a Paraméterek lap megnyitásához.

      Weblap hozzáadása kiemelt paraméterekkel.

    11. Tekintse át a Paraméterek lapot. A cikkben használt példa runbook esetében nincs szükség módosításra. Kattintson az OK gombra a Webhook hozzáadása lapra való visszatéréshez.

    12. A Webhook hozzáadása lapon válassza a Létrehozás lehetőséget. Létrejön a webhook, és visszakerül a Runbook áttekintési lapjára.

Webhook használata

Ez a példa az Invoke-WebRequest PowerShell-parancsmaggal küldi el a POST-kérést az új webhookra.

  1. Készítse elő az értékeket, hogy átadják a runbooknak a webhook-hívás törzseként. Viszonylag egyszerű értékek esetén a következőképpen szkriptelheti az értékeket:

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

$body = ConvertTo-Json -InputObject $Names

  2. Nagyobb csoportok esetén érdemes lehet egy fájlt használni. Hozzon létre egy elnevezett names.json fájlt, majd illessze be a következő kódot:

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

    Az alábbi PowerShell-parancsok futtatása előtt módosítsa a változó $file értékét a json-fájl tényleges elérési útjával.

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

  3. Futtassa a következő PowerShell-parancsokat a webhook meghívásához a REST API használatával.

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

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

    Szemléltető célokra két hívást indítottak a test előállításának két különböző módszerére. Éles környezetben csak egy módszert használjon. A kimenetnek a következőképpen kell kinéznie (csak egy kimenet jelenik meg):

    Kimenet webhook-hívásból.

    Az ügyfél a következő visszatérési kódok egyikét kapja meg a POST kéréstől.

    Kód Szöveg Leírás
    202 Elfogadva A kérést elfogadták, és a runbook sikeresen várólistára lett állítva.
    400 Hibás kérés A kérést a következő okok egyike miatt nem fogadták el:
    • A webhook lejárt.
    • A webhook le van tiltva.
    • Az URL-cím jogkivonata érvénytelen.
    404 Nem található A kérést a következő okok egyike miatt nem fogadták el:
    • A webhook nem található.
    • A runbook nem található.
    • A fiók nem található.
    500 Belső kiszolgálóhiba Az URL-cím érvényes volt, de hiba történt. Küldje el újra a kérést.

    Ha a kérés sikeres, a webhook-válasz JSON formátumban tartalmazza a feladatazonosítót az alább látható módon. Egyetlen feladatazonosítót tartalmaz, de a JSON formátum lehetővé teszi a jövőbeli fejlesztéseket.

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

  4. A Rendszer a Get-AzAutomationJobOutput PowerShell-parancsmagot használja a kimenet lekéréséhez. Az Azure Automation API is használható.

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

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

    Amikor elindít egy, az előző lépésben létrehozott runbookot, az létrehoz egy feladatot, és a kimenetnek a következőhöz hasonlóan kell kinéznie:

    Kimenet a webhook-feladatból.

Webhook frissítése

Amikor létrejön egy webhook, az érvényességi ideje 10 év lesz, ami után automatikusan lejár. Ha egy webhook lejárt, nem aktiválhatja újra. Csak eltávolíthatja, majd újra létrehozhatja. Meghosszabbíthatja azoknak a webhookoknak a lejárati idejét, amelyek még nem jártak le. A webhook kibővítéséhez hajtsa végre az alábbi lépéseket.

  1. Lépjen a webhookot tartalmazó runbookra.
  2. Az Erőforrások területen válassza a Webhookok lehetőséget, majd a kiterjeszteni kívánt webhookot.
  3. A Webhook lapon válasszon egy új lejárati dátumot és időpontot, majd válassza a Mentés lehetőséget.

Tekintse át a Webhook – Update és PowerShell parancsmag Set-AzAutomationWebhook API-hívását az egyéb lehetséges módosításokért.

Az erőforrások eltávolítása

Íme néhány példa egy webhook Automation-runbookból való eltávolítására.

  • A PowerShell használatával a Remove-AzAutomationWebhook parancsmag az alább látható módon használható. A függvény nem ad vissza kimenetet.

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

  • A REST használatával a REST Webhook – Delete API az alább látható módon használható.

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

    A kimenet StatusCode : 200 sikeres törlést jelent.

Runbook és webhook létrehozása ARM-sablonnal

Az Automation-webhookok Azure Resource Manager-sablonok használatával is létrehozhatók. Ez a mintasablon létrehoz egy Automation-fiókot, négy runbookot és egy webhookot a nevesített runbookhoz.

  1. Hozzon létre egy elnevezett webhook_deploy.json fájlt, majd illessze be a következő kódot:

    {
    "$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. Az alábbi PowerShell-kódminta telepíti a sablont a gépről. Adjon meg egy megfelelő értéket a változókhoz, majd hajtsa végre a szkriptet.

    $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

    Feljegyzés

    Biztonsági okokból a rendszer csak a sablon első üzembe helyezésekor adja vissza az URI-t.

Következő lépések

  • Ha egy runbookot szeretne aktiválni egy riasztásból, olvassa el az Azure Automation-runbook aktiválása riasztással című témakört.