Runbook indítása webhookból
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.
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 WebhookData
támogat. Ez a paraméter egy olyan objektumot határoz meg, amely adatokat tartalmaz az ügyfél egy POST-kérelemben.
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ágokkal WebhookData
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.
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]"}
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átWebhookData
. A runbook további ellenőrzést végezhet, ha konkrét információkat keres a tulajdonságokban ésRequestBody
aRequestHeader
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.
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!" }
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.
Jelentkezzen be az Azure Portalra.
Az Azure Portalon lépjen az Automation-fiókjához.
A Folyamatautomatizálás területen válassza a Runbookok lehetőséget a Runbookok lap megnyitásához.
A runbook áttekintési oldalának megnyitásához válassza ki a runbookot a listából.
A Webhook hozzáadása lap megnyitásához válassza a Webhook hozzáadása lehetőséget.
A Webhook hozzáadása lapon válassza az Új webhook létrehozása lehetőséget.
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.
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.
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.
Kattintson az OK gombra a Webhook hozzáadása lapra való visszatéréshez.
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.
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.
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.
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
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
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):
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>"]}
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:
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.
- Lépjen a webhookot tartalmazó runbookra.
- Az Erőforrások területen válassza a Webhookok lehetőséget, majd a kiterjeszteni kívánt webhookot.
- 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.
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]" } } }
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
Visszajelzés
https://aka.ms/ContentUserFeedback.
Hamarosan elérhető: 2024-ben fokozatosan kivezetjük a GitHub-problémákat a tartalom visszajelzési mechanizmusaként, és lecseréljük egy új visszajelzési rendszerre. További információ:Visszajelzés küldése és megtekintése a következőhöz: