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

Med en webhook kan du starta en viss runbook i Azure Automation via en enda 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 Azure DevOps Services, GitHub, Azure Monitor loggar eller anpassade program kan starta Runbooks utan att implementera en fullständig lösning med hjälp av Azure Automation API.This allows external services such as Azure DevOps Services, GitHub, Azure Monitor logs, or custom applications to start runbooks without implementing a full solution using the Azure Automation API. WebhooksOverviewWebhooksOverview

Du kan jämföra Webhooks med andra metoder för att starta en runbook när du startar en Runbook i Azure AutomationYou 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.

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.

EgenskapProperty DescriptionDescription
NameName Du kan ange vilket namn du vill för en webhook eftersom det inte visas för klienten.You can provide any name you want for a webhook since this 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 URL: en för webhook ä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.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. 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 att runbooken kan anropas av ett system från tredje part 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. Av den anledningen bör det behandlas som ett lösen ord.For this reason, it should be treated like a password. Av säkerhets skäl kan du bara Visa webb adressen i Azure Portal när webhooken skapas.For security reasons, you can only view the URL in the Azure portal at the time the webhook is created. Notera 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 Precis som ett certifikat har varje webhook ett förfallo datum då den inte längre kan användas.Like a certificate, each webhook has an expiration date at which time it can no longer be used. Detta förfallo datum kan ändras efter att webhooken har skapats så länge webhooken inte har upphört att gälla.This expiration date can be modified after the webhook is created as long as the webhook isn't expired.
AktiveradEnabled En webhook är aktive rad som standard när den skapas.A webhook is enabled by default when it's created. Om du ställer in den på inaktive rad kan ingen klient använda den.If you set it to Disabled, then no client can use it. Du kan ställa in egenskapen Enabled när du skapar webhooken eller när den skapas.You can set the Enabled property when you create the webhook or anytime once it's created.

ParametrarParameters

En webhook kan definiera värden för Runbook-parametrar som används när Runbook startas av 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 runbooken 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 parameter värde som har kon figurer ATS för en webhook kan ändras även när webhooken har skapats.A parameter value configured to a webhook can be modified even after creating the webhook. Flera webhook-länkar till en enda Runbook kan var och en använda olika parameter vä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 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 kan runbooken acceptera en enda parameter med namnet $WebhookData.To receive data from the client, the runbook can accept a single parameter called $WebhookData. Den här parametern är av en typ [Object] som innehåller data som klienten inkluderar i POST-begäran.This parameter is of a type [object] that contains data that the client includes in the POST request.

Egenskaper för Webhookdata

$WebhookData -objektet har följande egenskaper:The $WebhookData object has the following properties:

EgenskapProperty BeskrivningDescription
WebhookNameWebhookName Namnet på webhooken.The name of the webhook.
RequestHeaderRequestHeader Hash-tabell som innehåller rubrikerna för inkommande POST-begäran.Hash table containing the headers of the incoming POST request.
RequestBodyRequestBody Bröd texten i begäran om inkommande POST.The body of the incoming POST request. Detta behåller all formatering, till exempel sträng-, JSON-, XML-eller form-kodade data.This retains any formatting such as string, JSON, XML, or form encoded data. 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, then any details of the request sent from the client is ignored.

Anteckning

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

Om du anger ett värde för $WebhookData när du skapar webhooken, åsidosätts värdet när webhooken startar runbooken med data från klient POST förfrågan, även om klienten inte innehåller några data i begär ande texten.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 en annan metod än en webhook kan du ange ett värde för $Webhookdata som identifieras av runbooken.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. Värdet ska vara ett objekt med samma Egenskaper som $Webhookdata så att runbooken fungerar korrekt med det som om det fungerade med faktiska Webhookdata som skickats 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.

Om du till exempel startar följande Runbook från Azure Portal och vill skicka några exempel-WebhookData för testning, eftersom WebhookData är ett objekt, ska det skickas som 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 WebhookData for testing, since WebhookData is an object, it should be passed as JSON in the UI.

WebhookData-parameter från UI

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

  • WebhookName MyWebhookWebhookName: MyWebhook
  • RequestBody: [{' ResourceGroup ': ' myResourceGroup ', ' name ': ' VM01 '}, {' ResourceGroup ': ' myResourceGroup ', ' namn ': ' VM02 '}]RequestBody: [{'ResourceGroup': 'myResourceGroup','Name': 'vm01'},{'ResourceGroup': 'myResourceGroup','Name': 'vm02'}]

Sedan skickar du följande JSON-värde i användar gränssnittet för parametern WebhookData.Then you would pass the following JSON value in the UI for the WebhookData parameter. Följande exempel med tecknen vagn returer och rad matningar 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ändar gränssnittet

Anteckning

Värdena för alla indataparametrar loggas med Runbook-jobbet.The values of all input parameters are logged with the runbook job. Det innebär att 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.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. 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.

SäkerhetSecurity

Säkerheten för en webhook är beroende av sekretessen för dess URL, som innehåller en säkerhetstoken som gör att den 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 ingen autentisering på begäran så länge den har gjorts 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 alternativa metoder för 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 runbooken för att fastställa att den anropades av en webhook genom att kontrol lera egenskapen WebhookName 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. Runbooken kan utföra ytterligare verifiering genom att söka efter viss information i egenskaperna RequestHeader eller RequestBody .The runbook could perform further validation by looking for particular information in the RequestHeader or RequestBody properties.

En annan strategi är att låta Runbook utföra en del validering av ett externt villkor när den tar emot en webhook-begäran.Another strategy is to have the runbook perform some validation of an external condition when it received a webhook request. Anta till exempel en Runbook som anropas av GitHub när det finns ett nytt genomförande till en GitHub-lagringsplats.For example, consider a runbook that is called by GitHub whenever there's a new commit to a GitHub repository. Runbooken kan ansluta till GitHub för att verifiera att en ny incheckning har skett 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 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. sidan Runbooks i Azure Portal klickar du på den Runbook som webhooken börjar visa sin informations sida.From the Runbooks page in the Azure portal, click the runbook that the webhook starts to view its detail page. Se till att Runbook- statusen har publicerats.Ensure the runbook Status is 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. Ange ett namn, utgångs datum för webhooken och om det ska aktive ras.Specify a Name, Expiration Date for the webhook and whether it should be enabled. Se information om en webhook för mer information om dessa egenskaper.See Details of a webhook for more information 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. 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 inte värden anges.If the runbook has mandatory parameters, then you are not able to create the webhook unless values are provided.

  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 klient programmet utfärda ett HTTP-inlägg med URL: en 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. Webhookens syntax är i följande format:The syntax of the webhook is in the following format:

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 AccepteradAccepted Begäran accepterades och Runbook har placerats i kö.The request was accepted, and the runbook was successfully queued.
400400 Felaktig begäranBad 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 Kunde inte hittasNot 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 serverfelInternal 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 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 enda jobb-ID, men JSON-formatet möjliggör framtida 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 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 kan avgöra denna information med jobb-ID med en annan metod, till exempel Windows PowerShell eller Azure Automation-API: et.It can determine this information using the job ID with another method such as Windows PowerShell or the Azure Automation API.

Förnya en webhookRenew a webhook

När en webhook skapas har den en giltighets tid på ett år.When a webhook is created, it has a validity time of one year. Efter det året förfaller webhooken automatiskt.After that year time the webhook automatically expires. När en webhook har gått ut kan den inte återaktiveras. den måste tas bort och återskapas.Once a webhook is expired it can't be reactivated, it must be removed and recreated. Om en webhook inte har nått sin förfallo tid kan den utökas.If a webhook has not reached its expiry time, it can be extended.

Om du vill utöka en webhook navigerar du till den Runbook som innehåller webhooken.To extend a webhook, navigate to the runbook that contains the webhook. Välj Webhooks under resurser.Select Webhooks under Resources. Klicka på webhooken som du vill utöka. den här åtgärden öppnar webhook -sidan.Click the webhook that you want to extend, this action opens the Webhook page. Välj ett nytt förfallo datum och tid och klicka på Spara.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. Testa denna Runbook genom att klicka på + Lägg till en Runbooki Automation-kontot under Runbooks.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 don't 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) {

    # 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 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ä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; 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.

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 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. Värdet formateras som JSON eftersom det var det format som ingick i bröd texten i begäran.This value 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: 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