Starta en runbook från en webhook

  • Artikel

Med en webhook kan du låta en extern tjänst starta en viss runbook i Azure Automation via en enkel HTTP-förfrågan. Den externa tjänsten kan vara Azure DevOps Services, GitHub, Azure Monitor-loggar eller anpassade appar. En sådan tjänst kan använda en webhook för att starta en runbook utan att implementera hela Azure Automation-API:et. Du kan jämföra webhooks med andra metoder för att starta en runbook i Starta en runbook i Azure Automation.

WebhooksOverview

Information om klientkrav för TLS 1.2 eller senare med webhooks finns i TLS för Azure Automation.

Webhook-egenskaper

I följande tabell beskrivs de egenskaper du måste konfigurera för en webhook.

Egenskap Beskrivning
Name Namnet på webhooken. Du kan ange vilket namn du vill eftersom det inte exponeras för klienten. Det används bara till att identifiera runbooken i Azure Automation. Vi rekommenderar att du ger webhooken ett namn som är relaterat till klienten som använder den.
URL Webhookens webbadress. Det här är den unika adress som en klient anropar med HTTP POST för att starta runbooken som är länkad till webhooken. Adressen genereras automatiskt när du skapar webhooken. Du kan inte ange en anpassad webbadress.

Webbadressen innehåller en säkerhetstoken som gör att ett system från tredje part kan anropa runbooken utan ytterligare autentisering. Därför bör du behandla den här webbadressen som ett lösenord. Av säkerhetsskäl kan du bara visa URL:en i Azure-portalen när du skapar webhooken. Observera URL:en på en säker plats för framtida användning.
Förfallodatum Webhookens förfallodatum. Efter det här datumet kan du inte använda den längre. Du kan ändra förfallodatumet efter att webhooken har skapats så länge webhooken inte har upphört att gälla.
Enabled Inställning som anger om webhooken är aktiverad som standard när den skapas. Om du anger den här egenskapen till Inaktiverad kan ingen klient använda webhooken. Du kan ange den här egenskapen när du skapar webhooken eller någon annan gång efter att den har skapats.

Parametrar som används när webhooken startar en runbook

En webhook kan definiera värden för runbook-parametrar som används när runbooken startar. Webhooken måste innehålla värden för obligatoriska runbook-parametrar och kan innehålla värden för valfria parametrar. Ett parametervärde som konfigurerats för en webhook kan ändras även efter att webhooken har skapats. Flera webhooks som är länkade till en enda runbook kan använda olika runbook-parametervärden. När en klient startar en runbook med en webhook kan den inte åsidosätta parametervärdena som definierats i webhooken.

För att ta emot data från klienten stöder runbooken en enda parameter med namnet WebhookData. Den här parametern definierar ett objekt som innehåller data som klienten innehåller i en POST-begäran.

WebhookData-egenskaper

Parametern WebhookData har följande egenskaper:

Property beskrivning
WebhookName Namnet på webhooken.
RequestHeader PSCustomObject innehåller rubrikerna för den inkommande POST-begäran.
RequestBody Brödtext för den inkommande POST-begäran. Den här brödtexten behåller all dataformatering, till exempel sträng, JSON, XML eller formulärkodad. Runbooken måste skrivas för att fungera med det dataformat som förväntas.

Det finns ingen konfiguration av webhooken som krävs för att stödja parametern WebhookData och runbooken krävs inte för att acceptera den. Om runbooken inte definierar parametern ignoreras all information om begäran som skickas från klienten.

Kommentar

När du anropar en webhook bör klienten alltid lagra alla parametervärden om anropet misslyckas. Om det uppstår ett nätverksfel eller ett anslutningsproblem kan programmet inte hämta misslyckade webhook-anrop.

Om du anger ett värde för WebhookData när webhook skapas, åsidosättas det när webhooken startar runbooken med data från klientens POST-begäran. Detta händer även om programmet inte innehåller några data i begärandetexten.

Om du startar en runbook som definierar WebhookData med en annan mekanism än en webhook kan du ange ett värde för WebhookData som runbooken känner igen. Det här värdet ska vara ett objekt med samma egenskaper som parametern WebhookData så att runbooken kan fungera med det precis som det fungerar med faktiska WebhookData objekt som skickas av en webhook.

Om du till exempel startar följande runbook från Azure-portalen och vill skicka exempelwebbhooksdata för testning måste du skicka data i JSON i användargränssnittet.

WebhookData-parameter från användargränssnittet

I nästa runbook-exempel ska vi definiera följande egenskaper för WebhookData:

  • WebhookName: MyWebhook
  • RequestBody: *[{'ResourceGroup': 'myResourceGroup','Name': 'vm01'},{'ResourceGroup': 'myResourceGroup','Name': 'vm02'}]*

Nu skickar vi följande JSON-objekt i användargränssnittet för parametern WebhookData . Det här exemplet, med vagnreturer och nyradstecken, matchar det format som skickas från en 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]"}

Starta WebhookData-parametern från användargränssnittet

Kommentar

Azure Automation loggar värdena för alla indataparametrar med runbook-jobbet. Därför loggas alla indata som tillhandahålls av klienten i webhook-begäran och är tillgängliga för alla som har åtkomst till automationsjobbet. Därför bör du vara försiktig med att inkludera känslig information i webhook-anrop.

Webhook-säkerhet

Säkerheten för en webhook är beroende av webbadressens integritet, den innehåller en säkerhetstoken som tillåter att webhooken anropas. Azure Automation utför ingen autentisering på en begäran så länge den görs till rätt URL. Därför bör inte dina klienter använda webhooks för runbooks som utför mycket känsliga åtgärder utan att använda något alternativt sätt att verifiera förfrågan.

Föreställ dig följande strategier:

  • Du kan inkludera logik i en runbook för att avgöra om den anropas av en webhook. Låt runbooken WebhookName kontrollera parameterns WebhookData egenskap. Runbooken kan utföra ytterligare validering genom att söka efter viss information i RequestHeader egenskaperna och RequestBody .

  • Be runbooken att utföra en viss validering av ett externt villkor när den tar emot en webhook-begäran. Tänk dig till exempel en runbook som anropas av GitHub när det finns en ny incheckning till en GitHub-lagringsplats. Runbooken kan ansluta till GitHub för att verifiera att en ny incheckning har inträffat innan du fortsätter.

  • Azure Automation stöder tjänsttaggar för virtuella Azure-nätverk, särskilt GuestAndHybridManagement. Du kan använda tjänsttaggar för att definiera nätverksåtkomstkontroller i nätverkssäkerhetsgrupper eller Azure Firewall och utlösa webhooks inifrån ditt virtuella nätverk. Du kan använda tjänsttaggar i stället för specifika IP-adresser när du skapar säkerhetsregler. Genom att ange tjänsttaggen GuestAndHybridManagement i lämpligt käll- eller målfält för en regel kan du tillåta eller neka trafik för Automation-tjänsten. Den här tjänsttaggen har inte stöd för att tillåta mer detaljerad kontroll genom att begränsa IP-intervall till en viss region.

Skapa en webhook

Kommentar

När du använder webhooken med PowerShell 7-runbooken konverteras webhook-indataparametern automatiskt till en ogiltig JSON. Mer information finns i Kända problem – PowerShell 7.1 (förhandsversion). Vi rekommenderar att du använder webhooken med PowerShell 5-runbooken.

  1. Skapa PowerShell-runbook med följande kod:

    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. Skapa en webhook med hjälp av Azure-portalen, PowerShell eller REST API. En webhook kräver en publicerad runbook. Den här genomgången använder en modifierad version av runbooken som skapats från Skapa en Azure Automation-runbook.

    1. Logga in på Azure-portalen.

    2. Gå till ditt Automation-konto i Azure-portalen.

    3. Under ProcessAutomatisering väljer du Runbooks för att öppna sidan Runbooks .

    4. Välj din runbook i listan för att öppna sidan Översikt över Runbook.

    5. Välj Lägg till webhook för att öppna sidan Lägg till webhook .

      Översiktssida för Runbook med Lägg till webhook markerat.

    6. På sidan Lägg till webhook väljer du Skapa ny webhook.

      Lägg till webhook-sida med skapa markerat.

    7. Ange webhookens namn . Förfallodatumet för fältet Förfaller som standard ett år från det aktuella datumet.

    8. Klicka på kopieringsikonen eller tryck på Ctrl + C kopiera url:en för webhooken. Spara sedan URL:en på en säker plats.

      Skapa webhookssida med URL markerad.

      Viktigt!

      När du har skapat webhooken kan du inte hämta URL:en igen. Se till att du kopierar och registrerar den som ovan.

    9. Välj OK för att återgå till sidan Lägg till webhook .

    10. På sidan Lägg till webhook väljer du Konfigurera parametrar och kör inställningar för att öppna sidan Parametrar .

      Lägg till webhook-sida med parametrar markerade.

    11. Granska sidan Parametrar . För den exempel runbook som används i den här artikeln behövs inga ändringar. Välj OK för att återgå till sidan Lägg till webhook .

    12. På sidan Lägg till webhook väljer du Skapa. Webhooken skapas och du returneras till sidan Översikt över Runbook.

Använda en webhook

I det här exemplet används PowerShell-cmdleten Invoke-WebRequest för att skicka POST-begäran till din nya webhook.

  1. Förbered värden för att skicka till runbooken som brödtext för webhooksanropet. För relativt enkla värden kan du skripta värdena på följande sätt:

    $Names  = @(
            @{ Name="Hawaii"},
            @{ Name="Seattle"},
            @{ Name="Florida"}
        )

$body = ConvertTo-Json -InputObject $Names

  2. För större uppsättningar kanske du vill använda en fil. Skapa en fil med namnet names.json och klistra sedan in följande kod::

    [
    { "Name": "Hawaii" },
    { "Name": "Florida" },
    { "Name": "Seattle" }
]

    Ändra värdet för variabeln $file med den faktiska sökvägen till json-filen innan du kör följande PowerShell-kommandon.

    # Revise file path with actual path
$file = "path\names.json"
$bodyFile = Get-Content -Path $file

  3. Kör följande PowerShell-kommandon för att anropa webhooken med hjälp av REST-API:et.

    $response = Invoke-WebRequest -Method Post -Uri $webhookURI -Body $body -UseBasicParsing
$response

$responseFile = Invoke-WebRequest -Method Post -Uri $webhookURI -Body $bodyFile -UseBasicParsing
$responseFile

    För illustrativa ändamål gjordes två anrop för de två olika metoderna för att producera kroppen. Använd endast en metod för produktion. Utdata bör se ut ungefär så här (endast en utdata visas):

    Utdata från webhook-anrop.

    Klienten tar emot någon av följande returkoder från POST begäran.

    Kod Text beskrivning
    202 Godkänd Begäran accepterades och runbooken har placerats i kö.
    400 Felaktig förfrågan Begäran accepterades inte av någon av följande orsaker:
    • Webhooken har upphört att gälla.
    • Webhooken är inaktiverad.
    • Token i URL:en är ogiltig.
    404 Hittades inte Begäran accepterades inte av någon av följande orsaker:
    • Webhooken hittades inte.
    • Runbooken hittades inte.
    • Kontot hittades inte.
    500 Internt serverfel URL:en var giltig, men ett fel uppstod. Skicka begäran igen.

    Förutsatt att begäran lyckas innehåller webhook-svaret jobb-ID:t i JSON-format enligt nedan. Den innehåller ett enda jobb-ID, men JSON-formatet möjliggör potentiella framtida förbättringar.

    {"JobIds":["<JobId>"]}

  4. PowerShell-cmdleten Get-AzAutomationJobOutput används för att hämta utdata. Azure Automation-API:et kan också användas.

    #isolate job ID
$jobid = (ConvertFrom-Json ($response.Content)).jobids[0]

# Get output
Get-AzAutomationJobOutput `
    -AutomationAccountName $automationAccount `
    -Id $jobid `
    -ResourceGroupName $resourceGroup `
    -Stream Output

    När du utlöser en runbook som skapades i föregående steg skapas ett jobb och utdata bör se ut ungefär så här:

    Utdata från webhook-jobb.

Uppdatera en webhook

När du skapar en webhook har den en giltighetstid på 10 år, och efter det upphör den automatiskt att gälla. När en webhook har upphört att gälla kan du inte återaktivera den. Du kan bara ta bort och sedan återskapa det. Du kan förlänga en webhook som inte har upphört att gälla. Utför följande steg för att utöka en webhook.

  1. Gå till runbooken som innehåller webhooken.
  2. Under Resurser väljer du Webhooks och sedan den webhook som du vill utöka.
  3. På sidan Webhook väljer du ett nytt förfallodatum och en ny förfallotid och väljer sedan Spara.

Granska API-anropet Webhook – Update och PowerShell-cmdleten Set-AzAutomationWebhook för andra möjliga ändringar.

Rensa resurser

Här är exempel på hur du tar bort en webhook från en Automation-runbook.

  • Med PowerShell kan cmdleten Remove-AzAutomationWebhook användas enligt nedan. Inga utdata returneras.

    Remove-AzAutomationWebhook `
    -ResourceGroup $resourceGroup `
    -AutomationAccountName $automationAccount `
    -Name $psWebhook

  • Med REST kan REST Webhook – Delete API användas enligt nedan.

    Invoke-WebRequest -Method Delete -Uri $restURI -Headers $authHeader

    Ett utdata av StatusCode : 200 innebär en lyckad borttagning.

Skapa runbook och webhook med ARM-mall

Automation-webhooks kan också skapas med hjälp av Azure Resource Manager-mallar . Den här exempelmallen skapar ett Automation-konto, fyra runbooks och en webhook för den namngivna runbooken.

  1. Skapa en fil med namnet webhook_deploy.json och klistra sedan in följande kod:

    {
    "$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. Följande PowerShell-kodexempel distribuerar mallen från datorn. Ange ett lämpligt värde för variablerna och kör sedan skriptet.

    $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

    Kommentar

    Av säkerhetsskäl returneras URI:n först första gången en mall distribueras.

Nästa steg