Börja använda en Azure Automation-runbook med en webhookStarting an Azure Automation runbook with a webhook

En webhook gör att du kan starta en viss runbook i Azure Automation via en HTTP-begäran.A webhook allows you to start a particular runbook in Azure Automation through a single HTTP request. Detta gör att externa tjänster som Visual Studio Team Services, GitHub, Azure Log Analytics eller anpassade program att starta runbooks utan att implementera en komplett lösning med hjälp av Azure Automation-API.This allows external services such as Visual Studio Team Services, GitHub, Azure Log Analytics, or custom applications to start runbooks without implementing a full solution using the Azure Automation API.
WebhooksOverviewWebhooksOverview

Du kan jämföra webhooks för att andra metoder för att starta en runbook starta en runbook i Azure AutomationYou can compare webhooks to other methods of starting a runbook in Starting a runbook in Azure Automation

Information om en webhookDetails of a webhook

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.

Egenskap Property BeskrivningDescription
NamnName Du kan ange ett namn som du vill använda för en webhook eftersom detta inte är exponerad klienten.You can provide any name you want for a webhook since this is not exposed to the client. Den används endast för dig för att identifiera runbook i Azure Automation.It is only used for you to identify the runbook in Azure Automation.
Som bästa praxis bör du ge webhooken ett namn som är relaterade till den klient som använder den.As a best practice, you should give the webhook a name related to the client that uses it.
URLURL URL: en för webhooken är den unika adress som en klient anropar med en HTTP POST att starta runbooken länkad till webhooken.The URL of the webhook is the unique address that a client calls with an HTTP POST to start the runbook linked to the webhook. Det genereras automatiskt när du skapar webhooken.It is automatically generated when you create the webhook. Du kan inte ange en anpassad URL.You cannot specify a custom URL.

URL: en innehåller en säkerhetstoken som gör att runbook anropas av en tredjeparts-system utan ytterligare autentisering.The URL contains a security token that allows the runbook to be invoked by a third-party system with no further authentication. Den ska därför behandlas som ett lösenord.For this reason, it should be treated like a password. Av säkerhetsskäl kan du bara se URL: en i Azure-portalen när webhooken skapas.For security reasons, you can only view the URL in the Azure portal at the time the webhook is created. Observera att URL: en på en säker plats för framtida användning.Note the URL in a secure location for future use.
UpphörandedatumExpiration date Varje webhook om du har ett förfallodatum vid vilken tidpunkt den kan inte längre användas som ett certifikat.Like a certificate, each webhook has an expiration date at which time it can no longer be used. Den här förfallodatum kan ändras när webhooken skapas.This expiration date can be modified after the webhook is created.
EnabledEnabled En webhook aktiveras som standard när den skapas.A webhook is enabled by default when it is created. Om du ställer in det på inaktiverad är ingen klient kan använda den.If you set it to Disabled, then no client is able to use it. Du kan ange den aktiverad egenskapen när du skapar webhooken eller när som helst när den har skapats.You can set the Enabled property when you create the webhook or anytime once it is created.

ParametrarParameters

En webhook kan definiera värden för runbookparametrar som används när runbook startas av den webhooken.A webhook can define values for runbook parameters that are used when the runbook is started by that webhook. Webhooken måste innehålla värden för alla obligatoriska parametrar för runbook och kan innehålla värden för valfria parametrar.The webhook must include values for any mandatory parameters of the runbook and may include values for optional parameters. Ett parametervärde som konfigurerats för att en webhook kan ändras även när du har skapat webhooken.A parameter value configured to a webhook can be modified even after creating the webhook. Flera webhooks som är länkad till en enda runbook kan använda olika parametervärden.Multiple webhooks linked to a single runbook can each use different parameter values.

När en klient startar en runbook med en webhook, kan inte det åsidosätta de parametervärden som definierats i webhooken.When a client starts a runbook using a webhook, it cannot override the parameter values defined in the webhook. Om du vill ta emot data från klienten, runbook kan acceptera en enda parameter med namnet $WebhookData av typen [objekt] som innehåller data som klienten lägger till i POST-begäran.To receive data from the client, the runbook can accept a single parameter called $WebhookData of type [object] that contains data that the client includes in the POST request.

Webhookdata-egenskaper

Den $WebhookData objekt har följande egenskaper:The $WebhookData object has the following properties:

Egenskap Property BeskrivningDescription
WebhookNameWebhookName Namnet på webhooken.The name of the webhook.
RequestHeaderRequestHeader Hash-tabell som innehåller huvuden inkommande POST-begäran.Hash table containing the headers of the incoming POST request.
RequestBodyRequestBody Innehållet i den inkommande POST-begäran.The body of the incoming POST request. Detta bevarar all formatering, till exempel sträng, JSON, XML, eller formuläret kodade data.This retains any formatting such as string, JSON, XML, or form encoded data. Runbooken måste vara skrivna för att arbeta med dataformat som förväntas.The runbook must be written to work with the data format that is expected.

Ingen konfiguration krävs för att stödja webhookens den $WebhookData parameter och en runbook inte krävs för att acceptera den.There is no configuration of the webhook required to support the $WebhookData parameter, and the runbook is not required to accept it. Om runbook inte definierar parametern ignoreras någon information om begäran som skickats från klienten.If the runbook does not define the parameter, then any details of the request sent from the client is ignored.

Om du anger ett värde för $WebhookData när du skapar webhooken, att värde åsidosätts när webhooken startar runbook med data från klienten POST-begäran, även om klienten inte innehåller några data i begärandetexten.If you specify a value for $WebhookData when you create the webhook, that value is overridden when the webhook starts the runbook with the data from the client POST request, even if the client does not include any data in the request body. Om du startar en runbook som har $WebhookData med hjälp av en annan metod än en webhook, kan du ange ett värde för $Webhookdata som känns igen av runbook.If you start a runbook that has $WebhookData using a method other than a webhook, you can provide a value for $Webhookdata that is recognized by the runbook. Det här värdet ska vara ett objekt med samma egenskaper som $Webhookdata så att runbooken fungerar korrekt med det som om den fungerade med faktiska WebhookData som skickas av en webhook.This value should be an object with the same properties as $Webhookdata so that the runbook can properly work with it as if it was working with actual WebhookData passed by a webhook.

Till exempel om du startar följande runbook från Azure-portalen och vill skicka vissa exempel WebhookData för testning, eftersom WebhookData är ett objekt som ska den skickas som JSON i Användargränssnittet.For example, if you are starting the following runbook from the Azure portal and want to pass some sample WebhookData for testing, since WebhookData is an object, it should be passed as JSON in the UI.

WebhookData-parametern från Användargränssnittet

På följande runbook, om du har följande egenskaper för WebhookData-parametern:For the following runbook, if you have the following properties for the WebhookData parameter:

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

Sedan skickar du följande JSON-värde i Användargränssnittet för WebhookData-parametern.Then you would pass the following JSON value in the UI for the WebhookData parameter. I följande exempel med transport returneras och radmatningstecken matchar formatet som skickas från en webhook.The following example with the 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ändargränssnittet

Anteckning

Värdena för alla indataparametrar loggas med runbook-jobbet.The values of all input parameters are logged with the runbook job. Detta innebär att alla indata av klienten i webhook-begäran kommer loggas som är tillgänglig för alla med åtkomst till automation-jobb.This means that any input provided by the client in the webhook request will be logged and available to anyone with access to the automation job. Därför bör du vara försiktig inklusive känslig information i webhook-anrop.For this reason, you should be cautious about including sensitive information in webhook calls.

SäkerhetSecurity

Säkerheten för en webhook som förlitar sig på sekretessen för dess URL som innehåller en säkerhetstoken som gör att det kan anropas.The security of a webhook relies on the privacy of its URL, which contains a security token that allows it to be invoked. Azure Automation utför inte någon autentisering på begäran så länge som det görs till rätt URL.Azure Automation does not perform any authentication on the request as long as it is made to the correct URL. Därför bör webhooks inte användas för runbooks som utför mycket känsliga funktioner utan att använda ett annat sätt att verifiera begäran.For this reason, webhooks should not be used for runbooks that perform highly sensitive functions without using an alternate means of validating the request.

Du kan inkludera logik i din runbook för att fastställa att anropet av en webhook genom att markera den WebhookName egenskapen för parametern $WebhookData.You can include logic within the runbook to determine that it was called by a webhook by checking the WebhookName property of the $WebhookData parameter. Runbook kan utföra ytterligare verifiering genom att söka efter specifika informationen i den RequestHeader eller RequestBody egenskaper.The runbook could perform further validation by looking for particular information in the RequestHeader or RequestBody properties.

En annan strategi är att ha en runbook som utför vissa verifiering av en extern villkor när en webhook-begäran togs emot.Another strategy is to have the runbook perform some validation of an external condition when it received a webhook request. Anta exempelvis att en runbook som anropas av GitHub när det finns en ny allokering till en GitHub-lagringsplats.For example, consider a runbook that is called by GitHub whenever there is a new commit to a GitHub repository. Runbook kan ansluta till GitHub för att verifiera att en ny allokering inträffat innan du fortsätter.The runbook might connect to GitHub to validate that a new commit had occurred before continuing.

Skapa en webhookCreating a webhook

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

  1. Från den Runbooks sidan i Azure-portalen klickar du på den runbook som webhooken börjar att visa dess detaljsida.From the Runbooks page in the Azure portal, click the runbook that the webhook starts to view its detail page. Se till att runbook Status är publicerad.Ensure the runbook Status is Published.
  2. Klicka på Webhook överst på sidan för att öppna den Lägg till Webhook sidan.Click Webhook at the top of the page to open the Add Webhook page.
  3. Klicka på Skapa ny webhook att öppna den skapa webhook sidan.Click Create new webhook to open the Create webhook page.
  4. Ange en namn, förfallodatum för webhooken och om den ska aktiveras.Specify a Name, Expiration Date for the webhook and whether it should be enabled. Se information om en webhook mer dessa egenskaper.See Details of a webhook for more information these properties.
  5. Klicka på kopieringsikonen för och tryck på Ctrl + C för att kopiera Webbadressen till webhooken.Click the copy icon and press Ctrl+C to copy the URL of the webhook. Registrera den på en säker plats.Then record it in a safe place. När du skapar webhooken kan inte kan du hämta URL: en igen.Once you create the webhook, you cannot retrieve the URL again.

    Webhook-URL

  6. Klicka på parametrar att ange värden för runbook-parametrar.Click Parameters to provide values for the runbook parameters. Om runbooken har obligatoriska parametrar, är du inte kunna skapa webhooken om inte värden anges.If the runbook has mandatory parameters, then you are not able to create the webhook unless values are provided.

  7. Klicka på skapa du skapar webhooken.Click Create to create the webhook.

Med en webhookUsing a webhook

Om du vill använda en webhook när den har skapats, måste klientprogrammet utfärda en HTTP POST med URL-Adressen för webhooken.To use a webhook after it has been created, your client application must issue an HTTP POST with the URL for the webhook. Syntaxen för webhooken har följande format:The syntax of the webhook is in the following format:

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

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

KodCode TextText BeskrivningDescription
202202 AccepteradAccepted Begäran accepterades och runbook har i kö.The request was accepted, and the runbook was successfully queued.
400400 Felaktig förfråganBad Request Begäran godkändes inte av något av följande skäl:The request was not accepted for one of the following reasons:
  • Webhooken har gått ut.The webhook has expired.
  • Webhooken har inaktiverats.The webhook is disabled.
  • Token i URL: en är ogiltig.The token in the URL is invalid.
404404 Kunde inte hittasNot Found Begäran godkändes inte av något av följande skäl:The request was not accepted for one of the following reasons:
  • Webhook hittades inte.The webhook was not found.
  • Runbook hittades inte.The runbook was not found.
  • Kontot hittades inte.The account was not found.
500500 Internt serverfelInternal Server Error URL: en är 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 har lyckats, webhook svaret innehåller jobb-id i JSON-format på följande sätt.Assuming the request is successful, the webhook response contains the job id in JSON format as follows. Det innehåller ett enskilt jobb-id, men JSON-format som tillåter för eventuella framtida förbättringar.It will contain a single job id, but the JSON format allows for potential future enhancements.

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

Klienten kan inte fastställa när runbook-jobbet har slutförts eller deras slutförandestatus från webhooken.The client cannot determine when the runbook job completes or its completion status from the webhook. Det kan ta reda på den här informationen med jobb-id med en annan metod som Windows PowerShell eller Azure Automation API.It can determine this information using the job id with another method such as Windows PowerShell or the Azure Automation API.

Exempel-runbookSample runbook

Följande exempel-runbook som accepterar den accepterar webhookdata och startar de virtuella datorerna som anges i begärandetexten.The following sample runbook accepts the accepts webhook data and starts the virtual machines specified in the request body. Testa denna runbook i ditt Automation-konto under Runbooks, klickar du på + Lägg till en runbook.To test this runbook, in your Automation Account under Runbooks, click + Add a runbook. Om du inte vet hur du skapar en runbook, se skapa en runbook.If you do not know how to create a runbook, see Creating a runbook.

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

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

    # Retrieve VM's 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-AzureRmAccount -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-AzureRMVM -Name $vm.Name -ResourceGroup $vm.ResourceGroup
        }
}
else {
    # Error
    write-Error "This runbook is meant to be started from an Azure alert webhook only."
}

Testa exempletTest the example

I följande exempel använder 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 skicka en HTTP-begäran kan använda en webhook; Windows PowerShell används här som ett exempel.Any language that can make an HTTP request can use a webhook; Windows PowerShell is used here as an example.

Runbook förväntar sig en lista över virtuella datorer som har formaterats i JSON i brödtexten i begäran.The runbook is expecting a list of virtual machines formatted in JSON in the body of the request.

$uri = "<webHook Uri>"

$vms  = @(
            @{ Name="vm01";ResourceGroup="vm01"},
            @{ Name="vm02";ResourceGroup="vm02"}
        )
$body = ConvertTo-Json -InputObject $vms

$response = Invoke-RestMethod -Method Post -Uri $uri -Body $body
$jobid = (ConvertFrom-Json ($response.Content)).jobids[0]

I följande exempel visas brödtexten i begäran som är tillgänglig för runbooken i den RequestBody egenskapen för WebhookData.The following example shows the body of the request that is available to the runbook in the RequestBody property of WebhookData. Detta formateras som JSON eftersom det var det format som ingick i brödtexten i begäran.This is formatted as JSON because that was the format that was 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 är extraheras från svaret och konverteras till en sträng.The job id is extracted from the response and converted to a string.

Webhooks-knappen

Nästa stegNext steps