웹후크에서 Runbook 시작

웹후크를 사용하면 외부 서비스는 단일 HTTP 요청을 통해 Azure Automation에서 특정 Runbook을 시작할 수 있습니다. 외부 서비스에는 Azure DevOps Services, GitHub, Azure Monitor 로그 및 사용자 지정 애플리케이션이 포함됩니다. 해당 서비스는 웹후크를 사용하여 전체 Azure Automation API를 구현하지 않고도 Runbook을 시작할 수 있습니다. Azure Automation에서 Runbook 시작에서 Runhook을 시작하는 다른 방법과 웹후크를 비교할 수 있습니다.

WebhooksOverview

웹후크가 포함된 TLS 1.2 이상에 대한 클라이언트 요구 사항을 이해하려면 Azure Automation용 TLS를 참조하세요.

웹후크 속성

다음 표에서는 Webhook에 대해 구성해야 하는 속성을 설명합니다.

속성 설명
속성 웹후크의 이름입니다. 클라이언트에 노출되지 않으므로 원하는 이름을 지정할 수 있습니다. Azure Automation에서 Runbook을 식별하는 용도로만 사용됩니다. 가장 좋은 방법은 webhook를 사용할 클라이언트와 관련된 이름을 지정하는 것입니다.
URL 웹후크의 URL입니다. 클라이언트가 웹후크에 연결된 Runbook을 시작하기 위해 HTTP POST로 호출하는 고유한 주소입니다. webhook를 만들 때 자동으로 생성됩니다. 사용자 지정 URL을 지정할 수 없습니다.

URL에는 타사 시스템이 추가 인증 없이 Runbook을 호출할 수 있는 보안 토큰이 포함됩니다. 따라서 비밀번호와 같은 URL을 처리해야 합니다. 보안상의 이유로 Azure Portal의 URL은 웹후크가 생성될 때만 볼 수 있습니다. 이 URL을 나중에 사용할 수 있도록 안전한 위치에 기록해 둡니다.
만료 날짜 더 이상 사용할 수 없는 웹후크의 만료 날짜입니다. 웹후크가 만료되지 않는 한 웹후크를 만든 후에 만료 날짜를 수정할 수 있습니다.
Enabled 웹후크를 만들 때 기본적으로 사용하도록 설정 되어 있는지 여부를 나타내는 설정입니다. 이 속성을 사용 안 함으로 설정하면 클라이언트가 웹후크를 사용할 수 없습니다. 웹후크를 만들 때 또는 만든 후 다른 시간에 이 속성을 설정할 수 있습니다.

웹후크가 Runbook을 시작할 때 사용되는 매개 변수

웹후크는 Runbook을 시작할 때 사용되는 Runbook 매개 변수 값을 정의할 수 있습니다. 웹후크에는 필수 Runbook 매개 변수 값이 포함되어야 하고 선택적 매개 변수 값이 포함될 수 있습니다. 웹후크에 구성된 매개 변수 값은 웹후크를 만든 후에도 수정할 수 있습니다. 단일 Runbook에 연결된 여러 웹후크는 각각 다른 Runbook 매개 변수 값을 사용할 수 있습니다. 클라이언트는 webhook를 사용하여 Runbook을 시작할 때 webhook에 정의된 매개 변수 값을 재정의할 수 없습니다.

클라이언트에서 데이터를 수신하기 위해 Runbook은 WebhookData라는 단일 매개 변수를 지원합니다. 이 매개 변수는 클라이언트가 POST 요청에 포함하는 데이터가 있는 개체를 정의합니다.

WebhookData 속성

WebhookData 매개 변수에는 다음 속성이 있습니다.

속성 설명
WebhookName 웹후크의 이름입니다.
RequestHeader 들어오는 POST 요청의 헤더를 포함한 PSCustomObject입니다.
RequestBody 들어오는 POST 요청의 본문입니다. 이 본문은 문자열, JSON, XML 또는 양식 인코딩과 같은 데이터 서식을 유지합니다. Runbook은 예상되는 데이터 형식으로 작동하도록 작성되어야 합니다.

WebhookData 매개 변수를 지원하는 데 필요한 웹후크 구성은 없으며, Runbook은 이를 수락할 필요가 없습니다. Runbook이 매개 변수를 정의하지 않을 경우 클라이언트에서 전송된 요청의 모든 세부 정보가 무시됩니다.

참고 항목

웹후크를 호출할 때 클라이언트는 호출이 실패하는 경우에 대비하여 항상 모든 매개 변수 값을 저장해야 합니다. 네트워크 중단 또는 연결 문제가 있는 경우 애플리케이션은 실패한 웹후크 호출을 검색할 수 없습니다.

웹후크를 만들 때 WebhookData의 값을 지정하는 경우 웹후크가 클라이언트 POST 요청의 데이터로 Runbook을 시작하면 재정의됩니다. 이는 애플리케이션에 요청 본문의 데이터가 포함되어 있지 않은 경우에도 마찬가지입니다.

웹후크 이외의 메커니즘을 사용하여 WebhookData를 정의하는 Runbook을 시작하는 경우 Runbook에서 인식하는 WebhookData 값을 제공할 수 있습니다. 이 값은 WebhookData 매개 변수와 동일한 속성을 가진 개체여야 하므로 Runbook이 웹후크에 의해 전달된 실제 WebhookData 개체에서 작동하는 것처럼 작동할 수 있습니다.

예를 들어 Azure Portal에서 다음 Runbook을 시작하고 테스트용으로 일부 샘플 웹후크 데이터를 전달하려면 데이터를 사용자 인터페이스의 JSON에 전달해야 합니다.

UI에서의 WebhookData 매개 변수

다음 Runbook 예제에서는 WebhookData에 대한 다음 속성을 정의하겠습니다.

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

이제 WebhookData 매개 변수에 대한 UI에서 다음 JSON 개체를 전달합니다. 캐리지가 있는 이 예제는 반환하고 줄 바꿈 문자는 웹후크에서 전달되는 형식과 일치합니다.

{"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 Automation은 Runbook 작업으로 모든 입력 매개 변수의 값을 기록합니다. 웹후크 요청의 클라이언트에서 제공된 입력이 기록되고 자동화 작업에 액세스할 수 있는 어느 사용자든 사용할 수 있음을 의미합니다. 따라서 webhook 호출에 중요한 정보를 포함할 때는 주의해야 합니다.

웹후크 보안

웹후크의 보안은 웹후크를 호출할 수 있는 보안 토큰을 포함하는 URL의 개인 정보에 의존합니다. Azure Automation은 올바른 URL로 설정되어 있는 경우에만 요청에 대한 인증을 수행하지 않습니다. 따라서 클라이언트는 요청의 유효성을 검사하는 대체 수단을 사용하지 않고 매우 중요한 작업을 수행하는 Runbook에 웹후크를 사용해서는 안 됩니다.

다음과 같은 전략을 고려해 보세요.

  • Runbook에 논리를 포함하여 웹후크에서 호출했는지 여부를 확인할 수 있습니다. Runbook이 WebhookData 매개 변수의 WebhookName 속성을 확인하도록 합니다. Runbook은 RequestHeaderRequestBody 속성에서 특정 정보를 찾아 추가로 유효성 검사를 수행할 수 있습니다.

  • Runbook이 웹후크 요청을 받았을 때 외부 조건의 유효성 검사를 일부 수행하도록 합니다. 예를 들어 GitHub 리포지토리에 대한 새 커밋이 있을 때마다 GitHub에 의해 호출되는 Runbook을 가정해 보겠습니다. 이 Runbook은 계속하기 전에 GitHub에 연결하여 새 커밋이 발생했는지 유효성 검사를 수행할 수 있습니다.

  • Azure Automation은 Azure 가상 네트워크 서비스 태그, 특히 GuestAndHybridManagement를 지원합니다. 서비스 태그를 사용하여 네트워크 보안 그룹 또는 Azure Firewall에서 네트워크 액세스 제어를 정의하고 가상 네트워크 내에서 웹후크를 트리거할 수 있습니다. 보안 규칙을 만들 때 특정 IP 주소 대신 서비스 태그를 사용합니다. 서비스 태그 이름 GuestAndHybridManagement를 규칙의 적절한 원본 또는 대상 필드에 지정하면 Automation 서비스에 대한 트래픽을 허용하거나 거부할 수 있습니다. 이 서비스 태그는 IP 범위를 특정 지역으로 제한하여 보다 세부적인 제어를 허용하는 기능을 지원하지 않습니다.

웹후크 만들기

참고 항목

PowerShell 7 Runbook에서 웹후크를 사용하는 경우 웹후크 입력 매개 변수를 잘못된 JSON으로 자동 변환합니다. 자세한 내용은 알려진 문제 - PowerShell 7.1(미리 보기)을 참조하세요. PowerShell 5 Runbook에서 웹후크를 사용하는 것이 좋습니다.

  1. 다음 코드를 사용하여 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!"
    }
    
  2. Azure Portal 또는 PowerShell 또는 REST API를 사용하여 웹후크를 만듭니다. 웹후크에는 게시된 Runbook이 필요합니다. 이 단계에서는 Azure Automation Runbook 만들기에서 만든 Runbook의 수정 버전을 사용합니다.

    1. Azure Portal에 로그인합니다.

    2. Azure Portal에서 Automation 계정으로 이동합니다.

    3. 프로세스 자동화에서 Runbook을 선택하여 Runbook 페이지를 엽니다.

    4. 목록에서 Runbook을 선택하여 Runbook 개요 페이지를 엽니다.

    5. 웹후크 추가를 선택하여 웹후크 추가 페이지를 엽니다.

      웹후크 추가가 강조 표시된 Runbook 개요 페이지입니다.

    6. 웹후크 추가 페이지에서 새 웹후크 만들기를 선택합니다.

      만들기가 강조 표시된 웹후크 페이지를 추가합니다.

    7. 웹후크의 이름을 입력합니다. 만료 필드의 만료 날짜는 현재 날짜로부터 1년으로 설정됩니다.

    8. 복사 아이콘을 클릭하거나 Ctrl + C를 눌러 웹후크 URL을 복사합니다. 그런 다음, URL을 안전한 위치에 저장합니다.

      URL이 강조 표시된 웹후크 페이지를 만듭니다.

      Important

      webhook를 만들고 나면 URL을 다시 검색할 수 없습니다. 위와 같이 복사하고 기록해야 합니다.

    9. 확인을 선택하여 웹후크 추가 페이지로 돌아갑니다.

    10. 웹후크 추가 페이지에서 매개 변수 구성 및 설정 실행을 선택하여 매개 변수 페이지를 엽니다.

      매개 변수가 강조 표시된 웹후크 추가 페이지

    11. 매개 변수 페이지를 검토합니다. 이 문서에서 사용된 Runbook 예의 경우 변경할 필요가 없습니다. 확인을 선택하여 웹후크 추가 페이지로 돌아갑니다.

    12. 웹후크 추가 페이지에서 만들기를 선택합니다. 웹후크가 생성되며 Runbook 개요 페이지로 돌아갑니다.


웹후크 사용

이 예제에서는 PowerShell cmdlet Invoke-WebRequest를 사용하여 POST 요청을 새 웹후크에 보냅니다.

  1. Runbook에 전달할 값을 웹후크 호출 본문으로 준비합니다. 비교적 간단한 값의 경우 다음과 같이 값을 스크립트할 수 있습니다.

    $Names  = @(
                @{ Name="Hawaii"},
                @{ Name="Seattle"},
                @{ Name="Florida"}
            )
    
    $body = ConvertTo-Json -InputObject $Names
    
  2. 큰 집합의 경우 파일을 사용할 수 있습니다. 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 
    
  3. 다음 PowerShell 명령을 실행하여 REST API를 사용해 웹후크를 호출합니다.

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

    설명하기 위해 본문을 생성하는 서로 다른 메서드 2개에 대한 호출 2개가 생성되었습니다. 프로덕션의 경우 메서드 하나만 사용합니다. 출력은 다음과 유사하게 표시되어야 합니다(출력 하나만 표시됨).

    웹후크 호출의 출력입니다.

    클라이언트는 POST 요청으로부터의 다음 반환 코드 중 하나를 받게 됩니다.

    코드 Text 설명
    202 수락됨 요청이 수락되었고 runbook에서 대기합니다.
    400 Bad Request 다음 이유 중 하나로 인해 요청이 수락되지 않았습니다.
    • webhook가 만료되었습니다.
    • webhook가 비활성화되었습니다.
    • URL의 토큰이 잘못되었습니다.
    404 Not Found 다음 이유 중 하나로 인해 요청이 수락되지 않았습니다.
    • 웹후크를 찾을 수 없습니다.
    • Runbook을 찾을 수 없습니다.
    • 계정을 찾을 수 없습니다.
    500 Internal Server Error URL은 유효했지만 오류가 발생했습니다. 요청을 다시 제출합니다.

    요청이 성공했다고 가정하면 웹후크 응답에는 다음과 같은 JSON 형식의 작업 ID가 포함됩니다. 단일 작업 ID를 포함하지만 잠재적인 이후 향상 기능에 대해 JSON 형식이 허용됩니다.

    {"JobIds":["<JobId>"]}
    
  4. PowerShell cmdlet Get-AzAutomationJobOutput을 사용하여 출력을 가져옵니다. Azure Automation API를 사용할 수도 있습니다.

    #isolate job ID
    $jobid = (ConvertFrom-Json ($response.Content)).jobids[0]
    
    # Get output
    Get-AzAutomationJobOutput `
        -AutomationAccountName $automationAccount `
        -Id $jobid `
        -ResourceGroupName $resourceGroup `
        -Stream Output
    

    이전 단계에서 만든 Runbook을 트리거하면 작업이 생성되고 출력은 다음과 유사하게 표시됩니다.

    웹후크 작업의 출력입니다.

웹후크 업데이트

웹후크를 만들면 유효 기간은 10년이며 그 후에는 자동으로 만료됩니다. 웹후크가 만료된 후에는 다시 활성화할 수 없습니다. 제거했다가 다시 만들기만 가능합니다. 만료 시간에 도달하지 않은 웹후크를 연장할 수 있습니다. 웹후크를 연장하려면 다음 단계를 수행합니다.

  1. 웹후크가 포함 된 Runbook으로 이동합니다.
  2. 리소스에서 웹후크를 선택한 다음, 연장하려는 웹후크를 선택합니다.
  3. 웹후크 페이지에서 새 만료 날짜와 시간을 선택한 다음, 저장을 선택합니다.

API 호출 웹후크 - 업데이트와 PowerShell cmdlet Set-AzAutomationWebhook를 검토하여 다른 가능한 수정 사항을 확인합니다.

리소스 정리

Automation Runbook에서 웹후크를 제거하는 예는 다음과 같습니다.

  • PowerShell을 사용하여 다음과 같이 Remove-AzAutomationWebhook cmdlet을 사용할 수 있습니다. 출력은 반환되지 않습니다.

    Remove-AzAutomationWebhook `
        -ResourceGroup $resourceGroup `
        -AutomationAccountName $automationAccount `
        -Name $psWebhook
    
  • REST를 사용하면 다음과 같이 REST 웹후크 - 삭제 API를 사용할 수 있습니다.

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

    StatusCode : 200 출력은 성공적으로 삭제되었음을 의미합니다.

ARM 템플릿을 사용하여 Runbook 및 웹후크 만들기

Azure Resource Manager 템플릿을 사용하여 Automation 웹후크를 만들 수도 있습니다. 이 샘플 템플릿은 명명된 Runbook에 대한 Automation 계정 하나, Runbook 4개 및 웹후크 하나를 만듭니다.

  1. 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]"
            }
        }
    }
    
  2. 다음 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는 처음 템플릿이 배포될 때만 반환됩니다.

다음 단계