Uruchamianie elementu runbook z poziomu elementu webhook

  • Artykuł

Element webhook umożliwia usłudze zewnętrznej uruchomienie określonego elementu runbook w usłudze Azure Automation za pośrednictwem pojedynczego żądania HTTP. Usługi zewnętrzne obejmują usługi Azure DevOps Services i GitHub, dzienniki usługi Azure Monitor oraz aplikacje niestandardowe. Taka usługa może używać elementu webhook do uruchamiania elementu Runbook bez implementowania pełnego interfejsu API usługi Azure Automation. Elementy webhook można porównać z innymi metodami uruchamiania elementu Runbook w temacie Uruchamianie elementu Runbook w usłudze Azure Automation.

Elementy webhookPrzegląd

Aby zrozumieć wymagania klienta dotyczące protokołu TLS 1.2 lub nowszego z elementami webhook, zobacz TLS for Azure Automation (Protokół TLS dla usługi Azure Automation).

Właściwości elementu webhook

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 ona tylko do identyfikowania elementu runbook w usłudze Azure Automation. Najlepszym rozwiązaniem jest nadanie elementowi webhook nazwy powiązanej z klientem, który go używa.
Adres URL Adres URL elementu webhook. Jest to unikatowy adres, który klient wywołuje za pomocą żądania HTTP POST, aby uruchomić element runbook połączony z elementem webhook. Jest on generowany automatycznie podczas tworzenia elementu webhook. Nie można określić niestandardowego adresu URL.

Adres URL zawiera token zabezpieczający, który umożliwia systemowi innej firmy wywoływanie elementu runbook bez 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 witrynie Azure Portal 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 elementu webhook, 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ł.
Enabled (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 elementu webhook lub innego czasu 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 element Runbook przy użyciu elementu webhook, nie może zastąpić wartości parametrów zdefiniowanych w elemecie webhook.

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ści opis
Nazwa elementu webhook Nazwa elementu webhook.
RequestHeader PSCustomObject zawierający nagłówki przychodzącego żądania POST.
RequestBody Treść przychodzącego żądania POST. Ta treść przechowuje dowolne formatowanie danych, takie jak ciąg, JSON, XML lub zakodowane w formie. Element Runbook musi być zapisywany w celu pracy z oczekiwanym formatem danych.

Nie ma konfiguracji elementu webhook wymaganego do obsługi parametru WebhookData , a element Runbook nie jest wymagany do zaakceptowania go. 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 problem z awarią sieci lub połączeniem, aplikacja nie może pobrać nieudanych wywołań elementu webhook.

Jeśli określisz wartość elementu WebhookData webhook podczas tworzenia elementu webhook, zostanie on zastąpiony, gdy element webhook uruchamia element 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 element Runbook, który definiuje WebhookData się przy użyciu mechanizmu innego niż element webhook, możesz podać wartość rozpoznawaną WebhookData przez element Runbook. Ta wartość powinna być obiektem o tych samych właściwościach co parametr, WebhookData aby element Runbook mógł z nim pracować tak samo, jak działa z rzeczywistymi WebhookData obiektami przekazywanymi przez element webhook.

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

Parametr WebhookData z interfejsu użytkownika

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

  • Nazwa elementu webhook: 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 . W tym przykładzie z powrotami karetki i znakami nowego wiersza pasuje do formatu przekazywanego z elementu 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]"}

Uruchamianie parametru WebhookData z poziomu interfejsu użytkownika

Uwaga

Usługa Azure Automation rejestruje wartości wszystkich parametrów wejściowych za pomocą zadania elementu 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ść w zakresie dołączania poufnych informacji w wywołaniach elementu webhook.

Zabezpieczenia elementu webhook

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

Rozważ zastosowanie następujących strategii:

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

  • Element Runbook przeprowadza weryfikację warunku zewnętrznego po odebraniu żądania elementu webhook. Rozważmy na przykład element Runbook, który jest wywoływany przez usługę GitHub za każdym razem, gdy istnieje nowe zatwierdzenie w repozytorium GitHub. Element Runbook może połączyć się z usługą GitHub, aby sprawdzić, czy nowe zatwierdzenie miało miejsce przed kontynuowaniem.

  • Usługa Azure Automation obsługuje tagi usługi sieci wirtualnej platformy Azure, w szczególności GuestAndHybridManagement. Tagi usług umożliwiają definiowanie mechanizmów kontroli dostępu do sieci w sieciowych grupach zabezpieczeń lub w usłudze Azure Firewall i wyzwalanie elementów webhook z 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.

Tworzenie elementu webhook

Uwaga

Gdy używasz elementu webhook z elementem Runbook programu PowerShell 7, automatycznie konwertuje parametr wejściowy elementu webhook na nieprawidłowy kod JSON. Aby uzyskać więcej informacji, zobacz Znane problemy — PowerShell 7.1 (wersja zapoznawcza). Zalecamy używanie elementu webhook z elementem Runbook programu PowerShell 5.

  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 witryny Azure Portal lub programu PowerShell lub interfejsu API REST. Element webhook wymaga opublikowanego elementu Runbook. W tym przewodniku użyto zmodyfikowanej wersji elementu Runbook utworzonego na podstawie polecenia Tworzenie elementu Runbook usługi Azure Automation.

    1. Zaloguj się w witrynie Azure Portal.

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

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

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

    5. Wybierz pozycję Dodaj element webhook , aby otworzyć stronę Dodawanie elementu webhook .

      Strona przeglądu elementu Runbook z wyróżnionym pozycją Dodaj element webhook.

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

      Dodaj stronę elementu webhook z wyróżnioną pozycją Utwórz.

    7. Wprowadź w polu Nazwa elementu webhook. Data wygaśnięcia pola Wygasa domyślnie do jednego roku z bieżącej daty.

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

      Strona elementu webhook Creaye 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 przycisk OK , aby powrócić do strony Dodawanie elementu webhook .

    10. Na stronie Dodawanie elementu webhook wybierz pozycję Konfiguruj parametry i ustawienia uruchamiania, aby otworzyć stronę Parametry.

      Dodaj stronę elementu webhook z wyróżnionymi parametrami.

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

    12. Na stronie Dodawanie elementu webhook wybierz pozycję Utwórz. Element webhook zostanie utworzony i powrócisz do strony Przegląd elementu Runbook.

Korzystanie z elementu webhook

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

  1. Przygotuj wartości, aby przekazać element runbook jako treść wywołania elementu webhook. 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 elementu webhook.

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

    Kod Text opis
    202 Zaakceptowano Żądanie zostało zaakceptowane, a element Runbook został pomyślnie w kolejce.
    400 Nieprawidłowe żądanie Żądanie nie zostało zaakceptowane z jednego z następujących powodów:
    • Element webhook wygasł.
    • Element 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 można odnaleźć elementu webhook.
    • Nie znaleziono elementu Runbook.
    • 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 pobierania danych wyjściowych. Można również użyć interfejsu API usługi 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:

    Dane wyjściowe z zadania elementu webhook.

Aktualizacja elementu webhook

Podczas tworzenia element webhook ma okres ważności 10 lat, po którym automatycznie wygaśnie. Po wygaśnięciu elementu webhook nie można go ponownie uaktywnić. Można go usunąć tylko i ponownie utworzyć. Ważność elementu webhook, który nie osiągnął czasu wygaśnięcia, można przedłużyć. Aby rozszerzyć element webhook, wykonaj następujące kroki.

  1. Przejdź do elementu runbook zawierającego element webhook.
  2. W obszarze Zasoby wybierz pozycję Elementy webhook, a następnie element webhook, który chcesz rozszerzyć.
  3. Na stronie Elementu webhook wybierz nową datę i godzinę wygaśnięcia, a następnie wybierz pozycję Zapisz.

Przejrzyj element Webhook wywołania interfejsu API — aktualizacja i polecenie cmdlet programu PowerShell Set-AzAutomationWebhook , aby uzyskać inne możliwe modyfikacje.

Czyszczenie zasobów

Oto przykłady usuwania elementu webhook z elementu Runbook usługi 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

  • Za pomocą interfejsu REST element webhook REST — usuwanie interfejsu API można użyć, jak pokazano poniżej.

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

    Dane wyjściowe StatusCode : 200 oznaczają pomyślne usunięcie.

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

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

  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