Starta en Azure Automation Runbook med en webhookStarting an Azure Automation runbook with a webhook

Med en webhook kan en extern tjänst starta en viss Runbook i Azure Automation via en enda HTTP-begäran.A webhook allows an external service to start a particular runbook in Azure Automation through a single HTTP request. Externa tjänster omfattar Azure DevOps Services, GitHub, Azure Monitor loggar och anpassade program.External services include Azure DevOps Services, GitHub, Azure Monitor logs, and custom applications. En sådan tjänst kan använda en webhook för att starta en Runbook utan att implementera en fullständig lösning med hjälp av Azure Automation API.Such a service can use a webhook to start a runbook without implementing a full solution using the Azure Automation API. Du kan jämföra Webhooks med andra metoder för att starta en runbook när du startar en Runbook i Azure Automation.You can compare webhooks to other methods of starting a runbook in Starting a runbook in Azure Automation.

Anteckning

Det finns inte stöd för att använda en webhook för att starta en python-Runbook.Using a webhook to start a Python runbook is not supported.

WebhooksOverview

Anteckning

Den här artikeln har uppdaterats till att använda den nya Azure PowerShell Az-modulen.This article has been updated to use the new Azure PowerShell Az module. Du kan fortfarande använda modulen AzureRM som kommer att fortsätta att ta emot felkorrigeringar fram till december 2020 eller längre.You can still use the AzureRM module, which will continue to receive bug fixes until at least December 2020. Mer information om den nya Az-modulen och AzureRM-kompatibilitet finns i Introduktion till den nya Azure PowerShell Az-modulen.To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. Installations anvisningar för AZ-modulen på Hybrid Runbook Worker finns i installera Azure PowerShell-modulen.For Az module installation instructions on your Hybrid Runbook Worker, see Install the Azure PowerShell Module. För ditt Automation-konto kan du uppdatera dina moduler till den senaste versionen med hjälp av hur du uppdaterar Azure PowerShell moduler i Azure Automation.For your Automation account, you can update your modules to the latest version using How to update Azure PowerShell modules in Azure Automation.

Webhook-egenskaperWebhook properties

I följande tabell beskrivs de egenskaper som du måste konfigurera för en webhook.The following table describes the properties that you must configure for a webhook.

EgenskapProperty BeskrivningDescription
NamnName Webhookens namn.Name of the webhook. Du kan ange vilket namn du vill, eftersom det inte visas för klienten.You can provide any name you want, since it isn't exposed to the client. Den används bara för att identifiera runbooken i Azure Automation.It's only used for you to identify the runbook in Azure Automation. Vi rekommenderar att du ger webhooken ett namn som är relaterat till klienten som använder den.As a best practice, you should give the webhook a name related to the client that uses it.
URLURL Webhookens URL.URL of the webhook. Detta är den unika adress som en klient anropar med ett HTTP-inlägg för att starta den Runbook som är länkad till webhooken.This is the unique address that a client calls with an HTTP POST to start the runbook linked to the webhook. Den skapas automatiskt när du skapar webhooken.It's automatically generated when you create the webhook. Du kan inte ange en anpassad URL.You can't specify a custom URL.

URL: en innehåller en säkerhetstoken som gör det möjligt för ett system från tredje part att anropa runbooken utan ytterligare autentisering.The URL contains a security token that allows a third-party system to invoke the runbook with no further authentication. Därför bör du behandla URL: en som ett lösen ord.For this reason, you should treat the URL like a password. Av säkerhets skäl kan du bara Visa webb adressen i Azure Portal när du skapar webhooken.For security reasons, you can only view the URL in the Azure portal when creating the webhook. Notera URL: en på en säker plats för framtida användning.Note the URL in a secure location for future use.
FörfallodatumExpiration date Utgångs datum för webhooken, efter vilken den inte längre kan användas.Expiration date of the webhook, after which it can no longer be used. Du kan ändra utgångs datumet efter att webhooken har skapats, så länge webhooken inte har upphört att gälla.You can modify the expiration date after the webhook is created, as long as the webhook has not expired.
EnabledEnabled Anger om webhooken är aktive rad som standard när den skapas.Setting indicating if the webhook is enabled by default when it's created. Om du ställer in den här egenskapen på inaktive rad kan inte klienten använda webhooken.If you set this property to Disabled, no client can use the webhook. Du kan ange den här egenskapen när du skapar webhooken eller någon annan gång när den har skapats.You can set this property when you create the webhook or any other time after its creation.

Parametrar som används när webhooken startar en RunbookParameters used when the webhook starts a runbook

En webhook kan definiera värden för Runbook-parametrar som används när Runbook startas.A webhook can define values for runbook parameters that are used when the runbook starts. Webhooken måste innehålla värden för alla obligatoriska Runbook-parametrar och kan innehålla värden för valfria parametrar.The webhook must include values for any mandatory runbook parameters and can include values for optional parameters. Ett parameter värde som har kon figurer ATS för en webhook kan ändras även när webhook har skapats.A parameter value configured to a webhook can be modified even after webhook creation. Flera webhook-länkar till en enda Runbook kan båda använda olika värden för Runbook-parametrar.Multiple webhooks linked to a single runbook can each use different runbook parameter values. När en klient startar en Runbook med en webhook kan den inte åsidosätta de parameter värden som definierats i webhooken.When a client starts a runbook using a webhook, it can't override the parameter values defined in the webhook.

För att ta emot data från klienten stöder runbooken en enda parameter med namnet WebhookData.To receive data from the client, the runbook supports a single parameter called WebhookData. Den här parametern definierar ett objekt som innehåller data som klienten inkluderar i en POST-begäran.This parameter defines an object containing data that the client includes in a POST request.

Egenskaper för WebhookData

Parametern WebhookData har följande egenskaper:The WebhookData parameter has the following properties:

EgenskapProperty BeskrivningDescription
WebhookName Webhookens namn.Name of the webhook.
RequestHeader Hash-tabellen som innehåller rubrikerna för inkommande POST-begäran.Hashtable containing the headers of the incoming POST request.
RequestBody Brödtext i inkommande POST-begäran.Body of the incoming POST request. Den här texten behåller all dataformatering, till exempel String, JSON, XML eller form-kodad.This body retains any data formatting, such as string, JSON, XML, or form-encoded. Runbooken måste skrivas för att fungera med det data format som förväntas.The runbook must be written to work with the data format that is expected.

Det krävs ingen konfiguration av webhook för att stödja WebhookData-parametern och det krävs ingen Runbook för att acceptera den.There's no configuration of the webhook required to support the WebhookData parameter, and the runbook isn't required to accept it. Om runbooken inte definierar parametern ignoreras all information om begäran som skickas från klienten.If the runbook doesn't define the parameter, any details of the request sent from the client are ignored.

Anteckning

När du anropar en webhook bör klienten alltid lagra alla parameter värden, om anropet Miss lyckas.When calling a webhook, the client should always store any parameter values in case the call fails. Om det uppstår ett nätverks avbrott eller anslutnings problem kan programmet inte hämta misslyckade webhook-anrop.If there is a network outage or connection issue, the application can't retrieve failed webhook calls.

Om du anger ett värde för WebhookData vid skapande av webhook, åsidosätts det när webhooken startar runbooken med data från klient POST förfrågan.If you specify a value for WebhookData at webhook creation, it is overridden when the webhook starts the runbook with the data from the client POST request. Detta inträffar även om programmet inte innehåller några data i begär ande texten.This happens even if the application does not include any data in the request body.

Om du startar en Runbook som definierar WebhookData använder en annan mekanism än en webhook, kan du ange ett värde för WebhookData som Runbook känner igen.If you start a runbook that defines WebhookData using a mechanism other than a webhook, you can provide a value for WebhookData that the runbook recognizes. Det här värdet ska vara ett objekt med samma Egenskaper som parametern WebhookData så att runbooken kan arbeta med den precis som det fungerar med faktiska WebhookData objekt som skickas av en webhook.This value should be an object with the same properties as the WebhookData parameter so that the runbook can work with it just as it works with actual WebhookData objects passed by a webhook.

Om du till exempel startar följande Runbook från Azure Portal och vill skicka några exempel på webhook-data för testning måste du skicka data i JSON i användar gränssnittet.For example, if you are starting the following runbook from the Azure portal and want to pass some sample webhook data for testing, you must pass the data in JSON in the user interface.

WebhookData-parameter från UI

I nästa Runbook-exempel definierar vi följande egenskaper för WebhookData:For the next runbook example, let's define the following properties for WebhookData:

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

Nu skickar vi följande JSON-objekt i användar gränssnittet för parametern WebhookData.Now we pass the following JSON object in the UI for the WebhookData parameter. Det här exemplet, med vagn returer och rad matnings tecken, matchar formatet som skickas från en webhook.This example, with carriage returns and newline characters, matches the format that is passed in from a 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ändar gränssnittet

Anteckning

Azure Automation loggar värdena för alla indataparametrar med Runbook-jobbet.Azure Automation logs the values of all input parameters with the runbook job. Alla indata som tillhandahålls av klienten i webhook-begäran loggas och är tillgängliga för alla som har åtkomst till Automation-jobbet.Thus any input provided by the client in the webhook request is logged and available to anyone with access to the automation job. Av den anledningen bör du vara försiktig med att inkludera känslig information i webhook-anrop.For this reason, you should be cautious about including sensitive information in webhook calls.

Webhook-säkerhetWebhook security

Säkerheten för en webhook är beroende av sekretessen för dess URL, som innehåller en säkerhetstoken som gör att webhooken kan anropas.The security of a webhook relies on the privacy of its URL, which contains a security token that allows the webhook to be invoked. Azure Automation utför ingen autentisering för en begäran så länge den har gjorts till rätt URL.Azure Automation does not perform any authentication on a request as long as it is made to the correct URL. Därför bör dina klienter inte använda Webhooks för Runbooks som utför mycket känsliga åtgärder utan att använda alternativa metoder för att verifiera begäran.For this reason, your clients should not use webhooks for runbooks that perform highly sensitive operations without using an alternate means of validating the request.

Du kan inkludera logik i en Runbook för att avgöra om den anropas av en webhook.You can include logic within a runbook to determine if it is called by a webhook. Låt runbooken kontrol lera egenskapen WebhookName för parametern WebhookData.Have the runbook check the WebhookName property of the WebhookData parameter. Runbooken kan utföra ytterligare verifiering genom att söka efter viss information i RequestHeader och RequestBody egenskaper.The runbook can perform further validation by looking for particular information in the RequestHeader and RequestBody properties.

En annan strategi är att låta Runbook utföra en del validering av ett externt villkor när den får en webhook-begäran.Another strategy is to have the runbook perform some validation of an external condition when it receives a webhook request. Anta till exempel att en Runbook som anropas av GitHub när som helst är en ny incheckning av en GitHub-lagringsplats.For example, consider a runbook that is called by GitHub any time there's a new commit to a GitHub repository. Runbooken kan ansluta till GitHub för att kontrol lera att ett nytt genomförande har skett innan du fortsätter.The runbook might connect to GitHub to validate that a new commit has occurred before continuing.

Skapa en webhookCreating a webhook

Använd följande procedur för att skapa en ny webhook som är länkad till en Runbook i Azure Portal.Use the following procedure to create a new webhook linked to a runbook in the Azure portal.

  1. På sidan Runbooks i Azure Portal klickar du på den Runbook som webhooken startar för att Visa Runbook-informationen.From the Runbooks page in the Azure portal, click the runbook that the webhook starts to view the runbook details. Se till att fältet Runbook- status är inställt på publicerat.Ensure that the runbook Status field is set to Published.

  2. Klicka på webhook överst på sidan för att öppna sidan Lägg till webhook.Click Webhook at the top of the page to open the Add Webhook page.

  3. Klicka på Skapa ny webhook för att öppna sidan Skapa webhook.Click Create new webhook to open the Create Webhook page.

  4. Fyll i fälten namn och förfallo datum för webhooken och ange om den ska vara aktive rad.Fill in the Name and Expiration Date fields for the webhook and specify if it should be enabled. Se webhook-egenskaper för mer information om dessa egenskaper.See Webhook properties for more information about these properties.

  5. Klicka på Kopiera-ikonen och tryck på CTRL + C för att kopiera URL: en för webhooken.Click the copy icon and press Ctrl+C to copy the URL of the webhook. Registrera den på ett säkert ställe.Then record it in a safe place.

    Anteckning

    När du skapar webhooken kan du inte hämta URL: en igen.Once you create the webhook, you cannot retrieve the URL again.

    Webhook-URL

  6. Klicka på parametrar för att ange värden för Runbook-parametrarna.Click Parameters to provide values for the runbook parameters. Om runbooken har obligatoriska parametrar kan du inte skapa webhooken om du inte anger värden.If the runbook has mandatory parameters, you can't create the webhook unless you provide values.

  7. Skapa webhooken genom att klicka på Skapa.Click Create to create the webhook.

Använda en webhookUsing a webhook

Om du vill använda en webhook när den har skapats måste klienten utfärda en HTTP POST-begäran med URL: en för webhooken.To use a webhook after it has been created, your client must issue an HTTP POST request with the URL for the webhook. Syntax:The syntax is:

http://<Webhook Server>/token?=<Token Value>

Klienten får en av följande retur koder från POST begäran.The client receives one of the following return codes from the POST request.

KodCode TextText BeskrivningDescription
202202 AcceptedAccepted Begäran accepterades och Runbook har placerats i kö.The request was accepted, and the runbook was successfully queued.
400400 Felaktig förfråganBad Request Begäran godtogs inte av någon av följande orsaker:The request was not accepted for one of the following reasons:
  • Webhooken har upphört att gälla.The webhook has expired.
  • Webhooken är inaktive rad.The webhook is disabled.
  • Token i URL: en är ogiltig.The token in the URL is invalid.
404404 Hittades inteNot Found Begäran godtogs inte av någon av följande orsaker:The request was not accepted for one of the following reasons:
  • Det gick inte att hitta webhooken.The webhook was not found.
  • Det gick inte att hitta Runbook-flödet.The runbook was not found.
  • Det gick inte att hitta kontot.The account was not found.
500500 Internt Server felInternal Server Error URL: en var giltig, men ett fel uppstod.The URL was valid, but an error occurred. Skicka begäran igen.Please resubmit the request.

Förutsatt att begäran lyckas innehåller webhook-svaret jobb-ID i JSON-format som visas nedan.Assuming the request is successful, the webhook response contains the job ID in JSON format as shown below. Den innehåller ett enda jobb-ID, men JSON-formatet möjliggör framtida framtida förbättringar.It contains a single job ID, but the JSON format allows for potential future enhancements.

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

Klienten kan inte avgöra när Runbook-jobbet har slutförts eller om dess slut för ande status från webhooken är slutförd.The client can't determine when the runbook job completes or its completion status from the webhook. Den här informationen kan ta reda på den här informationen med jobb-ID: t med en annan mekanism, till exempel Windows PowerShell eller Azure Automation-API.It can find out this information using the job ID with another mechanism, such as Windows PowerShell or the Azure Automation API.

Förnyar en webhookRenewing a webhook

När en webhook skapas, har den en giltighets tid på tio år, efter vilken den upphör att gälla automatiskt.When a webhook is created, it has a validity time period of ten years, after which it automatically expires. När en webhook har gått ut kan du inte återaktivera den.Once a webhook has expired, you can't reactivate it. Du kan bara ta bort och sedan återskapa den.You can only remove and then recreate it.

Du kan utöka en webhook som inte har nått sin förfallo tid.You can extend a webhook that has not reached its expiration time. Så här utökar du en webhook:To extend a webhook:

  1. Navigera till den Runbook som innehåller webhooken.Navigate to the runbook that contains the webhook.
  2. Välj Webhooks under resurser.Select Webhooks under Resources.
  3. Klicka på den webhook som du vill utöka.Click the webhook that you want to extend.
  4. På sidan webhook väljer du ett nytt förfallo datum och tid och klickar på Spara.In the Webhook page, choose a new expiration date and time and click Save.

Exempel-RunbookSample runbook

Följande exempel-Runbook accepterar webhook-data och startar de virtuella datorer som anges i begär ande texten.The following sample runbook accepts the webhook data and starts the virtual machines specified in the request body. Om du vill testa denna Runbook klickar du på skapa en Runbooki Automation-kontot under Runbooks.To test this runbook, in your Automation account under Runbooks, click Create a runbook. Om du inte vet hur du skapar en Runbook, se skapa en Runbook.If you don't know how to create a runbook, see Creating a runbook.

Anteckning

För icke-grafiska PowerShell-Runbooks är Add-AzAccount och Add-AzureRMAccount alias för Connect-AzAccount.For non-graphical PowerShell runbooks, Add-AzAccount and Add-AzureRMAccount are aliases for Connect-AzAccount. Du kan använda dessa cmdletar, eller så kan du Uppdatera dina moduler i ditt Automation-konto till de senaste versionerna.You can use these cmdlets or you can update your modules in your Automation account to the latest versions. Du kan behöva uppdatera dina moduler även om du precis har skapat ett nytt Automation-konto.You might need to update your modules even if you have just created a new Automation account.

param
(
    [Parameter (Mandatory = $false)]
    [object] $WebhookData
)

# If runbook was called from Webhook, WebhookData will not be null.
if ($WebhookData) {

    # Check header for message to validate request
    if ($WebhookData.RequestHeader.message -eq 'StartedbyContoso')
    {
        Write-Output "Header has required information"}
    else
    {
        Write-Output "Header missing required information";
        exit;
    }

    # Retrieve VMs from Webhook request body
    $vms = (ConvertFrom-Json -InputObject $WebhookData.RequestBody)

    # Authenticate to Azure by using the service principal and certificate. Then, set the subscription.

    Write-Output "Authenticating to Azure with service principal and certificate"
    $ConnectionAssetName = "AzureRunAsConnection"
    Write-Output "Get connection asset: $ConnectionAssetName"

    $Conn = Get-AutomationConnection -Name $ConnectionAssetName
            if ($Conn -eq $null)
            {
                throw "Could not retrieve connection asset: $ConnectionAssetName. Check that this asset exists in the Automation account."
            }
            Write-Output "Authenticating to Azure with service principal."
            Add-AzAccount -ServicePrincipal -Tenant $Conn.TenantID -ApplicationId $Conn.ApplicationID -CertificateThumbprint $Conn.CertificateThumbprint | Write-Output

        # Start each virtual machine
        foreach ($vm in $vms)
        {
            $vmName = $vm.Name
            Write-Output "Starting $vmName"
            Start-AzVM -Name $vm.Name -ResourceGroup $vm.ResourceGroup
        }
}
else {
    # Error
    write-Error "This runbook is meant to be started from an Azure alert webhook only."
}

Testa exempletTesting the sample

I följande exempel används Windows PowerShell för att starta en Runbook med en webhook.The following example uses Windows PowerShell to start a runbook with a webhook. Alla språk som kan göra en HTTP-begäran kan använda en webhook.Any language that can make an HTTP request can use a webhook. Windows PowerShell används här som ett exempel.Windows PowerShell is used here as an example.

Runbooken förväntar sig en lista över virtuella datorer som är formaterade i JSON i bröd texten i begäran.The runbook is expecting a list of virtual machines formatted in JSON in the body of the request. Runbooken validerar även att huvuden innehåller ett definierat meddelande för att verifiera att webhook-anroparen är giltig.The runbook validates as well that the headers contain a defined message to validate that the webhook caller is valid.

$uri = "<webHook Uri>"

$vms  = @(
            @{ Name="vm01";ResourceGroup="vm01"},
            @{ Name="vm02";ResourceGroup="vm02"}
        )
$body = ConvertTo-Json -InputObject $vms
$header = @{ message="StartedbyContoso"}
$response = Invoke-WebRequest -Method Post -Uri $uri -Body $body -Headers $header
$jobid = (ConvertFrom-Json ($response.Content)).jobids[0]

I följande exempel visas bröd texten i begäran som är tillgänglig för runbooken i egenskapen RequestBody för WebhookData.The following example shows the body of the request that is available to the runbook in the RequestBody property of WebhookData. Det här värdet är formaterat i JSON för att vara kompatibelt med det format som finns i bröd texten i begäran.This value is formatted in JSON to be compatible with the format included in the body of the request.

[
    {
        "Name":  "vm01",
        "ResourceGroup":  "myResourceGroup"
    },
    {
        "Name":  "vm02",
        "ResourceGroup":  "myResourceGroup"
    }
]

Följande bild visar den begäran som skickas från Windows PowerShell och det resulterande svaret.The following image shows the request being sent from Windows PowerShell and the resulting response. Jobb-ID: t extraheras från svaret och konverteras till en sträng.The job ID is extracted from the response and converted to a string.

Webhooks-knapp

Nästa stegNext steps