Delen via


Een runbook starten vanuit een webhook

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.

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.

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.

Eigenschappen van WebhookData

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.

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

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 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 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:

  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.

    Ga als volgt te werk om een webhook te maken met behulp van Azure Portal:

    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 Runbook Overview-pagina te openen.

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

      Overzichtspagina van het runbook met de optie Webhook toevoegen gemarkeerd.

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

      Webhookpagina toevoegen met 'Create' 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. 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.

      Een webhookpagina maken met de URL gemarkeerd.

      Important

      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 toevoegende optie Parameters configureren en voer instellingen uit om de pagina Parameters te openen.

      Pagina webhook toevoegen met parameters gemarkeerd.

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

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

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

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 Resourceswebhooks en vervolgens de webhook die u wilt uitbreiden.
  3. 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 $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 betekent 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:

  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
    

    Note

    Om veiligheidsredenen wordt de URI alleen geretourneerd wanneer een sjabloon voor het eerst wordt geïmplementeerd.

Volgende stappen