Notitie
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen u aan te melden of de directory te wijzigen.
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen de mappen te wijzigen.
Met een webhook kan een externe service een bepaald runbook starten in Azure Automation via één 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 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.
| Property | Description |
|---|---|
| Name | 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. |
| Enabled | 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:
| Property | Description |
|---|---|
| WebhookName | Naam van de webhook. |
| RequestHeader | PSCustomObject met de headers van de binnenkomende POST-aanvraag. |
| RequestBody | Hoofdtekst van de binnenkomende POST-aanvraag. In deze body worden gegevensformaten behouden, zoals tekenreeks, JSON, XML of formuliercodering. Het runbook moet zodanig worden opgesteld dat het werkt met het verwachte dataformaat. |
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.
Note
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 bij het aanmaken van een webhook, wordt deze overschreven wanneer de webhook het runbook start met de gegevens van het POST-verzoek 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]"}
Note
Azure Automation registreert de waarden van alle invoerparameters tijdens het uitvoeren van de runbook-job. 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.
Houd rekening met 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
WebhookNameeigenschap van deWebhookDataparameter controleren. Het runbook kan verdere validatie uitvoeren door te zoeken naar specifieke informatie in deRequestHeaderenRequestBodyeigenschappen.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 commit naar een GitHub-repository is. Het runbook kan verbinding maken met GitHub om te valideren dat er een nieuwe commit is opgetreden voordat er wordt doorgegaan.
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
Note
- 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. We raden aan om de webhook te gebruiken met een PowerShell 5 runbook.
- Het gebruik van een webhook om een Python-runbook te starten, wordt niet ondersteund.
Voer de volgende stappen uit om een webhook te maken:
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.
Ga als volgt te werk om een webhook te maken met behulp van Azure Portal:
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 Runbook Overview-pagina te openen.
Selecteer Webhook toevoegen om de pagina Webhook toevoegen te openen.
Selecteer op de pagina Webhook toevoegende 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.
Selecteer het kopieerpictogram of druk op Ctrl+C om de URL van de webhook te kopiëren. Sla vervolgens de URL op een veilige locatie op.
Important
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 toevoegende optie Parameters configureren en voer instellingen uit om de pagina Parameters te openen.
Bekijk 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 is aangemaakt en je wordt teruggeleid naar de Runbook Overzicht-pagina.
Een webhook gebruiken
In dit voorbeeld wordt de PowerShell-cmdlet Invoke-WebRequest gebruikt om de POST-aanvraag naar uw nieuwe webhook te verzenden.
Voer de volgende stappen uit om een webhook te gebruiken:
Bereid waarden voor om door te geven aan het runbook als inhoud 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 $NamesVoor grotere sets kunt u een bestand gebruiken. Maak een bestand met de naam
names.jsonen plak de volgende code:[ { "Name": "Hawaii" }, { "Name": "Florida" }, { "Name": "Seattle" } ]Wijzig de waarde voor de variabele
$filemet 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 $fileVoer 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 $responseFileTer 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
POSTaanvraag.Code Text Description 202 Accepted De aanvraag is geaccepteerd, het runbook is succesvol 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. Als de aanvraag succesvol is, bevat de webhook-respons de taak-id in JSON-indeling, zoals hieronder te zien is. 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 OutputWanneer 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 Resourceswebhooks en vervolgens de webhook die u wilt uitbreiden.
- Kies op de pagina Webhook een nieuwe vervaldatum en -tijd en selecteer Opslaan.
Bekijk de API-aanroep Webhook - Update en de PowerShell-cmdlet Set-AzAutomationWebhook voor andere mogelijke wijzigingen.
De hulpbronnen 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 $psWebhookMet REST kan de REST-webhook - Delete-API worden gebruikt, zoals hieronder wordt weergegeven.
Invoke-WebRequest -Method Delete -Uri $restURI -Headers $authHeaderEen uitvoer van
StatusCode : 200betekent een geslaagde verwijdering.
Creëer een runbook en webhook met een 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.
Volg deze stappen om een webhook te maken met behulp van een ARM-sjabloon:
Maak een bestand met de naam
webhook_deploy.jsonen 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 $webhookExpiryTimeNote
Om veiligheidsredenen wordt de URI alleen geretourneerd wanneer een sjabloon voor het eerst wordt geïmplementeerd.