Uruchamianie elementu runbook z poziomu elementu webhook

Webhook umożliwia usłudze zewnętrznej uruchomienie określonego runbooka w Azure Automation za pomocą pojedynczego żądania HTTP. Usługi zewnętrzne obejmują usługi Azure DevOps, GitHub, dzienniki Azure Monitor i aplikacje niestandardowe. Taka usługa umożliwia użycie webhooka do uruchomienia runbooka bez potrzeby implementowania pełnego interfejsu API Azure Automation. Możesz porównać webhooki z innymi metodami uruchamiania runbooka w Uruchamianie runbooka w Azure Automation.

Przegląd webhooków

Aby zrozumieć wymagania klienta dotyczące protokołu TLS 1.2 lub nowszego z elementami webhook, zobacz TLS dla Azure Automation.

Właściwości webhooka

W poniższej tabeli opisano właściwości, które należy skonfigurować dla elementu webhook.

Właściwość Opis
Nazwa Nazwa elementu webhook. Możesz podać dowolną nazwę, ponieważ nie jest ona widoczna dla klienta. Służy tylko do identyfikowania elementu Runbook w Azure Automation. Najlepszym rozwiązaniem jest nadanie elementowi webhook nazwy powiązanej z klientem, który go używa.
adres URL Adres URL webhooku Jest to unikatowy adres, który klient wywołuje za pomocą żądania HTTP POST w celu uruchomienia runbooka powiązanego z webhookiem. Generuje się go automatycznie podczas tworzenia webhooku. Nie można określić niestandardowego adresu URL.

Adres URL zawiera token zabezpieczający, który umożliwia systemowi innej firmy uruchamianie runbooka bez potrzeby dalszego uwierzytelniania. Z tego powodu należy traktować adres URL jak hasło. Ze względów bezpieczeństwa adres URL można wyświetlić tylko w portalu Azure podczas tworzenia elementu webhook. Zanotuj adres URL w bezpiecznej lokalizacji do użycia w przyszłości.
Data wygaśnięcia Data wygaśnięcia webhooka, po której nie można go już używać. Datę wygaśnięcia można zmodyfikować po utworzeniu elementu webhook, o ile element webhook nie wygasł.
Włączony Ustawienie wskazujące, czy element webhook jest domyślnie włączony podczas jego tworzenia. Jeśli ustawisz tę właściwość na Wartość Wyłączone, żaden klient nie może użyć elementu webhook. Tę właściwość można ustawić podczas tworzenia webhooka lub w dowolnym momencie po jego utworzeniu.

Parametry używane podczas uruchamiania elementu runbook

Element webhook może definiować wartości parametrów elementu Runbook używanych podczas uruchamiania elementu Runbook. Element webhook musi zawierać wartości dla wszystkich obowiązkowych parametrów elementu Runbook i może zawierać wartości parametrów opcjonalnych. Wartość parametru skonfigurowana do elementu webhook może zostać zmodyfikowana nawet po utworzeniu elementu webhook. Wiele elementów webhook połączonych z jednym elementem Runbook może używać różnych wartości parametrów elementu Runbook. Gdy klient uruchamia runbook za pomocą webhooka, nie może zastąpić wartości parametrów zdefiniowanych w webhooku.

Aby odbierać dane od klienta, element Runbook obsługuje pojedynczy parametr o nazwie WebhookData. Ten parametr definiuje obiekt zawierający dane, które klient zawiera w żądaniu POST.

Właściwości elementu webhookData

Parametr WebhookData ma następujące właściwości:

Właściwość Opis
Nazwa webhook Nazwa elementu webhook.
RequestHeader PSCustomObject zawierający nagłówki przychodzącego żądania POST.
RequestBody Treść przychodzącego żądania POST. To ciało przechowuje dowolny format danych, taki jak ciąg, JSON, XML lub formularz. Runbook musi być napisany tak, aby współpracować z oczekiwanym formatem danych.

Nie jest wymagane konfigurowanie webhooka w celu obsługi parametru WebhookData, a runbook nie jest wymagany do jego akceptacji. Jeśli element Runbook nie definiuje parametru, wszystkie szczegóły żądania wysłanego z klienta są ignorowane.

Uwaga

Podczas wywoływania elementu webhook klient powinien zawsze przechowywać wszystkie wartości parametrów w przypadku niepowodzenia wywołania. Jeśli występuje awaria sieci lub problem z połączeniem, aplikacja nie może pobrać wywołań webhook, które się nie powiodły.

Jeśli określisz wartość dla WebhookData podczas tworzenia webhooku, zostanie ona zastąpiona, gdy webhook uruchomi Runbook z danymi z żądania POST klienta. Dzieje się tak, nawet jeśli aplikacja nie zawiera żadnych danych w treści żądania.

Jeśli uruchamiasz Runbook, który definiuje WebhookData przy użyciu mechanizmu innego niż webhook, możesz podać wartość WebhookData, którą Runbook rozpoznaje. Ta wartość powinna być obiektem o tych samych właściwościach co parametr WebhookData, aby runbook mógł z nim pracować tak jak z rzeczywistymi obiektami przekazywanymi przez webhook.

Jeśli na przykład uruchamiasz następujący skrypt Runbook z portalu Azure i chcesz przekazać przykładowe dane webhook do testowania, musisz wprowadzić dane w formacie JSON w interfejsie użytkownika.

Parametr WebhookData z interfejsu użytkownika

W następnym przykładzie runbook zdefiniujmy następujące właściwości dla WebhookData:

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

Teraz przekażemy następujący obiekt JSON w interfejsie użytkownika dla parametru WebhookData . Przykład ten, zawierający powroty karetki i znaki nowego wiersza, pasuje do formatu przekazywanego z webhooka.

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

Uruchamianie parametru WebhookData z poziomu interfejsu użytkownika

Uwaga

Azure Automation rejestruje wartości wszystkich parametrów wejściowych w ramach zadania Runbook. W związku z tym wszelkie dane wejściowe dostarczone przez klienta w żądaniu elementu webhook są rejestrowane i dostępne dla każdej osoby z dostępem do zadania automatyzacji. Z tego powodu należy zachować ostrożność przy dołączaniu poufnych informacji w wywołaniach webhook.

Zabezpieczenia webhooków

Zabezpieczenia elementu webhook bazują na prywatności jego adresu URL, który zawiera token zabezpieczający umożliwiający wywoływanie elementu webhook. Azure Automation nie wykonuje żadnego uwierzytelniania na żądaniu, o ile zostanie ono wykonane pod prawidłowym adresem URL. Z tego powodu klienci nie powinni używać webhooków dla runbooków wykonujących wysoce poufne operacje bez użycia alternatywnej metody weryfikacji żądania klienta.

Rozważ zastosowanie następujących strategii:

  • Logikę można uwzględnić w elemecie Runbook, aby określić, czy jest wywoływana przez element webhook. Niech runbook sprawdzi właściwość WebhookName parametru WebhookData. Element Runbook może przeprowadzić dalszą walidację, wyszukując określone informacje we właściwościach RequestHeader i RequestBody .

  • Runbook wykonuje weryfikację warunku zewnętrznego, gdy otrzymuje żądanie webhook. Rozważmy na przykład element Runbook, który jest wywoływany przez GitHub za każdym razem, gdy w repozytorium GitHub istnieje nowe zatwierdzenie. Runbook może nawiązać połączenie z GitHub, aby sprawdzić, czy nowe zatwierdzenie nastąpiło przed kontynuowaniem.

  • Azure Automation obsługuje tagi usługi sieci wirtualnej Azure, w szczególności GuestAndHybridManagement. Za pomocą tagów usługi można definiować mechanizmy kontroli dostępu do sieci w grupach zabezpieczeń sieciowych lub Azure Firewall i wyzwalać webhooki z poziomu sieci wirtualnej. Tagów usługi można też użyć zamiast konkretnych adresów IP podczas tworzenia reguł zabezpieczeń. Podając nazwę tagu usługi GuestAndHybridManagement w odpowiednim polu miejsca źródłowego lub docelowego w regule, możesz zezwolić na ruch dla usługi Automation lub go odrzucić. Ten tag usługi nie obsługuje zezwalania na bardziej szczegółową kontrolę przez ograniczenie zakresów adresów IP do konkretnego regionu.

Utwórz webhook

Uwaga

  • Gdy używasz webhooka z runbookiem programu PowerShell 7, automatycznie konwertuje dane wejściowe webhooka do nieprawidłowego JSON-a. Aby uzyskać więcej informacji, zobacz Znane problemy — PowerShell 7.1 (wersja zapoznawcza). Zalecamy używanie webhooka z runbookiem PowerShell 5.
  • Nie jest obsługiwane uruchamianie skryptu runbook Python przy użyciu webhook.

Aby utworzyć element webhook, wykonaj następujące kroki:

  1. Utwórz element Runbook programu PowerShell przy użyciu następującego kodu:

    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. Utwórz element webhook przy użyciu portalu Azure lub programu PowerShell lub interfejsu API REST. Webhook wymaga opublikowanego runbooka. W tym przewodniku użyto zmodyfikowanej wersji runbooka utworzonego na podstawie Tworzenie runbooka usługi Azure Automation.

    Aby utworzyć element webhook przy użyciu portalu Azure, wykonaj następujące czynności:

    1. Zaloguj się do portalu Azure.

    2. W portalu Azure przejdź do swojego konta usługi Automation.

    3. W obszarze Automatyzacja procesów wybierz pozycję Runbooks, aby otworzyć stronę Runbooks.

    4. Wybierz Runbook z listy, aby otworzyć stronę Przegląd Runbooka.

    5. Wybierz Dodaj webhook, aby otworzyć stronę Dodaj webhook.

      Strona przeglądu Runbook z wyróżnioną opcją Dodaj webhook.

    6. Na stronie Dodawanie elementu webhook wybierz pozycję Utwórz nowy element webhook.

      Dodaj stronę webhook z wyróżnioną opcją tworzenia.

    7. Wprowadź Nazwę dla webhooka. Data wygaśnięcia pola Wygasa domyślnie wynosi jeden rok od bieżącej daty.

    8. Wybierz ikonę kopiowania lub naciśnij Ctrl + C skopiuj adres URL elementu webhook. Następnie zapisz adres URL w bezpiecznej lokalizacji.

      Utwórz stronę webhook z wyróżnionym adresem URL.

      Ważne

      Po utworzeniu elementu webhook nie można ponownie pobrać adresu URL. Pamiętaj, aby skopiować i zarejestrować go tak jak powyżej.

    9. Wybierz OK, aby powrócić do strony Dodaj webhook.

    10. Na stronie Dodaj webhook wybierz Konfiguruj parametry i ustawienia uruchomienia, aby otworzyć stronę Parametry.

      Dodaj stronę webhook z wyróżnionymi parametrami.

    11. Przejrzyj stronę Parametry. Przykładowy element Runbook używany w tym artykule nie wymaga żadnych zmian. Wybierz OK, aby powrócić do strony Dodaj webhook.

    12. Na stronie Dodawanie webhooka wybierz opcję Utwórz. Webhook został utworzony i powrócisz do strony Runbooka Przegląd.

Użyj webhooka

W tym przykładzie użyto polecenia cmdlet Invoke-WebRequest PowerShell, aby wysłać żądanie POST do nowego webhook.

Aby użyć webhooka, wykonaj następujące kroki:

  1. Przygotuj wartości do przekazania do runbooka jako treść wywołania webhooka. W przypadku stosunkowo prostych wartości można utworzyć skrypt w następujący sposób:

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

$body = ConvertTo-Json -InputObject $Names

  2. W przypadku większych zestawów możesz użyć pliku. Utwórz plik o nazwie names.json , a następnie wklej następujący kod:

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

    Zmień wartość zmiennej $file na rzeczywistą ścieżkę do pliku json przed uruchomieniem następujących poleceń programu PowerShell.

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

  3. Uruchom następujące polecenia programu PowerShell, aby wywołać element webhook przy użyciu interfejsu API REST.

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

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

    W celach ilustracyjnych dwa wywołania zostały wykonane dla dwóch różnych metod produkcji ciała. W przypadku środowiska produkcyjnego użyj tylko jednej metody. Dane wyjściowe powinny wyglądać podobnie jak poniżej (wyświetlane są tylko jedno dane wyjściowe):

    Dane wyjściowe z wywołania webhooka.

    Klient otrzymuje jeden z następujących kodów zwrotnych z żądania POST.

    Code Tekst Opis
    202 Zaakceptowano Żądanie zostało zaakceptowane, a runbook został pomyślnie dodany do kolejki.
    400 Nieprawidłowe żądanie Żądanie nie zostało zaakceptowane z jednego z następujących powodów:
    • Webhook wygasł.
    • Webhook jest wyłączony.
    • Token w adresie URL jest nieprawidłowy.
    404 Nie znaleziono Żądanie nie zostało zaakceptowane z jednego z następujących powodów:
    • Nie znaleziono webhooks.
    • Nie znaleziono Runbooka.
    • Nie znaleziono konta.
    500 Wewnętrzny błąd serwera Adres URL był prawidłowy, ale wystąpił błąd. Prześlij ponownie żądanie.

    Zakładając, że żądanie zakończy się pomyślnie, odpowiedź elementu webhook zawiera identyfikator zadania w formacie JSON, jak pokazano poniżej. Zawiera on jeden identyfikator zadania, ale format JSON umożliwia potencjalne przyszłe ulepszenia.

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

  4. Polecenie cmdlet programu PowerShell Get-AzAutomationJobOutput będzie używane do uzyskania danych wyjściowych. Można również skorzystać z interfejsu API Azure Automation.

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

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

    Po wyzwoleniu elementu Runbook utworzonego w poprzednim kroku zostanie utworzone zadanie, a dane wyjściowe powinny wyglądać podobnie do następujących:

    Wynik z zadania webhook.

Aktualizuj webhook

Kiedy webhook jest tworzony, ma okres ważności 10 lat, po czym automatycznie wygasa. Po wygaśnięciu elementu webhook nie można go ponownie uaktywnić. Można go usunąć tylko i ponownie utworzyć. Możesz przedłużyć ważność webhooka, który nie stracił jeszcze ważności. Aby rozszerzyć webhook, wykonaj następujące kroki:

  1. Przejdź do runbooka, który zawiera webhook.
  2. W obszarze Zasoby, wybierz Webhooks, a następnie webhook, który chcesz rozszerzyć.
  3. Na stronie Webhook wybierz nową datę i godzinę wygaśnięcia, a następnie wybierz Zapisz.

Przejrzyj wywołanie interfejsu API Webhook - Aktualizacja i polecenie cmdlet programu PowerShell Set-AzAutomationWebhook, aby rozważyć inne możliwe modyfikacje.

Czyszczenie zasobów

Oto przykłady usuwania webhooka z runbooka Automation.

  • Za pomocą programu PowerShell można użyć polecenia cmdlet Remove-AzAutomationWebhook jak pokazano poniżej. Nie są zwracane żadne dane wyjściowe.

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

  • Korzystając z REST, można użyć interfejsu API Webhook - Delete, jak pokazano poniżej.

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

    Wynik StatusCode : 200 oznacza pomyślne usunięcie.

Tworzenie elementu Runbook i elementu webhook przy użyciu szablonu usługi ARM

Webhooki automatyzacji można również tworzyć przy użyciu szablonów Azure Resource Manager. Ten przykładowy szablon tworzy konto usługi Automation, cztery elementy Runbook i element webhook dla nazwanego elementu Runbook.

Aby utworzyć webhook przy użyciu szablonu ARM, wykonaj następujące kroki:

  1. Utwórz plik o nazwie webhook_deploy.json , a następnie wklej następujący kod:

    {
    "$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. Poniższy przykładowy kod programu PowerShell umożliwia wdrożenie szablonu z komputera. Podaj odpowiednią wartość dla zmiennych, a następnie wykonaj skrypt.

    $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

    Uwaga

    Ze względów bezpieczeństwa identyfikator URI jest zwracany tylko przy pierwszym wdrożeniu szablonu.

Następne kroki

  • Last updated on