Avviare un runbook da un webhook

Articolo
10/16/2024

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.

Panoramica dei webhook

Per informazioni sui requisiti client per TLS 1.2 o versione successiva con i webhook, vedere TLS 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, a condizione che quest'ultimo non sia scaduto.
Attivata	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	PSCustomObject contenente le intestazioni della richiesta POST in ingresso.
RequestBody	Corpo della richiesta POST in ingresso. Il corpo mantiene la formattazione dei dati, ad esempio stringa, JSON, XML o con codifica per il modulo. 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 al momento della creazione del webhook, ne viene eseguito l'override quando il webhook avvia il runbook con i dati della richiesta POST del client. Questo si verifica 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.

Se ad esempio si avvia il runbook seguente dal portale di Azure e si vogliono passare alcuni dati di webhook di esempio a scopo di test, i dati devono essere passati 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 alcuna autenticazione per una richiesta, a condizione che questa venga inviata all'URL corretto. Per questo motivo, i client devono usare webhook per runbook che eseguono operazioni altamente sensibili solo se usano una modalità alternativa di convalida della richiesta.

Considerare le strategie seguenti:

È possibile includere logica in un runbook per determinare se quest'ultimo viene chiamato 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.
Fare in modo che il runbook esegua la convalida di una condizione esterna quando riceve una richiesta di 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 del servizio per definire i controlli di accesso alla rete nei gruppi di sicurezza di rete o in Firewall di Azure e avviare i webhook dall'interno della rete virtuale. Quando si creano regole di sicurezza è possibile usare i tag del servizio anziché indirizzi IP specifici. Se si specifica il nome del tag del servizio GuestAndHybridManagement nel campo di origine o di destinazione appropriato di una regola, è possibile consentire o negare il traffico per il servizio Automazione. Questo tag del servizio non supporta il controllo più granulare limitando gli intervalli IP a un'area specifica.

Creare un webhook

Nota

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

Creare un 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-output "`n`n"
write-output $WebhookData.WebhookName
write-output $WebhookData.RequestBody
write-output $WebhookData.RequestHeader
write-output "end"

if ($WebhookData.RequestBody) { 
    $names = (ConvertFrom-Json -InputObject $WebhookData.RequestBody)

        foreach ($x in $names)
        {
            $name = $x.Name
            Write-Output "Hello $name"
        }
}
else {
    Write-Output "Hello World!"
}

Creare un webhook usando il portale di Azure, PowerShell o l'API REST. Un webhook richiede un runbook pubblicato. Questa procedura dettagliata usa una versione modificata del runbook creato in Creare un runbook di 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 nell'elenco per aprire la relativa pagina Panoramica.
5. Selezionare Aggiungi webhook per aprire la pagina Aggiungi webhook.
6. Nella pagina Aggiungi webhook selezionare Crea un nuovo webhook.
7. Immettere il Nome per il webhook. Per impostazione predefinita, la data di scadenza per il campo Scade è impostata su un anno successivo alla data corrente.
8. Fare clic sull'icona Copia e premere CTRL+C per copiare l'URL del webhook. Quindi salvare l'URL in una posizione sicura.
  
  Importante
  
  Dopo la creazione del webhook, non è possibile recuperare di nuovo l'URL. Assicurarsi di copiare e registrarlo come sopra.
9. Selezionare OK per tornare nella pagina Aggiungi webhook.
10. Nella pagina Aggiungi webhook selezionare Configura i parametri e le impostazioni di esecuzione per aprire la pagina Parametri.
11. Esaminare la pagina Parametri. Per il runbook di esempio usato in questo articolo, non sono necessarie modifiche. Selezionare OK per tornare nella pagina Aggiungi webhook.
12. Nella pagina Aggiungi webhook selezionare Crea. Il webhook viene creato e si torna nella pagina Panoramica del runbook.
1. Verificare di aver installato la versione più recente del modulo Az di PowerShell.
2. Accedere ad Azure in modo interattivo usando il cmdlet Connect-AzAccount e seguire le istruzioni:
```
# Sign in to your Azure subscription
$sub = Get-AzSubscription -ErrorAction SilentlyContinue
if(-not($sub))
{
    Connect-AzAccount
}
```
3. Usare il cmdlet New-AzAutomationWebhook per creare un webhook per un runbook di Automazione. Specificare un valore appropriato per le variabili e quindi eseguire lo script.
```
# Initialize variables with your relevant values
$resourceGroup = "resourceGroupName"
$automationAccount = "automationAccountName"
$runbook = "runbookName"
$psWebhook = "webhookName"

# Create webhook
$newWebhook = New-AzAutomationWebhook `
    -ResourceGroup $resourceGroup `
    -AutomationAccountName $automationAccount `
    -Name $psWebhook `
    -RunbookName $runbook `
    -IsEnabled $True `
    -ExpiryTime "12/31/2022" `
    -Force

# Store URL in variable; reveal variable
$uri = $newWebhook.WebhookURI
$uri
```
  L'output sarà un URL simile al seguente: https://ad7f1818-7ea9-4567-b43a.webhook.wus.azure-automation.net/webhooks?token=uTi69VZ4RCa42zfKHCeHmJa2W9fd
4. È anche possibile verificare il webhook con il cmdlet Get-AzAutomationWebhook di PowerShell.
```
Get-AzAutomationWebhook `
    -ResourceGroup $resourceGroup `
    -AutomationAccountName $automationAccount `
    -Name $psWebhook
```
Il comando PUT è documentato in Webhook - Create or Update. Questo esempio usa il cmdlet Invoke-RestMethod di PowerShell per inviare la richiesta PUT.
1. Creare un file denominato webhook.json e incollarvi il codice seguente:
```
{
"name": "RestWebhook",
"properties": {
    "isEnabled": true,
    "expiryTime": "2022-03-29T22:18:13.7002872Z",
    "runbook": {
    "name": "runbookName"
    }
}
}
```
  Prima di eseguirlo, sostituire il valore per la proprietà runbook:name con il nome effettivo del runbook. Per altre informazioni su queste proprietà, vedere Proprietà dei webhook.
2. Verificare di aver installato la versione più recente del modulo Az di PowerShell.
3. Accedere ad Azure in modo interattivo usando il cmdlet Connect-AzAccount e seguire le istruzioni:
```
# Sign in to your Azure subscription
$sub = Get-AzSubscription -ErrorAction SilentlyContinue
if(-not($sub))
{
    Connect-AzAccount
}
```
4. Specificare un valore appropriato per le variabili e quindi eseguire lo script.
```
# Initialize variables
$subscription = "subscriptionID"
$resourceGroup = "resourceGroup"
$automationAccount = "automationAccount"
$runbook = "runbookName"
$restWebhook = "webhookName"
$file = "path\webhook.json"

# consume file
$body = Get-Content $file

# Craft Uri
$restURI = "https://management.azure.com/subscriptions/$subscription/resourceGroups/$resourceGroup/providers/Microsoft.Automation/automationAccounts/$automationAccount/webhooks/$restWebhook`?api-version=2015-10-31"
```
5. Eseguire lo script seguente per ottenere un token di accesso. Se il token di accesso è scaduto, è necessario eseguire nuovamente lo script.
```
# Obtain access token
$azContext = Get-AzContext
$azProfile = [Microsoft.Azure.Commands.Common.Authentication.Abstractions.AzureRmProfileProvider]::Instance.Profile
$profileClient = New-Object -TypeName Microsoft.Azure.Commands.ResourceManager.Common.RMProfileClient -ArgumentList ($azProfile)
$token = $profileClient.AcquireAccessToken($azContext.Subscription.TenantId)
$authHeader = @{
    'Content-Type'='application/json'
    'Authorization'='Bearer ' + $token.AccessToken
}
```
6. Eseguire lo script seguente per creare il webhook usando l'API REST.
```
# Invoke the REST API
# Store URL in variable; reveal variable
$response = Invoke-RestMethod -Uri $restURI -Method Put -Headers $authHeader -Body $body
$webhookURI = $response.properties.uri
$webhookURI
```
  L'output è un URL simile al seguente: https://ad7f1818-7ea9-4567-b43a.webhook.wus.azure-automation.net/webhooks?token=uTi69VZ4RCa42zfKHCeHmJa2W9fd
7. È anche possibile usare Webhook - Get per recuperare il webhook identificato dal relativo nome. È possibile eseguire i seguenti comandi di PowerShell:
```
$response = Invoke-RestMethod -Uri $restURI -Method GET -Headers $authHeader
$response | ConvertTo-Json
```

Usare un webhook

Questo esempio usa il cmdlet Invoke-WebRequest di PowerShell per inviare la richiesta POST al nuovo webhook.

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

$Names  = @(
            @{ Name="Hawaii"},
            @{ Name="Seattle"},
            @{ Name="Florida"}
        )

$body = ConvertTo-Json -InputObject $Names

Per i 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" }
]
```
Sostituire 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 
```

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 l'ambiente di produzione, usare un solo metodo. L'output dovrà essere simile al seguente (viene visualizzato un solo output):

Output della chiamata al webhook.

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

Codice	Testo	Descrizione
202	Accettata	La richiesta è stata accettata e il Runbook è stato accodato.
400	Richiesta non valida	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>"]}

Per ottenere l'output, verrà usato il cmdlet Get-AzAutomationJobOutput di PowerShell. È anche possibile usare l'API di 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 dovrà essere simile al seguente:

Aggiornare un webhook

Quando viene creato, un webhook ha un periodo di validità di dieci 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 abbia raggiunto la data di scadenza. Per estendere un webhook, seguire questa procedura.

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

Esaminare la chiamata API Webhook - Update e il cmdlet Set-AzAutomationWebhook di PowerShell per altre possibili modifiche.

Pulire le risorse

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

Tramite PowerShell, è possibile usare il cmdlet Remove-AzAutomationWebhook come illustrato di seguito. Non viene restituito alcun output.
```
Remove-AzAutomationWebhook `
    -ResourceGroup $resourceGroup `
    -AutomationAccountName $automationAccount `
    -Name $psWebhook
```
Tramite REST, è possibile usare l'API REST Webhook - Delete come illustrato di seguito.
```
Invoke-WebRequest -Method Delete -Uri $restURI -Headers $authHeader
```
Un output StatusCode : 200 indica un'eliminazione riuscita.

Creare runbook e webhook con un modello di Resource Manager

I webhook di Automazione possono anche essere creati usando modelli di Azure Resource Manager. Questo modello di esempio crea un account di Automazione, quattro runbook e un webhook per il runbook specificato.

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]"
        }
    }
}

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

Per attivare un runbook da un avviso, vedere Usare un avviso per attivare un runbook di Automazione di Azure.

Condividi tramite

Avviare un runbook da un webhook

Proprietà dei webhook

Parametri usati quando il webhook avvia un runbook

Sicurezza dei webhook

Creare un webhook

Usare un webhook

Aggiornare un webhook

Pulire le risorse

Creare runbook e webhook con un modello di Resource Manager

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive