Een runbook starten vanuit een webhook
Een externe service kan met een webhook een bepaald runbook in Azure Automation starten via een afzonderlijke HTTP-aanvraag. Externe services zijn onder andere Azure DevOps Services, GitHub, Azure Monitor-logboeken en aangepaste toepassingen. Een dergelijke service kan een webhook gebruiken om een runbook te starten zonder de volledige Azure Automation-API te implementeren. U kunt webhooks vergelijken met andere methoden voor het starten van een runbook in Het starten van een runbook in Azure Automation.
Zie TLS voor Azure Automation voor meer informatie over clientvereisten voor TLS 1.2 of hoger met webhooks.
Eigenschappen van webhook
In de volgende tabel worden de eigenschappen beschreven die u moet configureren voor een webhook.
Eigenschap | Beschrijving |
---|---|
Naam | Naam van de webhook. U kunt elke gewenste naam opgeven, omdat deze niet beschikbaar is voor de client. Deze wordt alleen gebruikt om het runbook in Azure Automation te identificeren. Als best practice wordt aanbevolen dat u de webhook een naam geeft die is gerelateerd aan de client die de webhook gebruikt. |
URL | URL van de webhook. Dit is het unieke adres dat een client aanroept met een HTTP POST om het runbook te starten dat is gekoppeld aan de webhook. Het wordt automatisch gegenereerd wanneer u de webhook maakt. U kunt geen aangepaste URL opgeven. De URL bevat een beveiligingstoken waarmee een systeem van derden het runbook kan aanroepen zonder verdere verificatie. Daarom moet u de URL behandelen als een wachtwoord. Om veiligheidsredenen kunt u alleen de URL in Azure Portal bekijken bij het maken van de webhook. Noteer de URL op een veilige locatie voor toekomstig gebruik. |
Vervaldatum | Vervaldatum van de webhook, waarna deze niet meer kan worden gebruikt. U kunt de vervaldatum wijzigen nadat de webhook is gemaakt, zolang de webhook niet is verlopen. |
Ingeschakeld | Instelling die aangeeft of de webhook standaard is ingeschakeld wanneer deze wordt gemaakt. Als u deze eigenschap instelt op Uitgeschakeld, kan geen enkele client de webhook gebruiken. U kunt deze eigenschap instellen wanneer u de webhook of een andere keer na het maken ervan maakt. |
Parameters die worden gebruikt wanneer de webhook een runbook start
Een webhook kan waarden definiëren voor runbookparameters die worden gebruikt wanneer het runbook wordt gestart. De webhook moet waarden bevatten voor verplichte runbookparameters en kan waarden voor optionele parameters bevatten. Een parameterwaarde die is geconfigureerd voor een webhook, kan zelfs na het maken van de webhook worden gewijzigd. Meerdere webhooks die aan één runbook zijn gekoppeld, kunnen elk verschillende runbookparameterwaarden gebruiken. Wanneer een client een runbook start met behulp van een webhook, kunnen de parameterwaarden die in de webhook zijn gedefinieerd, niet worden overschreven.
Als u gegevens van de client wilt ontvangen, ondersteunt het runbook één parameter met de naam WebhookData
. Deze parameter definieert een object met gegevens die de client in een POST-aanvraag bevat.
De WebhookData
parameter heeft de volgende eigenschappen:
Eigenschappen | Beschrijving |
---|---|
WebhookName | Naam van de webhook. |
RequestHeader | PSCustomObject met de headers van de binnenkomende POST-aanvraag. |
RequestBody | Hoofdtekst van de binnenkomende POST-aanvraag. In deze hoofdtekst worden gegevensopmaak bewaard, zoals tekenreeks, JSON, XML of formuliercodering. Het runbook moet worden geschreven om te werken met de gegevensindeling die wordt verwacht. |
Er is geen configuratie van de webhook vereist om de WebhookData
parameter te ondersteunen en het runbook is niet vereist om deze te accepteren. Als het runbook de parameter niet definieert, worden alle details van de aanvraag die vanaf de client wordt verzonden genegeerd.
Notitie
Bij het aanroepen van een webhook moet de client altijd parameterwaarden opslaan voor het geval de aanroep mislukt. Als er sprake is van een netwerkstoring of verbindingsprobleem, kan de toepassing mislukte webhookaanroepen niet ophalen.
Als u een waarde opgeeft voor WebhookData
het maken van een webhook, wordt deze overschreven wanneer de webhook het runbook start met de gegevens uit de POST-aanvraag van de client. Dit gebeurt zelfs als de toepassing geen gegevens in de aanvraagbody bevat.
Als u een runbook start dat definieert WebhookData
met een ander mechanisme dan een webhook, kunt u een waarde opgeven die WebhookData
door het runbook wordt herkend. Deze waarde moet een object zijn met dezelfde eigenschappen als de WebhookData
parameter, zodat het runbook ermee kan werken, net zoals het werkt met werkelijke WebhookData
objecten die door een webhook worden doorgegeven.
Als u bijvoorbeeld het volgende runbook start vanuit Azure Portal en enkele voorbeeldwebhookgegevens wilt doorgeven voor testen, moet u de gegevens in JSON doorgeven in de gebruikersinterface.
Voor het volgende runbookvoorbeeld definiëren we de volgende eigenschappen voor WebhookData
:
- WebhookName: MyWebhook
- RequestBody:
*[{'ResourceGroup': 'myResourceGroup','Name': 'vm01'},{'ResourceGroup': 'myResourceGroup','Name': 'vm02'}]*
Nu geven we het volgende JSON-object door in de gebruikersinterface voor de WebhookData
parameter. In dit voorbeeld komen regelteruglooptekens en newlinetekens overeen met de indeling die wordt doorgegeven vanuit een webhook.
{"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]"}
Notitie
Azure Automation registreert de waarden van alle invoerparameters met de runbooktaak. Alle invoer die door de client in de webhookaanvraag wordt geleverd, wordt dus geregistreerd en beschikbaar voor iedereen met toegang tot de automatiseringstaak. Daarom moet u voorzichtig zijn met het opnemen van gevoelige informatie in webhook-aanroepen.
Webhookbeveiliging
De beveiliging van een webhook is afhankelijk van de privacy van de URL, die een beveiligingstoken bevat waarmee de webhook kan worden aangeroepen. Azure Automation voert geen verificatie uit op een aanvraag zolang deze wordt gedaan naar de juiste URL. Daarom is het beter dat uw clients geen webhooks gebruiken voor runbooks die zeer gevoelige bewerkingen uitvoeren zonder een alternatieve methode te gebruiken om de aanvraag te valideren.
Overweeg de volgende strategieën:
U kunt logica opnemen in een runbook om te bepalen of het wordt aangeroepen door een webhook. Laat het runbook de
WebhookName
eigenschap van deWebhookData
parameter controleren. Het runbook kan verdere validatie uitvoeren door te zoeken naar specifieke informatie in deRequestHeader
enRequestBody
eigenschappen.Laat het runbook een validatie uitvoeren van een externe voorwaarde wanneer er een webhookaanvraag wordt ontvangen. Denk bijvoorbeeld aan een runbook dat door GitHub wordt aangeroepen wanneer er een nieuwe doorvoering naar een GitHub-opslagplaats is. Het runbook kan verbinding maken met GitHub om te valideren dat er een nieuwe doorvoering is opgetreden voordat u doorgaat.
Azure Automation ondersteunt servicetags voor virtuele Netwerken van Azure, met name GuestAndHybridManagement. U kunt servicetags gebruiken om besturingselementen voor netwerktoegang in netwerkbeveiligingsgroepen of Azure Firewall te definiëren en webhooks vanuit uw virtuele netwerk te activeren. Servicetags kunnen worden gebruikt in plaats van specifieke IP-adressen wanneer u beveiligingsregels maakt. Door de servicetagnaam GuestAndHybridManagement op te geven in het juiste bron- of doelveld van een regel, kunt u het verkeer voor de Automation-service toestaan of weigeren. Deze servicetag biedt geen ondersteuning voor gedetailleerder beheer door IP-bereiken te beperken tot een specifieke regio.
Een webhook maken
Notitie
Wanneer u de webhook gebruikt met een PowerShell 7-runbook, wordt de invoerparameter van de webhook automatisch geconverteerd naar een ongeldige JSON. Zie Bekende problemen - PowerShell 7.1 (preview) voor meer informatie. U wordt aangeraden de webhook te gebruiken met een PowerShell 5-runbook.
Maak een PowerShell-runbook met de volgende code:
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!" }
Maak een webhook met behulp van Azure Portal of PowerShell of REST API. Voor een webhook is een gepubliceerd runbook vereist. In deze procedure wordt een gewijzigde versie van het runbook gebruikt dat is gemaakt op basis van Een Azure Automation-runbook maken.
Meld u aan bij het Azure-portaal.
Navigeer in Azure Portal naar uw Automation-account.
Selecteer runbooks onder Procesautomatisering om de pagina Runbooks te openen.
Selecteer uw runbook in de lijst om de pagina RunbookOverzicht te openen.
Selecteer Webhook toevoegen om de pagina Webhook toevoegen te openen.
Selecteer op de pagina Webhook toevoegen de optie Nieuwe webhook maken.
Voer de naam voor de webhook in. De vervaldatum voor het veld Verloopt is standaard ingesteld op één jaar vanaf de huidige datum.
Klik op het kopieerpictogram of druk op Ctrl+C om de URL van de webhook te kopiëren. Sla de URL vervolgens op een veilige locatie op.
Belangrijk
Nadat u de webhook hebt gemaakt, kunt u de URL niet meer ophalen. Zorg ervoor dat u deze kopieert en opneemt zoals hierboven.
Selecteer OK om terug te keren naar de pagina Webhook toevoegen.
Selecteer op de pagina Webhook toevoegen de optie Parameters configureren en voer instellingen uit om de pagina Parameters te openen.
Controleer de pagina Parameters . Voor het voorbeeldrunbook dat in dit artikel wordt gebruikt, zijn er geen wijzigingen nodig. Selecteer OK om terug te keren naar de pagina Webhook toevoegen.
Selecteer Maken op de pagina Webhook toevoegen. De webhook wordt gemaakt en u keert terug naar de pagina RunbookOverzicht.
Een webhook gebruiken
In dit voorbeeld wordt de PowerShell-cmdlet Invoke-WebRequest gebruikt om de POST-aanvraag naar uw nieuwe webhook te verzenden.
Bereid waarden voor om door te geven aan het runbook als hoofdtekst voor de webhook-aanroep. Voor relatief eenvoudige waarden kunt u de waarden als volgt uitvoeren:
$Names = @( @{ Name="Hawaii"}, @{ Name="Seattle"}, @{ Name="Florida"} ) $body = ConvertTo-Json -InputObject $Names
Voor grotere sets kunt u een bestand gebruiken. Maak een bestand met de naam
names.json
en plak de volgende code::[ { "Name": "Hawaii" }, { "Name": "Florida" }, { "Name": "Seattle" } ]
Wijzig de waarde voor de variabele
$file
met het werkelijke pad naar het json-bestand voordat u de volgende PowerShell-opdrachten uitvoert.# Revise file path with actual path $file = "path\names.json" $bodyFile = Get-Content -Path $file
Voer de volgende PowerShell-opdrachten uit om de webhook aan te roepen met behulp van de REST API.
$response = Invoke-WebRequest -Method Post -Uri $webhookURI -Body $body -UseBasicParsing $response $responseFile = Invoke-WebRequest -Method Post -Uri $webhookURI -Body $bodyFile -UseBasicParsing $responseFile
Ter illustratie werden twee aanroepen gedaan voor de twee verschillende methoden om het lichaam te produceren. Gebruik slechts één methode voor productie. De uitvoer moet er als volgt uitzien (er wordt slechts één uitvoer weergegeven):
De client ontvangt een van de volgende retourcodes van de
POST
aanvraag.Code Sms verzenden Beschrijving 202 Geaccepteerd De aanvraag is geaccepteerd en het runbook is in de wachtrij geplaatst. 400 Onjuiste aanvraag De aanvraag is om een van de volgende redenen niet geaccepteerd: - De webhook is verlopen.
- De webhook is uitgeschakeld.
- Het token in de URL is ongeldig.
404 Niet gevonden De aanvraag is om een van de volgende redenen niet geaccepteerd: - De webhook is niet gevonden.
- Het runbook is niet gevonden.
- Het account is niet gevonden.
500 Interne serverfout De URL is geldig, maar er is een fout opgetreden. Verzend de aanvraag opnieuw. Ervan uitgaande dat de aanvraag is geslaagd, bevat het webhookantwoord de taak-id in JSON-indeling, zoals hieronder wordt weergegeven. Het bevat één taak-id, maar de JSON-indeling maakt potentiële toekomstige verbeteringen mogelijk.
{"JobIds":["<JobId>"]}
De PowerShell-cmdlet Get-AzAutomationJobOutput wordt gebruikt om de uitvoer op te halen. De Azure Automation-API kan ook worden gebruikt.
#isolate job ID $jobid = (ConvertFrom-Json ($response.Content)).jobids[0] # Get output Get-AzAutomationJobOutput ` -AutomationAccountName $automationAccount ` -Id $jobid ` -ResourceGroupName $resourceGroup ` -Stream Output
Wanneer u een runbook activeert dat in de vorige stap is gemaakt, wordt er een taak gemaakt en ziet de uitvoer er ongeveer als volgt uit:
Een webhook bijwerken
Wanneer een webhook wordt gemaakt, heeft deze een geldigheidsperiode van 10 jaar, waarna deze automatisch verloopt. Zodra een webhook is verlopen, kunt u deze niet opnieuw activeren. U kunt deze alleen verwijderen en vervolgens opnieuw maken. U kunt een webhook verlengen die de vervaltijd niet heeft bereikt. Voer de volgende stappen uit om een webhook uit te breiden.
- Navigeer naar het runbook dat de webhook bevat.
- Selecteer onder Resources webhooks en vervolgens de webhook die u wilt uitbreiden.
- Kies op de pagina Webhook een nieuwe vervaldatum en -tijd en selecteer Opslaan.
Bekijk de WEBhook voor API-aanroep - Update en PowerShell-cmdlet Set-AzAutomationWebhook voor andere mogelijke wijzigingen.
Resources opschonen
Hier volgen voorbeelden van het verwijderen van een webhook uit een Automation-runbook.
Met Behulp van PowerShell kan de cmdlet Remove-AzAutomationWebhook worden gebruikt, zoals hieronder wordt weergegeven. Er wordt geen uitvoer geretourneerd.
Remove-AzAutomationWebhook ` -ResourceGroup $resourceGroup ` -AutomationAccountName $automationAccount ` -Name $psWebhook
Met REST kan de REST-webhook - Delete-API worden gebruikt, zoals hieronder wordt weergegeven.
Invoke-WebRequest -Method Delete -Uri $restURI -Headers $authHeader
Een uitvoer van
StatusCode : 200
een geslaagde verwijdering.
Runbook en webhook maken met ARM-sjabloon
Automation-webhooks kunnen ook worden gemaakt met behulp van Azure Resource Manager-sjablonen . Met deze voorbeeldsjabloon maakt u een Automation-account, vier runbooks en een webhook voor het benoemde runbook.
Maak een bestand met de naam
webhook_deploy.json
en plak de volgende code:{ "$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]" } } }
Met het volgende PowerShell-codevoorbeeld wordt de sjabloon van uw computer geïmplementeerd. Geef een geschikte waarde op voor de variabelen en voer vervolgens het script uit.
$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
Notitie
Om veiligheidsredenen wordt de URI alleen geretourneerd wanneer een sjabloon voor het eerst wordt geïmplementeerd.
Volgende stappen
- Zie Een waarschuwing gebruiken om een Azure Automation-runbook te activeren als u een runbook vanuit een waarschuwing wilt activeren.