Avviare un runbook da un webhook

Un webhook consente a un servizio esterno di avviare un runbook specifico in Automazione di Azure tramite una singola richiesta HTTP. I servizi esterni includono Azure DevOps Services, GitHub, log di Monitoraggio di Azure e applicazioni personalizzate. Un servizio di questo tipo può usare un webhook per avviare un runbook senza implementare l'API di Automazione di Azure completa. È possibile confrontare i webhook con altri metodi di avvio di un runbook in Avvio di un runbook in Automazione di Azure.

Nota

L'uso di un webhook per avviare un runbook Python non è supportato.

Panoramica dei webhook

Per comprendere i requisiti client per TLS 1.2 con webhook, vedere TLS 1.2 per Automazione di Azure.

Proprietà dei webhook

La tabella seguente descrive le proprietà che devono essere configurate per un webhook.

Proprietà Descrizione
Nome Nome del webhook. È possibile specificare un nome qualsiasi, dal momento che non è esposto al client. Il nome viene usato solo per consentire all'utente di identificare il runbook in Automazione di Azure. Come procedura consigliata è opportuno assegnare al webhook un nome correlato al client in cui verrà usato.
URL URL del webhook. Si tratta dell'indirizzo univoco che viene chiamato da un client con HTTP POST per avviare il runbook collegato al webhook. Viene generato automaticamente al momento della creazione del webhook. Non è possibile specificare un URL personalizzato.

L'URL contiene un token di sicurezza che consente a un sistema di terze parti di chiamare il runbook senza alcuna autenticazione aggiuntiva. Per questo motivo, è consigliabile considerare l'URL come una password. Per motivi di sicurezza, è possibile visualizzare l'URL nel portale di Azure solo quando si crea il webhook. Prendere nota dell'URL e conservarlo in un luogo sicuro per usi futuri.
Expiration date Data di scadenza del webhook, dopo la quale non può più essere usato. È possibile modificare la data di scadenza dopo la creazione del webhook, purché il webhook non sia scaduto.
Attivato Impostazione che indica se il webhook è abilitato per impostazione predefinita quando viene creato. Se si imposta questa proprietà su Disattivato, nessun client può usare il webhook. È possibile impostare questa proprietà quando si crea il webhook o in qualsiasi altro momento dopo la creazione di questo.

Parametri usati quando il webhook avvia un runbook

Un webhook può definire valori per i parametri del runbook da usare all'avvio del runbook stesso. Il webhook deve includere valori per tutti i parametri obbligatori del runbook e può includere valori per i parametri facoltativi. Un valore di parametro configurato per un webhook può essere modificato anche dopo la creazione del webhook. Se esistono più webhook collegati a un singolo runbook, ognuno di essi potrà usare valori diversi per i parametri del runbook. Quando avvia un runbook con un webhook, un client non può eseguire l'override dei valori di parametri definiti nel webhook.

Per ricevere dati dal client, il runbook supporta un singolo parametro denominato WebhookData. Questo parametro definisce un oggetto contenente i dati inclusi dal client in una richiesta POST.

Proprietà WebhookData

Il parametro WebhookData ha le proprietà seguenti:

Proprietà Descrizione
WebhookName Nome del webhook.
RequestHeader Tabella hash contenente le intestazioni della richiesta POST in ingresso.
RequestBody Corpo della richiesta POST in ingresso. Questo corpo mantiene qualsiasi formattazione dei dati, ad esempio stringa, JSON, XML o codificata in formato. Il Runbook deve essere scritto in modo che funzioni con il formato di dati previsto.

Non è richiesta alcuna configurazione del webhook per supportare il parametro WebhookData e il runbook non deve necessariamente accettarlo. Se il runbook non definisce il parametro, gli eventuali dettagli della richiesta inviata dal client vengono ignorati.

Nota

Quando si chiama un webhook, il client deve sempre archiviare tutti i valori dei parametri per l'eventualità che la chiamata abbia esito negativo. Se si verifica un'interruzione della rete o un problema di connessione, l'applicazione non è in grado di recuperare le chiamate al webhook non riuscite.

Se si specifica un valore per WebhookData la creazione di webhook, viene sottoposto a override quando il webhook avvia il runbook con i dati della richiesta POST client. Ciò avviene anche se l'applicazione non include dati nel corpo della richiesta.

Se si avvia un runbook che definisce WebhookData usando un meccanismo diverso da un webhook, è possibile specificare un valore per WebhookData riconoscibile dal runbook. Questo valore deve essere un oggetto con le stesse proprietà del parametro WebhookData in modo che il runbook possa usarlo in modo analogo a oggetti WebhookData effettivi passati da un webhook.

Ad esempio, se si avvia il runbook seguente dal portale di Azure e si desidera passare alcuni dati webhook di esempio per il test, è necessario passare i dati in JSON nell'interfaccia utente.

Parametro WebhookData dall'interfaccia utente

Per il prossimo esempio di runbook, si definiranno le proprietà seguenti per WebhookData:

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

A questo punto, nell'interfaccia utente viene passato l'oggetto JSON seguente per il parametro WebhookData. Questo esempio, con ritorni a capo e caratteri di nuova riga, corrisponde al formato passato da un 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

Automazione di Azure registra i valori di tutti i parametri di input con il processo del runbook. Qualsiasi input fornito dal client nella richiesta webhook viene quindi registrato ed è disponibile per chiunque abbia accesso al processo di automazione. Per questo motivo è consigliabile procedere con cautela quando si includono dati sensibili nelle chiamate di webhook.

Sicurezza dei webhook

La sicurezza di un webhook si basa sulla privacy dell'URL corrispondente, che contiene un token di sicurezza che consente di chiamare il webhook. Automazione di Azure non esegue l'autenticazione su una richiesta purché venga effettuata all'URL corretto. Per questo motivo, i client non devono usare webhook per i runbook che eseguono operazioni altamente sensibili senza usare un mezzo alternativo per convalidare la richiesta.

Prendere in considerazione le strategie seguenti:

  • È possibile includere la logica all'interno di un runbook per determinare se viene chiamata da un webhook. Fare in modo che il runbook controlli la proprietà WebhookName del parametro WebhookData. Il runbook può eseguire ulteriori operazioni di convalida cercando informazioni specifiche nella proprietà RequestHeader e RequestBody.

  • Se il runbook esegue una convalida di una condizione esterna quando riceve una richiesta webhook. Si consideri ad esempio un runbook chiamato da GitHub ogni volta che viene eseguito un nuovo commit in un repository di GitHub. Il runbook può connettersi a GitHub per verificare che sia stato eseguito un nuovo commit prima di continuare.

  • Automazione di Azure supporta i tag del servizio di rete virtuale di Azure, in particolare GuestAndHybridManagement. È possibile usare i tag di servizio per definire i controlli di accesso di rete nei gruppi di sicurezza di rete o Firewall di Azure e attivare webhook dall'interno della rete virtuale. I tag di servizio possono essere usati al posto di indirizzi IP specifici quando si creano regole di sicurezza. Specificando il nome del tag di servizio GuestAndHybridManagement nel campo di origine o destinazione appropriato di una regola, è possibile consentire o negare il traffico per il servizio di automazione. Questo tag di servizio non supporta il controllo più granulare limitando gli intervalli IP a un'area specifica.

Creare un webhook

Nota

Quando si usa il webhook con Il runbook di PowerShell 7, converte automaticamente il parametro di input del webhook in un codice JSON non valido. Per altre informazioni, vedere Problemi noti - PowerShell 7.1 (anteprima). È consigliabile usare il webhook con runbook di PowerShell 5.

  1. Creare runbook di PowerShell con il codice seguente:

    param
    (
        [Parameter(Mandatory=$false)]
        [object] $WebhookData
    )
    
    write-output "start"
    write-output ("object type: {0}" -f $WebhookData.gettype())
    write-output $WebhookData
    #write-warning (Test-Json -Json $WebhookData)
    $Payload = $WebhookData | ConvertFrom-Json
    write-output "`n`n"
    write-output $Payload.WebhookName
    write-output $Payload.RequestBody
    write-output $Payload.RequestHeader
    write-output "end"
    
    if ($Payload.RequestBody) { 
        $names = (ConvertFrom-Json -InputObject $Payload.RequestBody)
    
            foreach ($x in $names)
            {
                $name = $x.Name
                Write-Output "Hello $name"
            }
    }
    else {
        Write-Output "Hello World!"
    }
    
  2. Creare un webhook usando l'API portale di Azure o PowerShell o REST. Un webhook richiede un runbook pubblicato. Questa procedura dettagliata usa una versione modificata del runbook creato da Creare un runbook Automazione di Azure.

    1. Accedere al portale di Azure.

    2. Nel portale di Azure passare all'account di Automazione.

    3. In Automazione processi selezionare Runbook per aprire la pagina Runbook .

    4. Selezionare il runbook dall'elenco per aprire la pagina Panoramica del runbook.

    5. Selezionare Aggiungi webhook per aprire la pagina Aggiungi webhook .

      Pagina di panoramica del runbook con l'opzione Aggiungi webhook evidenziata.

    6. Nella pagina Aggiungi webhook selezionare Crea nuovo webhook.

      Aggiungere la pagina webhook con l'opzione Crea evidenziata.

    7. Immettere nel nome del webhook. La data di scadenza per il campo Scade per impostazione predefinita è un anno dalla data corrente.

    8. Fare clic sull'icona di copia oppure premere CTRL+C per copiare l'URL del webhook. Salvare quindi l'URL in una posizione sicura.

      Pagina creaye webhook con URL evidenziato.

      Importante

      Dopo la creazione del webhook, non è possibile recuperare di nuovo l'URL. Assicurarsi di copiarlo e registrarlo come indicato sopra.

    9. Selezionare OK per tornare alla pagina Aggiungi webhook .

    10. Nella pagina Aggiungi webhook selezionare Configura parametri ed eseguire le impostazioni per aprire la pagina Parametri .

      Aggiungere la pagina webhook con i parametri evidenziati.

    11. Esaminare la pagina Parametri . Per il runbook di esempio usato in questo articolo, non sono necessarie modifiche. Selezionare OK per tornare alla pagina Aggiungi webhook .

    12. Nella pagina Aggiungi webhook selezionare Crea. Il webhook viene creato e viene restituito alla pagina Panoramica del runbook.


Usare un webhook

In questo esempio viene usato il cmdlet di PowerShell Invoke-WebRequest per inviare la richiesta POST al nuovo webhook.

  1. Preparare i valori da passare al runbook come corpo per la chiamata webhook. Per i valori relativamente semplici, è possibile creare uno script dei valori come indicato di seguito:

    $Names  = @(
                @{ Name="Hawaii"},
                @{ Name="Seattle"},
                @{ Name="Florida"}
            )
    
    $body = ConvertTo-Json -InputObject $Names
    
  2. Per set di dimensioni maggiori, è possibile usare un file. Creare un file denominato names.json e quindi incollare il codice seguente:

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

    Modificare il valore della variabile $file con il percorso effettivo del file JSON prima di eseguire i comandi di PowerShell seguenti.

    # Revise file path with actual path
    $file = "path\names.json"
    $bodyFile = Get-Content -Path $file 
    
  3. Eseguire i comandi di PowerShell seguenti per chiamare il webhook usando l'API REST.

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

    A scopo illustrativo, sono state effettuate due chiamate per i due diversi metodi di produzione del corpo. Per la produzione, usare un solo metodo. L'output dovrebbe essere simile al seguente (viene visualizzato un solo output):

    Output dalla chiamata webhook.

    Il client riceve uno dei codici restituiti seguenti dalla richiesta POST.

    Codice Text Descrizione
    202 Accepted La richiesta è stata accettata e il Runbook è stato accodato.
    400 Bad Request La richiesta non è stata accettata per uno dei motivi seguenti:
    • Il webhook è scaduto.
    • Il webhook è disabilitato.
    • Il token nell'URL non è valido.
    404 Non trovato La richiesta non è stata accettata per uno dei motivi seguenti:
    • Il webhook non è stato trovato.
    • Il runbook non è stato trovato.
    • L'account non è stato trovato.
    500 Internal Server Error L'URL è valido, ma si è verificato un errore. Inviare di nuovo la richiesta.

    Se la richiesta ha esito positivo, la risposta del webhook conterrà l'ID del processo in formato JSON come illustrato di seguito. Contiene un singolo ID processo, ma il formato JSON consente potenziali miglioramenti futuri.

    {"JobIds":["<JobId>"]}
    
  4. Il cmdlet di PowerShell Get-AzAutomationJobOutput verrà usato per ottenere l'output. È anche possibile usare l'API Automazione di Azure.

    #isolate job ID
    $jobid = (ConvertFrom-Json ($response.Content)).jobids[0]
    
    # Get output
    Get-AzAutomationJobOutput `
        -AutomationAccountName $automationAccount `
        -Id $jobid `
        -ResourceGroupName $resourceGroup `
        -Stream Output
    

    Quando si attiva un runbook creato nel passaggio precedente, verrà creato un processo e l'output dovrebbe essere simile al seguente:

    Output del processo webhook.

Aggiornare un webhook

Quando viene creato un webhook, ha un periodo di validità di 10 anni, dopo il quale scade automaticamente. Dopo che il webhook è scaduto, non è possibile riattivarlo. È solo possibile rimuoverlo e ricrearlo. È possibile estendere un webhook che non ha raggiunto la scadenza. Per estendere un webhook, seguire questa procedura.

  1. Passare al runbook che contiene il webhook.
  2. In Risorse selezionare Webhook e quindi il webhook da estendere.
  3. Nella pagina Webhook scegliere una nuova data e ora di scadenza e quindi selezionare Salva.

Esaminare il webhook di chiamata API - Aggiornare e il cmdlet di PowerShell Set-AzAutomationWebhook per altre possibili modifiche.

Pulire le risorse

Ecco alcuni esempi di rimozione di un webhook da un runbook di Automazione.

  • Usando PowerShell, il cmdlet Remove-AzAutomationWebhook può essere usato come illustrato di seguito. Non viene restituito alcun output.

    Remove-AzAutomationWebhook `
        -ResourceGroup $resourceGroup `
        -AutomationAccountName $automationAccount `
        -Name $psWebhook
    
  • Usando REST, l'API REST Webhook - Delete può essere usata come illustrato di seguito.

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

    Un output di StatusCode : 200 significa un'eliminazione riuscita.

Creare runbook e webhook con il modello di Resource Manager

È anche possibile creare webhook di automazione usando modelli di Resource Manager di Azure. Questo modello di esempio crea un account di Automazione, quattro runbook e un webhook per il runbook denominato.

  1. Creare un file denominato webhook_deploy.json e quindi incollare il codice seguente:

    {
        "$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. L'esempio di codice di PowerShell seguente distribuisce il modello dal computer. Specificare un valore appropriato per le variabili e quindi eseguire lo script.

    $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
    

    Nota

    Per motivi di sicurezza, l'URI viene restituito solo la prima volta che viene distribuito un modello.

Passaggi successivi