Starten eines Runbooks über einen Webhook

  • Artikel

Mit einem Webhook kann ein externer Dienst ein bestimmtes Runbook in Azure Automation über eine einfache HTTP-Anforderung starten. Externe Dienste umfassen Azure DevOps Services, GitHub, Azure Monitor-Protokolle und benutzerdefinierte Anwendungen. Ein solcher Dienst kann einen Webhook verwenden, um ein Runbook zu starten, ohne die vollständige Azure Automation-API zu implementieren. Unter Starten eines Runbooks in Azure Automation können Sie Webhooks mit anderen Methoden zum Starten eines Runbooks vergleichen.

WebhooksOverview

Informationen zu den Anforderungen für TLS 1.2 oder höher mit Webhooks finden Sie unter TLS 1.2 oder höher für Azure Automation.

Eigenschaften von Webhooks

Die folgende Tabelle beschreibt die Eigenschaften, die Sie für einen Webhook konfigurieren müssen.

Eigenschaft Beschreibung
Name Name des Webhooks. Sie können einen beliebigen Namen vergeben, da er nicht für den Client verfügbar gemacht wird. Sie benötigen den Namen nur zur Identifizierung des Runbooks in Azure Automation. Es empfiehlt sich, den Webhook entsprechend dem Client zu benennen, der ihn verwenden wird.
URL URL des Webhooks. Dies ist die eindeutige Adresse, die ein Client mit einer HTTP POST-Anforderung aufruft, um das mit dem Webhook verknüpfte Runbook zu starten. Sie wird beim Erstellen des Webhooks automatisch generiert. Sie können keine benutzerdefinierte URL angeben.

Die URL enthält ein Sicherheitstoken, das es einem Drittanbietersystem ermöglicht, das Runbook ohne weitere Authentifizierung aufzurufen. Behandeln Sie die URL daher wie ein Kennwort. Aus Sicherheitsgründen können Sie die URL im Azure-Portal nur zu dem Zeitpunkt anzeigen, zu dem der Webhook erstellt wird. Sie sollten die URL zur späteren Verwendung an einem sicheren Ort speichern.
Ablaufdatum Das Ablaufdatum des Webhooks, nach dem er nicht mehr verwendet werden kann. Sie können das Ablaufdatum nach dem Erstellen des Webhooks ändern, solange der Webhook noch nicht abgelaufen ist.
Enabled Diese Einstellung gibt an, dass der Webhook bei der Erstellung standardmäßig aktiviert ist. Wenn Sie diese Eigenschaft deaktivieren, kann der Webhook von keinem Client verwendet werden. Sie können diese Eigenschaft beim Erstellen des Webhooks oder zu einem beliebigen späteren Zeitpunkt festlegen.

Parameter, die verwendet werden, wenn der Webhook ein Runbook startet

Ein Webhook kann Werte für Runbookparameter definieren, die verwendet werden, wenn das Runbook gestartet wird. Der Webhook muss Werte für alle obligatorischen Parameter des Runbooks einschließen und kann auch Werte für optionale Parameter umfassen. Ein Parameterwert, der für einen Webhook konfiguriert wurde, kann auch nach der Erstellung des Webhooks geändert werden. Mehrere mit einem einzelnen Runbook verknüpften Webhooks können verschiedene Parameterwerte für das Runbook verwenden. Wenn ein Client ein Runbook mithilfe eines Webhooks startet, können die im Webhook definierten Parameterwerte nicht überschrieben werden.

Um Daten vom Client zu empfangen, unterstützt das Runbook einen einzelnen Parameter mit dem Namen WebhookData. Dieser Parameter definiert ein Objekt, das Daten enthält, die der Client in eine POST-Anforderung einschließt.

WebhookData properties

Der WebhookData-Parameter hat folgende Eigenschaften:

Eigenschaft Beschreibung
WebhookName Name des Webhooks.
RequestHeader PSCustomObject mit den Headern der eingehenden POST-Anforderung.
RequestBody Der Text der eingehenden POST-Anforderung. In diesem Text werden sämtliche Datenformatierungen beibehalten, z. B. Zeichenfolgen, JSON, XML oder formularcodierte Daten. Das Runbook muss so verfasst werden, dass es mit dem erwarteten Datenformat funktioniert.

Zur Unterstützung des Parameters WebhookData ist keine Konfiguration des Webhooks erforderlich, und das Runbook muss ihn nicht akzeptieren. Wenn das Runbook den Parameter nicht definiert, werden alle vom Client gesendeten Details der Anforderung ignoriert.

Hinweis

Beim Aufrufen eines Webhooks muss der Client für den Fall, dass der Aufruf fehlschlägt, immer alle Parameterwerte speichern. Bei einem Netzwerkausfall oder einem Verbindungsproblem kann die Anwendung fehlgeschlagene Webhook-Aufrufe nicht abrufen.

Wenn Sie beim Erstellen des Webhooks einen Wert für WebhookData festlegen, wird dieser überschrieben, wenn der Webhook das Runbook mit den Daten aus der POST-Anforderung des Clients startet. Dies geschieht selbst dann, wenn die Anwendung keine Daten in den Anforderungstext einbezieht.

Wenn Sie ein Runbook starten, das WebhookData mit einem anderen Mechanismus als einem Webhook definiert, können Sie einen Wert für WebhookData angeben, der vom Runbook erkannt wird. Bei diesem Wert sollte es sich um ein Objekt mit den gleichen Eigenschaften wie dem Parameter WebhookData handeln, damit das Runbook damit genauso funktioniert, wie mit WebhookData-Objekten, die über einen Webhook übergeben werden.

Wenn Sie beispielsweise das folgende Runbook aus dem Azure-Portal starten und Webhook-Beispieldaten zum Testen übergeben möchten, müssen Sie die Daten in der Benutzeroberfläche als JSON übergeben.

WebhookData parameter from UI

Für das nächste Beispiel für ein Runbook definieren wir die folgenden Eigenschaften für WebhookData:

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

Nun übergeben wir das folgende JSON-Objekt in der Benutzeroberfläche für den Parameter WebhookData. Dieses Beispiel mit Wagenrücklauf und Zeilenumbruchzeichen entspricht dem vom Webhook übergebenen Format.

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

Start WebhookData parameter from UI

Hinweis

Azure Automation protokolliert die Werte aller Eingabeparameter mit dem Runbookauftrag. Somit werden alle vom Client in der Webhookanforderung bereitgestellten Eingaben protokolliert und stehen jedem Benutzer mit Zugriff auf den Automatisierungsauftrag zur Verfügung. Aus diesem Grund sollten Sie sorgfältig überlegen, welche vertraulichen Daten Sie in Webhookaufrufe einschließen.

Webhook-Sicherheit

Die Sicherheit eines Webhooks beruht auf dem Schutz seiner URL, die ein Sicherheitstoken enthält, mit dem der Webhook aufgerufen werden kann. Azure Automation führt keinerlei Authentifizierung der Anforderung durch, sofern diese über die richtige URL erfolgt. Aus diesem Grund sollten Ihre Client keine Webhooks für Runbooks verwenden, die sehr vertrauliche Vorgänge ausführen, ohne eine alternative Möglichkeit zur Überprüfung der Anforderung zu verwenden.

Erwägen Sie die folgenden Strategien:

  • Sie können Logik in ein Runbook einschließen, um zu bestimmen, ob es von einem Webhook aufgerufen wird. Lassen Sie das Runbook die Eigenschaft WebhookName des Parameters WebhookData überprüfen. Das Runbook kann eine weitere Überprüfung durchführen, indem es in den Eigenschaften RequestHeaderoder RequestBody nach bestimmten Informationen sucht.

  • Lassen Sie das Runbook eine externe Bedingung überprüfen, wenn es eine Webhookanforderung empfängt. Betrachten Sie z. B. ein Runbook, das von GitHub aufgerufen wird, sobald ein neuer Commit für ein GitHub-Repository vorhanden ist. Das Runbook kann eine Verbindung mit GitHub herstellen, um zu überprüfen, ob ein neuer Commit durchgeführt wurde, bevor es mit der Ausführung fortfährt.

  • Azure Automation unterstützt Diensttags für virtuelle Azure-Netzwerke (genauer gesagt: GuestAndHybridManagement). Sie können Diensttags verwenden, um Netzwerkzugriffssteuerungen für Netzwerksicherheitsgruppen oder Azure Firewall zu definieren und Webhooks innerhalb Ihres virtuellen Netzwerks auszulösen. Diensttags können anstelle von spezifischen IP-Adressen verwendet werden, wenn Sie Sicherheitsregeln erstellen. Indem Sie den Diensttagnamen GuestAndHybridManagement im entsprechenden Quell- oder Zielfeld einer Regel angeben, können Sie den Datenverkehr für den Automation-Dienst zulassen oder verweigern. Dieses Diensttag weist keine Unterstützung für das Zulassen einer präziseren Steuerung durch das Einschränken von IP-Adressbereichen auf eine bestimmte Region auf.

Erstellen eines Webhooks

Hinweis

Wenn Sie den Webhook mit dem PowerShell 7-Runbook verwenden, wird der Eingabeparameter des Webhooks automatisch in einen ungültigen JSON-Code konvertiert. Weitere Informationen finden Sie unter Bekannte Probleme: PowerShell 7.1 (Vorschau). Es wird empfohlen, den Webhook mit einem PowerShell 5-Runbook zu verwenden.

  1. Erstellen Sie ein PowerShell-Runbook mit dem folgenden Code:

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

  2. Erstellen Sie einen Webhook über Azure-Portal, mit PowerShell oder mit der REST-API. Ein Webhook erfordert ein veröffentlichtes Runbook. In dieser exemplarischen Vorgehensweise wird eine geänderte Version des Runbooks verwendet, das unter Erstellen eines Azure Automation-Runbooks erstellt wurde.

    1. Melden Sie sich beim Azure-Portal an.

    2. Navigieren Sie im Azure-Portal zu Ihrem Automation-Konto.

    3. Wählen Sie unter Prozessautomatisierung die Option Runbooks aus, um die Seite Runbooks zu öffnen.

    4. Wählen Sie Ihr Runbook in der Liste aus, um die Seite Übersicht zu für Runbooks zu öffnen.

    5. Wählen Sie Webhook hinzufügen aus, um die Seite Webhook hinzufügen zu öffnen.

      Runbook overview page with Add webhook highlighted.

    6. Wählen Sie auf der Seite Webhook hinzufügen die Option Neuen Webhook erstellen aus.

      Add webhook page with create highlighted.

    7. Geben Sie den Namen für den Webhook ein. Das Ablaufdatum für das Feld Läuft ab wird standardmäßig auf ein Jahr ab dem aktuellen Datum festgelegt.

    8. Klicken Sie auf das Symbol zum Kopieren, oder drücken Sie STRG+C, um die URL des Webhooks zu kopieren. Speichern Sie dann die URL an einem sicheren Speicherort.

      Creaye webhook page with URL highlighted.

      Wichtig

      Nachdem Sie den Webhook erstellt haben, können Sie die URL nicht erneut abrufen. Stellen Sie sicher, dass Sie sie wie oben beschrieben kopieren und sichern.

    9. Klicken Sie auf OK, um zur Seite Webhook hinzufügen zurückzukehren.

    10. Wählen Sie auf der Seite Webhook hinzufügen die Option Parameter und Ausführungseinstellungen konfigurieren aus, um die Seite Parameter zu öffnen.

      Add webhook page with parameters highlighted.

    11. Überprüfen Sie die Seite Parameter. Für das in diesem Artikel verwendete Beispielrunbook sind keine Änderungen erforderlich. Klicken Sie auf OK, um zur Seite Webhook hinzufügen zurückzukehren.

    12. Wählen Sie auf der Seite Webhook hinzufügen die Option Erstellen aus. Der Webhook wird erstellt, und Sie kehren zur Runbookseite Übersicht zurück.

Verwenden eines Webhooks

In diesem Beispiel wird das PowerShell-Cmdlet Invoke-WebRequest verwendet, um die POST-Anforderung an den neuen Webhook zu senden.

  1. Bereiten Sie Werte vor, die als Text für den Webhookaufruf an das Runbook übergeben werden. Für relativ einfache Werte können Sie ein Skript für die Werte wie folgt erstellen:

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

$body = ConvertTo-Json -InputObject $Names

  2. Bei größeren Mengen können Sie eine Datei verwenden. Erstellen Sie eine Datei namens names.json, und fügen Sie den folgenden Code in die Datei ein:

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

    Ändern Sie den Wert der Variablen $file in den tatsächlichen Pfad zur JSON-Datei, bevor Sie die folgenden PowerShell-Befehle ausführen.

    # Revise file path with actual path
$file = "path\names.json"
$bodyFile = Get-Content -Path $file

  3. Führen Sie die folgenden PowerShell-Befehle zum Aufrufen des Webhooks mithilfe der REST-API aus.

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

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

    Zur Veranschaulichung wurden zwei Aufrufe für die beiden verschiedenen Methoden zum Erstellen des Textkörpers durchgeführt. Verwenden Sie für die Produktion nur eine Methode. Die Ausgabe sollte in etwa wie folgt aussehen (nur eine Ausgabe wird gezeigt):

    Output from webhook call.

    Der Client empfängt einen der folgenden Rückgabecodes als Antwort auf die POST-Anforderung.

    Code Text Beschreibung
    202 Zulässig Die Anforderung wurde akzeptiert, und das Runbook wurde erfolgreich in die Warteschlange gestellt.
    400 Ungültige Anforderung Die Anforderung wurde aus einem der folgenden Gründe nicht akzeptiert:
    • Der Webhook ist abgelaufen.
    • Der Webhook ist deaktiviert.
    • Das Token in der URL ist ungültig.
    404 Nicht gefunden Die Anforderung wurde aus einem der folgenden Gründe nicht akzeptiert:
    • Der Webhook wurde nicht gefunden.
    • Das Runbook wurde nicht gefunden.
    • Das Konto wurde nicht gefunden.
    500 Interner Serverfehler Die URL ist gültig, es ist jedoch ein Fehler aufgetreten. Senden Sie die Anforderung erneut.

    Wenn die Anforderung erfolgreich ist, enthält die Antwort des Webhooks wie im Folgenden dargestellt die Auftrags-ID im JSON-Format. Sie enthält eine einzelne Auftrags-ID, wobei das JSON-Format Potenzial für künftige Verbesserungen bietet.

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

  4. Das PowerShell-Cmdlet Get-AzAutomationJobOutput wird zum Abrufen der Ausgabe verwendet. Die Azure Automation-API kann auch genutzt werden.

    #isolate job ID
$jobid = (ConvertFrom-Json ($response.Content)).jobids[0]

# Get output
Get-AzAutomationJobOutput `
    -AutomationAccountName $automationAccount `
    -Id $jobid `
    -ResourceGroupName $resourceGroup `
    -Stream Output

    Wenn Sie ein im vorherigen Schritt erstelltes Runbook auslösen, wird ein Auftrag erstellt. Die Ausgabe sollte in etwa wie folgt aussehen:

    Output from webhook job.

Aktualisieren eines Webhooks

Wenn ein Webhook erstellt wird, hat er einen Gültigkeitszeitraum von 10 Jahren, nach dem er automatisch abläuft. Wenn ein Webhook abgelaufen ist, kann er nicht reaktiviert werden. Sie können ihn nur entfernen und anschließend neu erstellen. Sie können einen Webhook verlängern, der seine Ablaufzeit noch nicht erreicht hat. Führen Sie die folgenden Schritte aus, um einen Webhook zu verlängern.

  1. Navigieren Sie zu dem Runbook, das den Webhook enthält.
  2. Wählen Sie unter Ressourcen erst Webhooks und dann den Webhook aus, den Sie verlängern möchten.
  3. Wählen Sie auf der Seite Webhook ein neues Ablaufdatum und eine neue Ablaufzeit und dann Speichern aus.

Überprüfen Sie den API-Aufruf Webhook – Aktualisieren und das PowerShell-Cmdlet Set-AzAutomationWebhook auf weitere Änderungsmöglichkeiten.

Bereinigen von Ressourcen

Es folgen Beispiele für das Entfernen eines Webhooks aus einem Automation-Runbook.

  • Mithilfe von PowerShell kann das Cmdlet Remove-AzAutomationWebhook wie unten gezeigt verwendet werden. Es wird keine Ausgabe zurückgegeben.

    Remove-AzAutomationWebhook `
    -ResourceGroup $resourceGroup `
    -AutomationAccountName $automationAccount `
    -Name $psWebhook

  • Mithilfe von REST kann die REST-API Webhook – Löschen wie unten gezeigt verwendet werden.

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

    Die Ausgabe StatusCode : 200 steht für einen erfolgreichen Löschvorgang.

Erstellen eines Runbooks und Webhooks mit einer ARM-Vorlage

Automation-Webhooks können auch mit Azure Resource Manager-Vorlagen erstellt werden. Mit dieser Beispielvorlage werden ein Automation-Konto, vier Runbooks und ein Webhook für das benannte Runbook erstellt.

  1. Erstellen Sie eine Datei namens webhook_deploy.json, und fügen Sie den folgenden Code in die Datei ein:

    {
    "$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. Mit dem folgenden PowerShell-Codebeispiel wird die Vorlage von Ihrem Computer aus bereitgestellt. Geben Sie einen geeigneten Wert für die Variablen an, und führen Sie dann das Skript aus.

    $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

    Hinweis

    Aus Sicherheitsgründen wird der URI nur bei der erstmaligen Bereitstellung einer Vorlage zurückgegeben.

Nächste Schritte