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.

WebhooksOverview

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.

Eigenschappen van WebhookData

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.

WebhookData-parameter uit 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]"}

WebhookData-parameter starten vanuit de gebruikersinterface

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 de WebhookData parameter controleren. Het runbook kan verdere validatie uitvoeren door te zoeken naar specifieke informatie in de RequestHeader en RequestBody 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.

  1. 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!"
    }
    
  2. 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.

    1. Meld u aan bij het Azure-portaal.

    2. Navigeer in Azure Portal naar uw Automation-account.

    3. Selecteer runbooks onder Procesautomatisering om de pagina Runbooks te openen.

    4. Selecteer uw runbook in de lijst om de pagina RunbookOverzicht te openen.

    5. Selecteer Webhook toevoegen om de pagina Webhook toevoegen te openen.

      Overzichtspagina runbook met Webhook toevoegen gemarkeerd.

    6. Selecteer op de pagina Webhook toevoegen de optie Nieuwe webhook maken.

      Pagina webhook toevoegen met maken gemarkeerd.

    7. Voer de naam voor de webhook in. De vervaldatum voor het veld Verloopt is standaard ingesteld op één jaar vanaf de huidige datum.

    8. 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.

      Creaye-webhookpagina met URL gemarkeerd.

      Belangrijk

      Nadat u de webhook hebt gemaakt, kunt u de URL niet meer ophalen. Zorg ervoor dat u deze kopieert en opneemt zoals hierboven.

    9. Selecteer OK om terug te keren naar de pagina Webhook toevoegen.

    10. Selecteer op de pagina Webhook toevoegen de optie Parameters configureren en voer instellingen uit om de pagina Parameters te openen.

      Pagina webhook toevoegen met parameters gemarkeerd.

    11. 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.

    12. 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.

  1. 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
    
  2. 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 
    
  3. 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):

    Uitvoer van webhook-aanroep.

    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>"]}
    
  4. 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:

    Uitvoer van webhooktaak.

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.

  1. Navigeer naar het runbook dat de webhook bevat.
  2. Selecteer onder Resources webhooks en vervolgens de webhook die u wilt uitbreiden.
  3. 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.

  1. 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]"
            }
        }
    }
    
  2. 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