webhook を使用した Azure Automation の Runbook の開始Starting an Azure Automation runbook with a webhook

Webhook を使用することにより、単一の HTTP 要求を通して Azure Automation で特定の Runbook を開始することができます。A webhook allows you to start a particular runbook in Azure Automation through a single HTTP request. これにより、Azure DevOps Services、GitHub、Azure Monitor ログなどの外部サービス、またはカスタム アプリケーションにおいて、Azure Automation API を使用した完全なソリューションを実装していなくても、Runbook を開始することができます。This allows external services such as Azure DevOps Services, GitHub, Azure Monitor logs, or custom applications to start runbooks without implementing a full solution using the Azure Automation API.
WebhooksOverviewWebhooksOverview

Azure Automation での Runbook を開始するYou can compare webhooks to other methods of starting a runbook in Starting a runbook in Azure Automation

注意

Webhook を使用して Python Runbook を開始することはできません。Using a webhook to start a Python runbook is not supported.

Webhook の詳細Details of a webhook

次のテーブルは、Webhook 用に構成する必要があるプロパティについて説明しています。The following table describes the properties that you must configure for a webhook.

プロパティProperty DescriptionDescription
NameName Webhook に使用する任意の名前を指定できます。これはクライアントには公開されません。You can provide any name you want for a webhook since this isn't exposed to the client. これはユーザーが Azure Automation の Runbook を識別する場合にのみ使用されます。It's only used for you to identify the runbook in Azure Automation.
ベスト プラクティスとして、webhook を使用するクライアントに関連した名前を webhook に付ける必要があります。As a best practice, you should give the webhook a name related to the client that uses it.
URLURL Webhook の URL は、クライアントが Webhook にリンクされた Runbook を開始するために HTTP POST で呼び出す一意のアドレスです。The URL of the webhook is the unique address that a client calls with an HTTP POST to start the runbook linked to the webhook. これは、Webhook を作成するときに自動的に生成されます。It's automatically generated when you create the webhook. カスタム URL を指定することはできません。You can't specify a custom URL.

この URL には、追加の認証なしで、サードパーティ製システムによる Runbook 呼び出しを可能にするためのセキュリティ トークンが含まれています。The URL contains a security token that allows the runbook to be invoked by a third-party system with no further authentication. その理由で、これはパスワードと同じように扱う必要があります。For this reason, it should be treated like a password. セキュリティ上の理由から、Webhook の作成時に Azure ポータルで表示できるのは URL だけです。For security reasons, you can only view the URL in the Azure portal at the time the webhook is created. 将来の使用に備えて、URL を安全な場所にメモしてください。Note the URL in a secure location for future use.
有効期限Expiration date 証明書のように、各 Webhook には有効期限があり、それ以降は使用できなくなります。Like a certificate, each webhook has an expiration date at which time it can no longer be used. この有効期限は、切れる前であれば、Webhook の作成後に変更できます。This expiration date can be modified after the webhook is created as long as the webhook isn't expired.
EnabledEnabled 既定では、Webhook は作成時に有効になります。A webhook is enabled by default when it's created. Disabled に設定した場合、クライアントはそれを使用できなくなります。If you set it to Disabled, then no client can use it. Enabled プロパティは、Webhook の作成時、または作成後はいつでも設定できます。You can set the Enabled property when you create the webhook or anytime once it's created.

parametersParameters

Webhook は、Runbook がその Webhook によって開始されたときに使用される Runbook のパラメーターの値を定義できます。A webhook can define values for runbook parameters that are used when the runbook is started by that webhook. Webhook には、Runbook の任意の必須パラメーターの値を含める必要があり、省略可能なパラメーターの値を含めることもできます。The webhook must include values for any mandatory parameters of the runbook and may include values for optional parameters. Webhook に対して構成されているパラメーター値は、Webhook の作成後であっても変更できます。A parameter value configured to a webhook can be modified even after creating the webhook. 1 つの Runbook にリンクされている複数の Webhook は、それぞれ異なるパラメーター値を使用することができます。Multiple webhooks linked to a single runbook can each use different parameter values.

Webhook を使用して Runbook を開始した場合、クライアントは Webhook で定義されているパラメーターの値をオーバーライドできません。When a client starts a runbook using a webhook, it can't override the parameter values defined in the webhook. クライアントからデータを受け取るために、Runbook が $WebhookData という名前の単一のパラメーターを受け入れることができます。To receive data from the client, the runbook can accept a single parameter called $WebhookData. このパラメーターの型は [object] で、これにはクライアントによって POST 要求に含められるデータが含まれます。This parameter is of a type [object] that contains data that the client includes in the POST request.

Webhookdata プロパティ

$WebhookData オブジェクトには、次のプロパティがあります。The $WebhookData object has the following properties:

プロパティProperty 説明Description
WebhookNameWebhookName Webhook の名前。The name of the webhook.
RequestHeaderRequestHeader 受信 POST 要求のヘッダーを含むハッシュ テーブル。Hash table containing the headers of the incoming POST request.
RequestBodyRequestBody 受信 POST 要求の本文。The body of the incoming POST request. 文字列、JSON、XML、フォームのエンコード済みデータなどの書式設定が保持されます。This retains any formatting such as string, JSON, XML, or form encoded data. 想定されるデータ形式を操作するには、Runbook を記述する必要があります。The runbook must be written to work with the data format that is expected.

$WebhookData パラメーターのサポートに必要な Webhook の構成はありません。また、これを受け入れるために Runbook は必要ありません。There's no configuration of the webhook required to support the $WebhookData parameter, and the runbook isn't required to accept it. Runbook がパラメーターを定義していない場合は、クライアントから送信された要求の詳細は無視されます。If the runbook doesn't define the parameter, then any details of the request sent from the client is ignored.

webhook の作成時に $WebhookData の値を指定した場合、クライアントの要求本文にデータが含まれていなくても、クライアントの POST 要求からのデータで webhook が Runbook を開始した時点でその値はオーバーライドされます。If you specify a value for $WebhookData when you create the webhook, that value is overridden when the webhook starts the runbook with the data from the client POST request, even if the client does not include any data in the request body. webhook 以外の方法を使用して $WebhookData が含まれる Runbook を開始する場合、Runbook で認識される $Webhookdata の値を指定することができます。If you start a runbook that has $WebhookData using a method other than a webhook, you can provide a value for $Webhookdata that is recognized by the runbook. この値は $Webhookdata と同じプロパティを持つオブジェクトにする必要があります。それにより、Runbook は、Webhook によって渡された実際の WebhookData を操作しているかのように適切な処理を実行できます。This value should be an object with the same properties as $Webhookdata so that the runbook can properly work with it as if it was working with actual WebhookData passed by a webhook.

たとえば、Azure portal から次の Runbook を開始するときにテスト用のサンプル WebhookData を渡す場合、WebhookData はオブジェクトであるため、UI に JSON として渡す必要があります。For example, if you are starting the following runbook from the Azure portal and want to pass some sample WebhookData for testing, since WebhookData is an object, it should be passed as JSON in the UI.

UI からの WebhookData パラメーター

次の Runbook で、WebhookData パラメーターに次のプロパティがあるとします。For the following runbook, if you have the following properties for the WebhookData parameter:

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

この場合は、次の JSON 値を WebhookData パラメーター用の UI に渡します。Then you would pass the following JSON value in the UI for the WebhookData parameter. 復帰文字と改行文字がある次の例は、webhook から渡される形式に対応します。The following example with the carriage returns and newline characters matches the format that is passed in from a 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 パラメーターを開始する

注意

すべての入力パラメーターの値は、Runbook のジョブに記録されます。The values of all input parameters are logged with the runbook job. つまり、Webhook の要求でクライアントから提供された入力はすべて記録され、Automation ジョブにアクセスできるすべてのユーザーが使用できます。This means that any input provided by the client in the webhook request will be logged and available to anyone with access to the automation job. このため、Webhook の呼び出しに機密情報を含める場合には注意する必要があります。For this reason, you should be cautious about including sensitive information in webhook calls.

セキュリティSecurity

webhook のセキュリティは、呼び出しを許可するセキュリティ トークンが含まれる URL のプライバシーに依存します。The security of a webhook relies on the privacy of its URL, which contains a security token that allows it to be invoked. 正しい URL に対して要求がなされる場合、Azure Automation はその要求に対してどの認証も実行しません。Azure Automation does not perform any authentication on the request as long as it is made to the correct URL. このため、要求を検証する他の方法を使用しない場合は、機密性の高い機能を実行する Runbook で Webhook を使用しないでください。For this reason, webhooks should not be used for runbooks that perform highly sensitive functions without using an alternate means of validating the request.

Runbook 内にロジックを含め、$WebhookData パラメーターの WebhookName プロパティを調べることによって、Webhook で呼び出されたことを判別できます。You can include logic within the runbook to determine that it was called by a webhook by checking the WebhookName property of the $WebhookData parameter. Runbook は、RequestHeader または RequestBody プロパティの特定の情報を探すことによって、追加の検証を実行できます。The runbook could perform further validation by looking for particular information in the RequestHeader or RequestBody properties.

別の方法として、Webhook 要求の受信時に外部条件のいくつかの検証を Runbook に実行させることです。Another strategy is to have the runbook perform some validation of an external condition when it received a webhook request. たとえば、GitHub リポジトリに新しいコミットがある場合は常に GitHub によって呼び出される Runbook について考えてみましょう。For example, consider a runbook that is called by GitHub whenever there's a new commit to a GitHub repository. Runbook は、新しいコミットが発生したことを検証するために、GitHub に接続してから、処理を続行することができます。The runbook might connect to GitHub to validate that a new commit had occurred before continuing.

Webhook の作成Creating a webhook

次の手順を使用して、Runbook にリンクされた新しい Webhook を Azure ポータルに作成します。Use the following procedure to create a new webhook linked to a runbook in the Azure portal.

  1. Azure portal の [Runbook] ページから、webhook がその詳細ページの表示を開始する Runbook をクリックします。From the Runbooks page in the Azure portal, click the runbook that the webhook starts to view its detail page. Runbook の [状態][発行済み] を確認します。Ensure the runbook Status is Published.

  2. ページの上部にある Webhook をクリックして、 [Webhook の追加] ページを開きます。Click Webhook at the top of the page to open the Add Webhook page.

  3. [新しい Webhook の作成] をクリックして、 [webhook の作成] ページを開きます。Click Create new webhook to open the Create webhook page.

  4. Webhook の名前有効期限、およびそれを有効にする必要があるかどうかを指定します。Specify a Name, Expiration Date for the webhook and whether it should be enabled. これらのプロパティの詳細については、「 Webhook の詳細 」を参照してください。See Details of a webhook for more information these properties.

  5. コピー アイコンをクリックし、Ctrl + C キーを押して Webhook の URL をコピーします。Click the copy icon and press Ctrl+C to copy the URL of the webhook. 次に、それを安全な場所に記録します。Then record it in a safe place. Webhook を作成したら、再度 URL を取得することはできません。Once you create the webhook, you cannot retrieve the URL again.

    Webhook URL

  6. [パラメーター] をクリックし、Runbook のパラメーターの値を指定します。Click Parameters to provide values for the runbook parameters. Runbook に必須のパラメーターがある場合、値を指定しない限り webhook を作成できません。If the runbook has mandatory parameters, then you are not able to create the webhook unless values are provided.

  7. [作成] をクリックして Webhook を作成します。Click Create to create the webhook.

Webhook の使用Using a webhook

Webhook を作成後に使用する場合、クライアント アプリケーションは Webhook の URL で HTTP POST を発行する必要があります。To use a webhook after it has been created, your client application must issue an HTTP POST with the URL for the webhook. webhook の構文は、次の形式になります。The syntax of the webhook is in the following format:

http://<Webhook Server>/token?=<Token Value>

クライアントは、POST 要求から次のリターン コードのいずれかを受け取ります。The client receives one of the following return codes from the POST request.

コードCode TextText 説明Description
202202 承認済みAccepted 要求が承認され、Runbook が正常にキューに入れられました。The request was accepted, and the runbook was successfully queued.
400400 正しくない要求Bad Request 次のいずれかの理由で要求が受け入れられませんでした。The request was not accepted for one of the following reasons:
  • webhook の有効期限が切れている。The webhook has expired.
  • webhook が無効になっている。The webhook is disabled.
  • URL 内のトークンが無効になっている。The token in the URL is invalid.
404404 見つかりませんNot Found 次のいずれかの理由で要求が受け入れられませんでした。The request was not accepted for one of the following reasons:
  • webhook が見つからない。The webhook was not found.
  • Runbook が見つからない。The runbook was not found.
  • アカウントが見つからない。The account was not found.
500500 内部サーバー エラーInternal Server Error URL は有効ですが、エラーが発生しました。The URL was valid, but an error occurred. 要求を再送信してください。Please resubmit the request.

要求が成功したと仮定した場合、Webhook の応答には、次のような JSON 形式のジョブ ID が含まれています。Assuming the request is successful, the webhook response contains the job ID in JSON format as follows. ここに含まれるジョブ ID は 1 つですが、JSON 形式は将来拡張できるようになっています。It will contain a single job ID, but the JSON format allows for potential future enhancements.

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

Runbook ジョブの完了時期と Webhook からの完了状態は、クライアントからは判別できません。The client can't determine when the runbook job completes or its completion status from the webhook. この情報は、Windows PowerShellAzure Automation API などの方法でジョブ ID を使用すると判別できます。It can determine this information using the job ID with another method such as Windows PowerShell or the Azure Automation API.

Webhook を更新するRenew a webhook

Webhook が作成された時点での有効期間は 1 年です。When a webhook is created, it has a validity time of one year. その日時が過ぎると、Webhook は自動的に期限切れになります。After that year time the webhook automatically expires. 有効期限が切れた Webhook は再アクティブ化できず、削除して作成しなおす必要があります。Once a webhook is expired it can't be reactivated, it must be removed and recreated. Webhook が有効期限に達していない場合は延長できます。If a webhook has not reached its expiry time, it can be extended.

Webhook を延長するには、その Webhook を含む Runbook に移動します。To extend a webhook, navigate to the runbook that contains the webhook. [リソース][Webhooks] を選択します。Select Webhooks under Resources. 延長する Webhook をクリックすると、 [Webhook] ページが開きます。Click the webhook that you want to extend, this action opens the Webhook page. 新しい有効期限の日付と時刻を選択して、 [保存] をクリックします。Choose a new expiration date and time and click Save.

サンプル RunbookSample runbook

次の例の Runbook では、webhook データを受け入れ、要求本文で指定された仮想マシンを起動します。The following sample runbook accepts the webhook data and starts the virtual machines specified in the request body. この Runbook をテストするには、Automation アカウントの Runbook で、 [+ Runbook の追加] をクリックします。To test this runbook, in your Automation Account under Runbooks, click + Add a runbook. Runbook を作成する方法がわからない場合は、Runbook の作成に関する記事をご覧ください。If you don't know how to create a runbook, see Creating a runbook.

param
(
    [Parameter (Mandatory = $false)]
    [object] $WebhookData
)



# If runbook was called from Webhook, WebhookData will not be null.
if ($WebhookData) {

    # Check header for message to validate request
    if ($WebhookData.RequestHeader.message -eq 'StartedbyContoso')
    {
        Write-Output "Header has required information"}
    else
    {
        Write-Output "Header missing required information";
        exit;
    }

    # Retrieve VM's from Webhook request body
    $vms = (ConvertFrom-Json -InputObject $WebhookData.RequestBody)

    # Authenticate to Azure by using the service principal and certificate. Then, set the subscription.

    Write-Output "Authenticating to Azure with service principal and certificate"
    $ConnectionAssetName = "AzureRunAsConnection"
    Write-Output "Get connection asset: $ConnectionAssetName"

    $Conn = Get-AutomationConnection -Name $ConnectionAssetName
            if ($Conn -eq $null)
            {
                throw "Could not retrieve connection asset: $ConnectionAssetName. Check that this asset exists in the Automation account."
            }
            Write-Output "Authenticating to Azure with service principal." 
            Add-AzureRmAccount -ServicePrincipal -Tenant $Conn.TenantID -ApplicationId $Conn.ApplicationID -CertificateThumbprint $Conn.CertificateThumbprint | Write-Output

        # Start each virtual machine
        foreach ($vm in $vms)
        {
            $vmName = $vm.Name
            Write-Output "Starting $vmName"
            Start-AzureRMVM -Name $vm.Name -ResourceGroup $vm.ResourceGroup
        }
}
else {
    # Error
    write-Error "This runbook is meant to be started from an Azure alert webhook only."
}

例をテストするTest the example

次の例では、Windows PowerShell を使用して Webhook で Runbook を開始します。The following example uses Windows PowerShell to start a runbook with a webhook. webhook は、HTTP 要求を実行できる任意の言語で使用できます。ここでは、例として Windows PowerShell を使用します。Any language that can make an HTTP request can use a webhook; Windows PowerShell is used here as an example.

Runbook では、要求の本文に JSON 形式の仮想マシン一覧が必要です。The runbook is expecting a list of virtual machines formatted in JSON in the body of the request. Runbook では、Webhook の呼び出し元が有効であることを検証するために定義されたメッセージがヘッダーに含まれることも検証されます。The runbook validates as well that the headers contain a defined message to validate the webhook caller is valid.

$uri = "<webHook Uri>"

$vms  = @(
            @{ Name="vm01";ResourceGroup="vm01"},
            @{ Name="vm02";ResourceGroup="vm02"}
        )
$body = ConvertTo-Json -InputObject $vms
$header = @{ message="StartedbyContoso"}
$response = Invoke-WebRequest -Method Post -Uri $uri -Body $body -Headers $header
$jobid = (ConvertFrom-Json ($response.Content)).jobids[0]

次の例は、WebhookDataRequestBody プロパティで Runbook に利用できる要求の本文を示しています。The following example shows the body of the request that is available to the runbook in the RequestBody property of WebhookData. 要求の本文に含まれていた形式が JSON であったため、この値の形式は JSON になります。This value is formatted as JSON because that was the format that was included in the body of the request.

[
    {
        "Name":  "vm01",
        "ResourceGroup":  "myResourceGroup"
    },
    {
        "Name":  "vm02",
        "ResourceGroup":  "myResourceGroup"
    }
]

次の図に、Windows PowerShell から送信される要求と、結果の応答を示します。The following image shows the request being sent from Windows PowerShell and the resulting response. ジョブ ID が応答から抽出され、文字列に変換されます。The job ID is extracted from the response and converted to a string.

Webhook ボタン

次の手順Next steps