從 Webhook 啟動 Runbook

發行項
10/16/2024

Webhook 可讓外部服務在 Azure 自動化中，透過單一 HTTP 要求啟動特定的 Runbook。外部服務包括 Azure DevOps Services、GitHub、Azure 監視器記錄，以及自訂應用程式。此類服務可以使用 Webhook 來啟動 Runbook，而不需要實作完整的 Azure 自動化 API。您可以透過在 Azure 自動化中啟動 Runbook，比較 Webhook 與其他啟動 Runbook 的方法。

WebhooksOverview

如需了解使用 Webhook 之 TLS 1.2 或更新版本的用戶端需求，請參閱 Azure 自動化的 TLS 版本。

Webhook 屬性

下表描述您必須為 Webhook 設定的屬性。

屬性	描述
名稱	Webhook 的名稱。您可以提供任何想要的名稱，因為這並不會向用戶端公開。該名稱僅供您用來識別 Azure 自動化中的 Runbook。最佳做法是您給予 Webhook 的名稱應該與要使用它的用戶端相關。
URL	Webhook 的 URL。這是唯一性的位址，即用戶端用來呼叫 HTTP POST 以啟動連結至 Webhook 的 Runbook。當您建立 Webhook 時其會自動產生。您無法指定自訂 URL。 URL 包含可讓協力廠商系統不需進一步驗證即可叫用 Runbook 的安全性權杖。基於此原因，您應該將 URL 視為密碼。基於安全性原因，您僅能於 Webhook 建立時在 Azure 入口網站中檢視 URL。請在安全的位置記下 URL 以供日後使用。
到期日期	Webhook 的到期日，在此之後就無法再使用。您可以在 Webhook 建立後修改到期日，只要 Webhook 尚未過期即可。
已啟用	此設定表示在建立時預設是否啟用 Webhook。如果您將此屬性設定為 [停用]，則不會有任何用戶端可以使用 Webhook。您可以在建立 Webhook 時，或在其建立後的任何其他時間，設定此屬性。

Webhook 啟動 Runbook 時使用的參數

Webhook 可以定義 Runbook 啟動時所使用的 Runbook 參數值。 Webhook 必須包含任何強制 Runbook 參數的值，且可能包含選擇性的參數值。您可以修改設定至 Webhoook 的參數值，甚至是在建立 Webhook 之後也可以進行修改。多個 Webhook 連結至單一 Runbook 時，可以個別使用不同的 Runbook 參數值。當用戶端使用 Webhook 啟動 Runbook 時，其無法覆寫 Webhook 中定義的參數值。

若要從用戶端接收資料，Runbook 支援稱為 WebhookData 的單一參數。此參數會定義物件，其中包含用戶端在 POST 要求中所包含的資料。

WebhookData 屬性

WebhookData 參數具有下列屬性：

屬性	說明
WebhookName	Webhook 的名稱。
RequestHeader	包含傳入 POST 要求標頭的 PSCustomObject。
RequestBody	傳入 POST 要求的本文。此本文會保留任何資料格式設定 (例如字串、JSON、XML 或表單編碼)。 Runbook 必須撰寫用來搭配預期的資料格式。

支援 WebhookData 參數不需要 Webhook 的設定，且不需要 Runbook 就可以加以接受。若 Runbook 並未定義參數，則會忽略從用戶端所傳送要求的任何詳細資料。

注意

呼叫 Webhook 時，用戶端應該一律儲存任何參數值，以防呼叫失敗。如果發生網路中斷或連線問題，應用程式將無法擷取失敗的 Webhook 呼叫。

如果您在建立 Webhook 時指定 WebhookData 的值，當 Webhook 使用來自用戶端 POST 要求的資料來啟動 Runbook 時，就會加以覆寫。即使應用程式未在要求本文中包含任何資料，也會發生這種情況。

如果您使用 Webhook 以外的機制來啟動定義 WebhookData 的 Runbook，您可以針對 Runbook 可辨識的 WebhookData 提供值。此值應該是與 WebhookData 參數具有相同屬性的物件，如此一來 Runbook 即可正確地與其一起運作，就像是其使用 Webhook 所傳遞的實際 WebhookData 物件一般。

例如，如果要從 Azure 入口網站啟動下列 Runbook，並想要傳遞一些範例 Webhook 資料進行測試，您必須在使用者介面中以 JSON 傳遞該資料。

來自 UI 的 WebhookData 參數

針對下一個 Runbook 範例，讓我們定義 WebhookData 的下列屬性：

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

現在，我們會在 UI 中傳遞 WebhookData 參數的下列 JSON 物件。此範例使用歸位字元與新行字元，符合從 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]"}

啟動來自 UI 的 WebhookData 參數

注意

Azure 自動化會使用 Runbook 作業記錄所有輸入參數的值。因此，任何由用戶端在 Webhook 要求中提供的輸入會加以記錄，並可讓任何有自動化作業存取權的人使用。基於這個原因，您在 Webhook 呼叫中包含機密資訊時應該特別謹慎。

Webhook 安全性

Webhook 的安全性仰賴其 URL 的隱私權，其中包含允許叫用 Webhook 的安全性權杖。只要針對正確的 URL 進行要求，Azure 自動化就不會對要求執行任何驗證。基於此原因，若不使用驗證要求的替代方式時，您的用戶端不應使用執行高度敏感性作業的 Webhook。

請考慮下列策略：

您可以在 Runbook 中包含邏輯，以判斷 Runbook 是否由 Webhook 呼叫。讓 Runbook 檢查 WebhookData 參數的 WebhookName 屬性。 Runbook 可以透過尋找 RequestHeader 或 RequestBody 屬性中的特定資訊來執行進一步的驗證。
當 Runbook 收到 Webhook 要求時，使其執行某些外部條件的驗證。例如，請考慮每當 GitHub 存放庫出現新的認可時，就會由 GitHub 呼叫的 Runbook。該 Runbook 在繼續執行之前，可能會先連線到 GitHub，以驗證新的認可已經出現。
Azure 自動化支援 Azure 虛擬網路服務標籤，特別是 GuestAndHybridManagement。您可以使用服務標籤來定義網路安全性群組或 Azure 防火牆的網路存取控制，並從虛擬網路內觸發 Webhook。建立安全性規則時，可以使用服務標籤取代特定的 IP 位址。在規則的適當來源或目的地欄位中指定服務標籤名稱 GuestAndHybridManagement，即可允許或拒絕自動化服務的流量。此服務標籤未支援藉由將 IP 範圍限制為特定區域來允許更細微的控制。

建立 Webhook

注意

當您搭配 PowerShell 7 Runbook 使用 Webhook 時，會將 Webhook 輸入參數自動轉換成不正確的 JSON。如需詳細資訊，請參閱已知問題 - PowerShell 7.1 (預覽)。建議您搭配 PowerShell 5 Runbook 使用 Webhook。

使用下列程式碼來建立 PowerShell Runbook：

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

使用 Azure 入口網站建立 Webhook，或是 PowerShell 或 REST API。 Webhook 需要已發佈的 Runbook。本逐步解說會使用從建立 Azure 自動化 Runbook 所建立的已修改 Runbook 版本。
1. 登入 Azure 入口網站。
2. 在 Azure 入口網站中，瀏覽至您的自動化帳戶。
3. 在 [程序自動化] 底下選取 [Runbook] 來開啟 Runbook 頁面。
4. 從清單中選取您的 Runbook，以開啟 [Runbook 概觀] 頁面。
5. 選取 [新增 Webhook] 以開啟 [新增 Webhook] 頁面。
6. 在 [新增 Webhook] 頁面上，選取 [建立新的 Webhook]。
7. 在 Webhook 的 [名稱] 中輸入。 [到期] 欄位的到期日預設為目前日期起的一年。
8. 按一下複製圖示，或按 Ctrl + C 以複製 Webhook 的 URL。然後將 URL 儲存到安全的位置。
  
  重要
  
  一旦您建立 Webhook，即無法再次擷取 URL。請確定您複製並記錄為上述內容。
9. 選取 [確定] 返回 [新增 Webhook] 頁面。
10. 從 [新增 Webhook] 頁面中，選取 [設定參數並執行設定] 以開啟 [參數] 頁面。
11. 檢閱 [參數] 頁面。針對本文中使用的範例 Runbook，不需要進行變更。選取 [確定] 返回 [新增 Webhook] 頁面。
12. 從 [新增 Webhook] 頁面，選取 [建立]。 Webhook 隨即建立，然後您會返回 Runbook [概觀] 頁面。
1. 確認您已安裝最新版本的 PowerShell Az Module。
2. 使用 Connect-AzAccount cmdlet 以互動方式登入 Azure 並遵循指示。
```
# Sign in to your Azure subscription
$sub = Get-AzSubscription -ErrorAction SilentlyContinue
if(-not($sub))
{
    Connect-AzAccount
}
```
3. 使用 New-AzAutomationWebhook Cmdlet 來建立適用於自動化 Runbook 的 Webhook。為變數提供適當的值，然後執行指令碼。
```
# 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
```
  輸出將為類似以下的 URL：https://ad7f1818-7ea9-4567-b43a.webhook.wus.azure-automation.net/webhooks?token=uTi69VZ4RCa42zfKHCeHmJa2W9fd
4. 您也可以使用 PowerShell Cmdlet Get-AzAutomationWebhook 來驗證 Webhook。
```
Get-AzAutomationWebhook `
    -ResourceGroup $resourceGroup `
    -AutomationAccountName $automationAccount `
    -Name $psWebhook
```
PUT 命令記載於 Webhook - 建立或更新。此範例會使用 PowerShell Cmdlet Invoke-RestMethod 來傳送 PUT 要求。
1. 建立名為 webhook.json 的檔案，然後貼上以下程式碼：
```
{
"name": "RestWebhook",
"properties": {
    "isEnabled": true,
    "expiryTime": "2022-03-29T22:18:13.7002872Z",
    "runbook": {
    "name": "runbookName"
    }
}
}
```
  在執行之前，請以 Runbook 的實際名稱來修改 runbook:name 屬性的值。如需這些屬性的詳細資訊，請檢閱 Webhook 屬性。
2. 確認您已安裝最新版本的 PowerShell Az Module。
3. 使用 Connect-AzAccount cmdlet 以互動方式登入 Azure 並遵循指示。
```
# Sign in to your Azure subscription
$sub = Get-AzSubscription -ErrorAction SilentlyContinue
if(-not($sub))
{
    Connect-AzAccount
}
```
4. 為變數提供適當的值，然後執行指令碼。
```
# 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. 執行下列指令碼以取得存取權杖。如果您的存取權杖已過期，則必須重新執行指令碼。
```
# 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. 執行下列指令碼，以使用 REST API 建立 Webhook。
```
# 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
```
  輸出為類似以下的 URL：https://ad7f1818-7ea9-4567-b43a.webhook.wus.azure-automation.net/webhooks?token=uTi69VZ4RCa42zfKHCeHmJa2W9fd
7. 您也可以使用 Webhook - Get，來擷取其名稱所識別的 Webhook。您可以執行下列 PowerShell 命令：
```
$response = Invoke-RestMethod -Uri $restURI -Method GET -Headers $authHeader
$response | ConvertTo-Json
```

使用 Webhook

此範例會使用 PowerShell Cmdlet Invoke-WebRequest，將 POST 要求傳送至新的 Webhook。

準備將值傳遞至 Runbook 做為 Webhook 呼叫的主體。對於相對簡單的值，您可以撰寫值指令碼，如下所示：

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

$body = ConvertTo-Json -InputObject $Names

對於較大的集合，您可能要使用檔案。建立名為 names.json 的檔案，然後貼上下列程式碼：
```
[
    { "Name": "Hawaii" },
    { "Name": "Florida" },
    { "Name": "Seattle" }
]
```
在執行下列 PowerShell 命令之前，請先使用 json 檔案的實際路徑來變更變數 $file 的值。
```
# Revise file path with actual path
$file = "path\names.json"
$bodyFile = Get-Content -Path $file 
```

執行下列 PowerShell 命令，以使用 REST API 來呼叫 Webhook。

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

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

為達到說明之目的，已針對產生主體的兩種不同方法進行兩次呼叫。針對生產環境，請僅使用一種方法。輸出看起來應該如下所示 (只會顯示一個輸出)：

Webhook 呼叫的輸出。

用戶端會從 POST 要求中接收下列其中一個傳回碼。

代碼	Text	描述
202	已接受	已接受要求，且 Runbook 已經成功排入佇列。
400	不正確的要求	基於下列其中一個原因而不接受此要求： Webhook 已過期。 Webhook 已停用。 URL 中的權杖無效。
404	找不到	基於下列其中一個原因而不接受此要求：找不到 Webhook。找不到 Runbook。找不到帳戶。
500	內部伺服器錯誤	URL 有效，但發生錯誤。請重新提交要求。

假設要求成功，Webhook 會回應包含 JSON 格式的作業識別碼，如下所示。其會包含單一作業識別碼，但是 JSON 格式允許未來可能的增強功能。

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

將使用 PowerShell Cmdlet Get-AzAutomationJobOutput 來取得輸出。您也可以使用 Azure 自動化 API。

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

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

當您觸發上一個步驟中所建立的 Runbook 時，其會建立作業，且輸出看起來應該如下：

Webhook 作業的輸出。

更新 Webhook

建立 Webhook 時，其有效時間週期為 10 年，之後就會自動到期。一旦 Webhook 過期，您就無法加以重新啟用。您只能加以移除後再重新建立。您可以將尚未達到到期時間的 Webhook 延長。若要擴充 Webhook，請執行下列步驟。

請瀏覽至包含 Webhook 的 Runbook。
在 [資源] 底下，選取 [Webhook]，然後選取您想要延長的 Webhook。
在 [Webhook] 頁面中，選擇新的到期日期和時間，然後選取 [儲存]。

檢閱 API 呼叫 Webhook - Update 和 PowerShell cmdlet Set-AzAutomationWebhook，以取得其他可能的修改。

清除資源

以下為從自動化 Runbook 中移除 Webhook 的範例。

使用 PowerShell 時，可以使用 Remove-AzAutomationWebhook Cmdlet，如下所示。不會傳回任何輸出。

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

使用 REST 時，可以使用 REST Webhook - Delete API，如下所示。
```
Invoke-WebRequest -Method Delete -Uri $restURI -Headers $authHeader
```
StatusCode : 200 的輸出表示成功刪除。

使用 ARM 範本建立 Runbook 和 Webhook

也可以使用 Azure Resource Manager 範本來建立自動化 Webhook。此範例範本會建立自動化帳戶、4 個 Runbook，以及具名 Runbook 的 Webhook。

建立名為 webhook_deploy.json 的檔案，然後貼上下列程式碼：

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

下列 PowerShell 程式碼範例會從您的電腦部署範本。為變數提供適當的值，然後執行指令碼。

$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

注意

基於安全性理由，只會在第一次部署範本時傳回 URI。

下一步

若要從警示觸發 Runbook，請參閱使用警示來觸發 Azure 自動化 Runbook。

共用方式為