resources.webhooks.webhook 定義

[アーティクル]
04/16/2024

Webhook リソースを使用すると、パイプラインを外部サービスと統合してワークフローを自動化できます。

webhooks:
- webhook: string # Required as first property. Name of the webhook.
  connection: string # Required. Name of the connection. In case of offline webhook this will be the type of Incoming Webhook otherwise it will be the type of the webhook extension.
  type: string # Name of the webhook extension. Leave this empty if it is an offline webhook.
  filters: [ filter ] # List of trigger filters.

この定義を参照する定義: resources.webhooks

プロパティ

webhook 文字列。最初のプロパティとして必須。
Webhook の名前。使用できる値: [-_A-Za-z0-9]*

connection 文字列。必須。
接続の名前。オフライン Webhook の場合、これは受信 Webhook の種類になります。それ以外の場合は、Webhook 拡張機能の種類になります。

type 文字列。
Webhook 拡張機能の名前。オフライン Webhook の場合は、この値を空のままにします。

filtersresources.webhooks.webhook.filters。
トリガーフィルターの一覧。

例

基本的な例

パイプラインは次のように定義できます。

resources:
  webhooks:
    - webhook: WebHook
      connection: IncomingWH

steps:  
- script: echo ${{ parameters.WebHook.resource.message.title }}

Webhook を使用してパイプラインをトリガーするには、https://dev.azure.com/<org_name>/_apis/public/distributedtask/webhooks/<webhook_connection_name>?api-version=6.0-preview に POST 要求を行う必要があります。このエンドポイントは一般公開されており、承認は必要ありません。要求には、次の本文が必要です。

{
    "resource": {
        "message": {
            "title": "Hello, world!",
            "subtitle": "I'm using WebHooks!"
        }
    }
}

Webhook の要求本文からデータにアクセスする場合は、YAML が正しくない可能性があることに注意してください。たとえば、前のパイプラインでステップが - script: echo ${{ parameters.WebHook.resource.message }} を読み取り、Webhook を介してパイプラインをトリガーした場合、パイプラインは実行されません。これは、${{ parameters.WebHook.resource.message.title }} を次の JSON を含む message に置き換えるプロセスでは、生成された YAML が無効になるからです。

{
  "title": "Hello, world!",
  "subtitle": "I'm using WebHooks!"
}

生成された YAML が無効になるため、応答にキューに入れられるパイプラインはありません。

承認されていないパイプラインの実行を防止する

Webhook を使用すると、organizationと webhook サービス接続の名前がわかっている限り、誰でもパイプラインをトリガーできます。

受信 Webhook サービス接続を作成するときに シークレット を定義することで、承認されていないパイプラインの実行を防ぐことができます。 Webhook の本文の SHA-1 チェックサムを含む HTTP ヘッダーの名前も指定する必要があります。

受信 Webhook REST API 呼び出しが承認されていることを確認するために、Azure Pipelines はシークレットをキーとして使用して、要求の本文の SHA-1 チェックサムを計算します。次に、要求ヘッダーで渡されたチェックサムと比較します。これにより、呼び出し元はシークレットを知っていることを証明します。

例を見てみましょう。という名前 IncomingWHの受信 Webhook サービス接続を構成したとします。シークレットはで secret、チェックサムはという名前 X-WH-Checksumの HTTP ヘッダーで送信されます。 Webhook リソースを定義するパイプラインがあるとします。

次の要求本文を使用してパイプラインをトリガーするとします。

{"resource":{"message":{"title":"Hello, world!","subtitle":"I'm using WebHooks!"}}}

これを行うには、に要求https://dev.azure.com/<org_name>/_apis/public/distributedtask/webhooks/IncomingWH?api-version=6.0-previewをPOST行い、の値750D33212D3AD4932CC390819050734831A0A94FをX-WH-Checksum持つヘッダーを追加する必要があります。ユーザー名 & パスワードやその他の種類の認証情報を指定する必要はありません。

Azure Pipelines は、キーとしてを使用して本文の SHA-1 チェックサムを secret 個別に計算し、同じ 750D33212D3AD4932CC390819050734831A0A94F 値を生成します。値が一致するため、呼び出しは承認され、パイプラインキューが続行されます。

ヘッダーの値を X-WH-Checksum 擬似コードでとして SHA1(secret).ComputeHash(requestBody)計算します。を使用できます。この目的のための NET の System.Security.Cryptography.HMACSHA1 クラス。

新しい行または空白による検証エラーを防ぐために、本文を最小化された形式で送信することをお勧めします。つまり、送信

{"resource":{"message":{"title":"Hello, world!","subtitle":"I'm using WebHooks!"}}}

( ではなく )

{
    "resource": {
        "message": {
            "title": "Hello, world!",
            "subtitle": "I'm using WebHooks!"
        }
    }
}

上記の 2 つの JSON オブジェクトは同じオブジェクトを表していますが、異なる SHA-1 チェックサムを生成します。これは、SHA-1 が文字列表現で計算されるためです。これは異なります。

こちらもご覧ください

リソースをパイプラインに追加する