Avviare un runbook di Automazione di Azure con un webhookStarting an Azure Automation runbook with a webhook

Un webhook consente di avviare un Runbook specifico in Automazione di Azure tramite una singola richiesta HTTP.A webhook allows you to start a particular runbook in Azure Automation through a single HTTP request. In questo modo, i servizi esterni come Azure DevOps Services, GitHub, Log Analytics di Azure o le applicazioni personalizzate possono avviare i runbook senza implementare una soluzione completa usando l'API di Automazione di Azure.This allows external services such as Azure DevOps Services, GitHub, Azure Log Analytics, or custom applications to start runbooks without implementing a full solution using the Azure Automation API.
Panoramica dei webhookWebhooksOverview

È possibile confrontare i webhook con altre modalità di avvio di un Runbook nell'articolo relativo all' avvio di un Runbook in Automazione di AzureYou can compare webhooks to other methods of starting a runbook in Starting a runbook in Azure Automation

Informazioni dettagliate sui webhookDetails of a webhook

La tabella seguente descrive le proprietà che devono essere configurate per un webhook.The following table describes the properties that you must configure for a webhook.

ProprietàProperty DESCRIZIONEDescription
NOMEName È possibile specificare un nome qualsiasi per un webhook dal momento che non viene esposto al client.You can provide any name you want for a webhook since this is not exposed to the client. Viene usato solo per consentire all'utente di identificare il Runbook in Automazione di Azure.It is only used for you to identify the runbook in Azure Automation.
Come procedura consigliata è opportuno assegnare al webhook un nome correlato al client in cui verrà usato.As a best practice, you should give the webhook a name related to the client that uses it.
URLURL L'URL del webhook è l'indirizzo univoco che viene chiamato da un client con HTTP POST per avviare il Runbook collegato al webhook.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. Viene generato automaticamente al momento della creazione del webhook.It is automatically generated when you create the webhook. Non è possibile specificare un URL personalizzato.You cannot specify a custom URL.

L'URL contiene un token di sicurezza che consente al runbook di essere richiamato da un sistema di terze parti senza un'autenticazione aggiuntiva.The URL contains a security token that allows the runbook to be invoked by a third-party system with no further authentication. Per questo motivo, deve essere considerato come una password.For this reason, it should be treated like a password. Per motivi di sicurezza, è possibile visualizzare l'URL solo nel portale di Azure al momento della creazione del webhook.For security reasons, you can only view the URL in the Azure portal at the time the webhook is created. Prendere nota dell'URL e conservarlo in un luogo sicuro per usi futuri.Note the URL in a secure location for future use.
Expiration dateExpiration date Analogamente a un certificato, un webhook ha una data di scadenza oltre la quale non può più essere usato.Like a certificate, each webhook has an expiration date at which time it can no longer be used. La data di scadenza può essere modificata dopo la creazione del webhook.This expiration date can be modified after the webhook is created.
AttivatoEnabled Un webhook viene abilitato per impostazione predefinita nel momento in cui viene creato.A webhook is enabled by default when it is created. Se viene impostato sulla proprietà Disabled, nessun client sarà in grado di usarlo.If you set it to Disabled, then no client is able to use it. È possibile impostare la proprietà Enabled quando si crea il webhook o in qualsiasi momento successivo.You can set the Enabled property when you create the webhook or anytime once it is created.

ParametriParameters

Un webhook può definire valori per parametri di Runbook usati quando il Runbook viene avviato dal webhook.A webhook can define values for runbook parameters that are used when the runbook is started by that webhook. Il webhook deve includere valori per tutti i parametri obbligatori del Runbook e può includere valori per i parametri facoltativi.The webhook must include values for any mandatory parameters of the runbook and may include values for optional parameters. Un valore di parametro configurato per un webhook può essere modificato anche dopo aver creato il webhook.A parameter value configured to a webhook can be modified even after creating the webhook. Se esistono più webhook collegati a un singolo Runbook, ognuno di essi potrà usare valori di parametri diversi.Multiple webhooks linked to a single runbook can each use different parameter values.

Quando avvia un Runbook con un webhook, un client non può eseguire l'override dei valori di parametri definiti nel webhook.When a client starts a runbook using a webhook, it cannot override the parameter values defined in the webhook. Per ricevere dati dal client, il Runbook può accettare un singolo parametro denominato $WebhookData di tipo [object] che contiene i dati inclusi dal client nella richiesta POST.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.

Proprietà Webhookdata

Di seguito sono elencate le proprietà dell'oggetto $WebhookData:The $WebhookData object has the following properties:

ProprietàProperty DESCRIZIONEDescription
WebhookNameWebhookName Nome del webhook.The name of the webhook.
RequestHeaderRequestHeader Tabella hash contenente le intestazioni della richiesta POST in ingresso.Hash table containing the headers of the incoming POST request.
RequestBodyRequestBody Corpo della richiesta POST in ingresso.The body of the incoming POST request. Mantiene tutta la formattazione, ad esempio stringa, JSON, XML o dati codificati in un modulo.This retains any formatting such as string, JSON, XML, or form encoded data. Il Runbook deve essere scritto in modo che funzioni con il formato di dati previsto.The runbook must be written to work with the data format that is expected.

Non è richiesta alcuna configurazione del webhook per supportare il parametro $WebhookData e il Runbook non deve necessariamente accettarlo.There is no configuration of the webhook required to support the $WebhookData parameter, and the runbook is not required to accept it. Se il Runbook non definisce il parametro, gli eventuali dettagli della richiesta inviata dal client verranno ignorati.If the runbook does not define the parameter, then any details of the request sent from the client is ignored.

Se si specifica un valore per $WebhookData quando si crea il webhook, viene eseguito l'override di tale valore quando il webhook avvia il runbook con i dati della richiesta POST del client, anche se il client non include dati nel corpo della richiesta.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. Se si avvia un runbook con l'oggetto $WebhookData che usa un metodo diverso da un webhook, è possibile specificare un valore per $Webhookdata che verrà riconosciuto dal 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. Questo valore deve essere un oggetto con le stesse proprietà di $Webhookdata in modo che il Runbook possa usarlo correttamente come se stesse usando con il WebhookData effettivo passato da un 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.

Ad esempio, se si avvia il seguente runbook dal portale di Azure e si vuole passare alcuni WebhookData di esempio per testarli, WebhookData deve essere passato come JSON nell'interfaccia utente poiché è un oggetto.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.

Parametro WebhookData dall'interfaccia utente

Per il runbook seguente, se si hanno le seguenti proprietà per il parametro 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','Name': 'vm02'}]RequestBody: [{'ResourceGroup': 'myResourceGroup','Name': 'vm01'},{'ResourceGroup': 'myResourceGroup','Name': 'vm02'}]

Passare quindi il seguente valore JSON nell'interfaccia utente per il parametro WebhookData.Then you would pass the following JSON value in the UI for the WebhookData parameter. L'esempio seguente con i caratteri di ritorno a capo e di nuova riga corrisponde al formato passato da un 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]"}

Parametro WebhookData Start dall'interfaccia utente

Nota

I valori di tutti i parametri di input vengono registrati con il processo di Runbook.The values of all input parameters are logged with the runbook job. Qualsiasi input fornito dal client nella richiesta del webhook verrà quindi registrato e sarà disponibile per chiunque abbia accesso al processo di automazione.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. Per questo motivo è consigliabile procedere con cautela quando si includono dati sensibili nelle chiamate di webhook.For this reason, you should be cautious about including sensitive information in webhook calls.

SicurezzaSecurity

La sicurezza di un webhook si basa sulla privacy dell'URL che contiene un token di sicurezza che consente di richiamarlo.The security of a webhook relies on the privacy of its URL, which contains a security token that allows it to be invoked. Automazione di Azure non esegue alcuna autenticazione per la richiesta, purché venga inviata all'URL corretto.Azure Automation does not perform any authentication on the request as long as it is made to the correct URL. Per questo motivo, non è consigliabile usare i webhook per i Runbook che eseguono funzioni sensibili senza usare una modalità alternativa di convalida della richiesta.For this reason, webhooks should not be used for runbooks that perform highly sensitive functions without using an alternate means of validating the request.

È possibile includere nel Runbook la logica per determinare che è stato chiamato da un webhook selezionando la proprietà WebhookName del parametro $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. Il runbook può eseguire altre convalide cercando informazioni specifiche nella proprietà RequestHeader o RequestBody.The runbook could perform further validation by looking for particular information in the RequestHeader or RequestBody properties.

Un'altra strategia consiste nel fare in modo che il Runbook esegua la convalida di una condizione esterna quando riceve una richiesta da un webhook.Another strategy is to have the runbook perform some validation of an external condition when it received a webhook request. Si consideri ad esempio un Runbook chiamato da GitHub ogni volta che si verifica un nuovo commit in un repository di GitHub.For example, consider a runbook that is called by GitHub whenever there is a new commit to a GitHub repository. Il runbook può connettersi a GitHub per convalidare che sia stato eseguito un nuovo commit prima di continuare.The runbook might connect to GitHub to validate that a new commit had occurred before continuing.

Creazione di un webhookCreating a webhook

Seguire questa procedura per creare un nuovo webhook collegato a un Runbook nel portale di Azure.Use the following procedure to create a new webhook linked to a runbook in the Azure portal.

  1. Nella pagina Runbook nel portale di Azure fare clic sul runbook che verrà avviato dal webhook per visualizzare la pagina dei dettagli.From the Runbooks page in the Azure portal, click the runbook that the webhook starts to view its detail page. Verificare che lo stato del runbook sia Pubblicato.Ensure the runbook Status is Published.
  2. Fare clic su Webhook nella parte superiore della pagina per aprire la pagina Aggiungi webhook.Click Webhook at the top of the page to open the Add Webhook page.
  3. Fare clic su Creare un nuovo webhook per aprire la pagina Crea webhook.Click Create new webhook to open the Create webhook page.
  4. Specificare un valore per Nome e Data scadenza per il webhook e indicare se deve essere abilitato.Specify a Name, Expiration Date for the webhook and whether it should be enabled. Per altre informazioni su queste proprietà, vedere Informazioni dettagliate sui webhook .See Details of a webhook for more information these properties.
  5. Fare clic sull'icona di copia e premere CTRL+C per copiare l'URL del webhook.Click the copy icon and press Ctrl+C to copy the URL of the webhook. Annotarlo in un luogo sicuro.Then record it in a safe place. Dopo aver creato il webhook, non è possibile recuperare di nuovo l'URL.Once you create the webhook, you cannot retrieve the URL again.

    URL webhook

  6. Fare clic su Parameters per specificare i valori per i parametri del Runbook.Click Parameters to provide values for the runbook parameters. Se il runbook contiene parametri obbligatori, non sarà possibile creare il webhook a meno che non vengano forniti i valori.If the runbook has mandatory parameters, then you are not able to create the webhook unless values are provided.

  7. Fare clic su Create per creare il webhook.Click Create to create the webhook.

Uso di un webhookUsing a webhook

Per usare un webhook dopo averlo creato, l'applicazione client deve inviare una richiesta HTTP POST con l'URL del webhook.To use a webhook after it has been created, your client application must issue an HTTP POST with the URL for the webhook. La sintassi del webhook ha il formato seguente:The syntax of the webhook is in the following format:

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

Il client riceve uno dei codici restituiti seguenti dalla richiesta POST.The client receives one of the following return codes from the POST request.

CodiceCode TestoText DESCRIZIONEDescription
202202 AcceptedAccepted La richiesta è stata accettata e il Runbook è stato accodato.The request was accepted, and the runbook was successfully queued.
400400 Bad RequestBad Request La richiesta non è stata accettata per uno dei motivi seguenti:The request was not accepted for one of the following reasons:
  • Il webhook è scaduto.The webhook has expired.
  • Il webhook è disabilitato.The webhook is disabled.
  • Il token nell'URL non è valido.The token in the URL is invalid.
404404 Non trovatoNot Found La richiesta non è stata accettata per uno dei motivi seguenti:The request was not accepted for one of the following reasons:
  • Il webhook non è stato trovato.The webhook was not found.
  • Il runbook non è stato trovato.The runbook was not found.
  • L'account non è stato trovato.The account was not found.
500500 Internal Server ErrorInternal Server Error L'URL è valido, ma si è verificato un errore.The URL was valid, but an error occurred. Inviare di nuovo la richiesta.Please resubmit the request.

Se la richiesta ha esito positivo, la risposta del webhook conterrà l'ID processo in formato JSON come indicato di seguito.Assuming the request is successful, the webhook response contains the job ID in JSON format as follows. Conterrà un singolo ID processo, ma il formato JSON consente potenziali miglioramenti futuri.It will contain a single job ID, but the JSON format allows for potential future enhancements.

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

Il client non è in grado di determinare quando viene completato il processo del Runbook o lo stato di avanzamento dal webhook.The client cannot determine when the runbook job completes or its completion status from the webhook. Può determinare queste informazioni usando l'ID processo con un altro metodo, ad esempio Windows PowerShell o l'API di Automazione di Azure.It can determine this information using the job ID with another method such as Windows PowerShell or the Azure Automation API.

Runbook di esempioSample runbook

Il runbook di esempio seguente accetta i dati del webhook e avvia le macchine virtuali specificate nel corpo della richiesta.The following sample runbook accepts the webhook data and starts the virtual machines specified in the request body. Per testare il runbook, nell'account di Automazione in Runbook fare clic su + Aggiungi runbook.To test this runbook, in your Automation Account under Runbooks, click + Add a runbook. Se non conosce la procedura di creazione di un runbook, vedere Creare un runbook di Automazione di Azure.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."
}

Testare l'esempio.Test the example

L'esempio seguente usa Windows PowerShell per avviare un Runbook con un webhook.The following example uses Windows PowerShell to start a runbook with a webhook. Qualsiasi linguaggio in grado di creare una richiesta HTTP può usare un webhook. Windows PowerShell viene usato qui come esempio.Any language that can make an HTTP request can use a webhook; Windows PowerShell is used here as an example.

Il Runbook prevede un elenco di macchine virtuali in formato JSON nel corpo della richiesta.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]

L'esempio seguente mostra il corpo della richiesta che è disponibile per il runbook nella proprietà RequestBody di WebhookData.The following example shows the body of the request that is available to the runbook in the RequestBody property of WebhookData. Viene formattata come JSON perché questo era il formato incluso nel corpo della richiesta.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"
    }
]

L'immagine seguente mostra la richiesta inviata da Windows PowerShell e la risposta risultante.The following image shows the request being sent from Windows PowerShell and the resulting response. L'ID processo viene estratto dalla risposta e convertito in una stringa.The job ID is extracted from the response and converted to a string.

Pulsante Webhooks

Passaggi successiviNext steps