Azure Data Factory の Webhook アクティビティ

[アーティクル]
10/20/2023

適用対象: Azure Data Factory Azure Synapse Analytics

ヒント

企業向けのオールインワン分析ソリューション、Microsoft Fabric の Data Factory をお試しください。 Microsoft Fabric は、データ移動からデータサイエンス、リアルタイム分析、ビジネスインテリジェンス、レポートまで、あらゆるものをカバーしています。無料で新しい試用版を開始する方法について説明します。

Webhook アクティビティを使用すると、カスタムコードでパイプラインの実行を制御できます。 Webhook アクティビティを使用すると、コードでエンドポイントを呼び出して、コールバック URL を渡すことができます。パイプラインでは、次のアクティビティに進む前に、コールバックが呼び出されるまで実行が待機されます。

重要

Webhook アクティビティでは、エラー状態とカスタムメッセージをアクティビティとパイプラインに戻すことができるようになりました。 reportStatusOnCallBack を true に設定し、コールバックペイロードに StatusCode と Error を含めます。詳細については、「その他のメモ」セクションを参照してください。

UI を使用して Webhook アクティビティを作成する

パイプライン内で Webhook アクティビティを使用するには、次の手順を実行します。

パイプラインの [アクティビティ] ペイン内で Webhook を検索し、Webhook アクティビティをパイプラインキャンバスにドラッグします。
キャンバス上で新しいWebhook アクティビティ (まだ選択されていない場合)、その [設定] タブの順に選択して、その詳細を編集します。
Webhook の URL を指定します。これには、リテラル URL 文字列、または動的な式、関数、システム変数、または他のアクティビティからの出力の任意の組み合わせを使用できます。要求と共に送信されるその他の詳細を指定します。
アクティビティからの出力を他のアクティビティへの入力として使用し、宛先アクティビティで動的コンテンツがサポートされている任意の場所で出力を参照します。

構文


{
    "name": "MyWebHookActivity",
    "type": "WebHook",
    "typeProperties": {
        "method": "POST",
        "url": "<URLEndpoint>",
        "headers": {
            "Content-Type": "application/json"
        },
        "body": {
            "key": "value"
        },
        "timeout": "00:10:00",
        "reportStatusOnCallBack": false,
        "authentication": {
            "type": "ClientCertificate",
            "pfx": "****",
            "password": "****"
        }
    }
}

型のプロパティ

プロパティ	説明	使用できる値	必須
name	Webhook アクティビティの名前。	String	はい
type	"WebHook" に設定する必要があります。	String	はい
method	ターゲットエンドポイント用の REST API メソッド。	文字列をオンにします。サポートされている型は "POST" です。	はい
url	ターゲットエンドポイントおよびパス。	文字列または resultType 値の文字列が含まれる式。	はい
headers	要求に送信されるヘッダー。言語と種類を要求に設定する場合の例を次に示します。`"headers" : { "Accept-Language": "en-us", "Content-Type": "application/json" }`	文字列または resultType 値の文字列が含まれる式。	はい。 `"headers":{ "Content-Type":"application/json"}` のような `Content-Type` ヘッダーが必要です。
body	エンドポイントに送信されるペイロードを表します。	有効な JSON または resultType 値の JSON が含まれる式。要求ペイロードのスキーマについては、「要求ペイロードのスキーマ」を参照してください。	はい
認証	エンドポイントを呼び出すために使用される認証方法。サポートされる種類は "Basic" および "ClientCertificate" です。詳細については、認証に関するページをご覧ください。認証が必要ない場合は、このプロパティを除外します。	文字列または resultType 値の文字列が含まれる式。	いいえ
timeout	callBackUri で指定されたコールバックが呼び出されるまでのアクティビティの待機時間。既定値は 10 分 ("00:10:00") です。値の TimeSpan 形式は d.hh:mm:ss です。	String	いいえ
[Report status on callback] (コールバックで状態を報告する)	ユーザーが Webhook アクティビティの失敗した状態を報告できるようにします。	ブール型	いいえ

認証

Webhook アクティビティでは、次の認証の種類がサポートされます。

なし

認証が必要ない場合は、authentication プロパティを含めないでください。

Basic

基本認証で使用するユーザー名とパスワードを指定します。

"authentication":{
   "type":"Basic",
   "username":"****",
   "password":"****"
}

クライアント証明書

PFX ファイルの Base64 でエンコードされたコンテンツとパスワードを指定します。

"authentication":{
   "type":"ClientCertificate",
   "pfx":"****",
   "password":"****"
}

マネージド ID

データファクトリまたは Synapse ワークスペースのマネージド ID を使用して、アクセストークンの要求対象となるリソース URI を指定します。 Azure Resource Management API を呼び出すには、https://management.azure.com/ を使用します。マネージド ID が機能する方法について詳しくは、Azure リソースのマネージド ID の概要に関するページを参照してください。

"authentication": {
    "type": "MSI",
    "resource": "https://management.azure.com/"
}

Note

ご利用のサービスが Git リポジトリを使用して構成されている場合、基本認証またはクライアント証明書認証を使用するには、ご自分の資格情報を Azure Key Vault に格納する必要があります。このサービスでは、パスワードは Git に格納されません。

その他のメモ

このサービスでは、URL エンドポイントに送信される本文に追加のプロパティ callBackUri が渡されます。サービスは、指定されたタイムアウト値の前にこの URI が呼び出されることを想定しています。この URI が呼び出されない場合、アクティビティは状態 'TimedOut' で失敗します。

Webhook アクティビティが失敗するのは、カスタムエンドポイントへの呼び出しが失敗した場合です。任意のエラーメッセージをコールバックの本文に追加して、その後のアクティビティで使用できます。

毎回の REST API 呼び出しでは、エンドポイントが 1 分以内に応答しない場合、クライアントがタイムアウトします。この動作は、HTTP の標準的なベストプラクティスです。この問題を解決するには、202 パターンを実装します。現在のケースでは、エンドポイントで 202 (受理) が返され、クライアントでポーリングが行われます。

要求時の 1 分間のタイムアウトは、アクティビティタイムアウトとは関係ありません。後者は、callbackUri によって指定されたコールバックを待機するために使用されます。

コールバック URI に戻される本文は、有効な JSON である必要があります。 Content-Type ヘッダーを application/json に設定します。

[Report status on callback](コールバックで状態を報告する) プロパティを使用する場合は、コールバックを作成するときに本文に次のコードを追加する必要があります。

{
    "Output": {
        // output object is used in activity output
        "testProp": "testPropValue"
    },
    "Error": {
        // Optional, set it when you want to fail the activity
        "ErrorCode": "testErrorCode",
        "Message": "error message to show in activity error"
    },
    "StatusCode": "403" // when status code is >=400, activity is marked as failed
}

次のサポートされる制御フローアクティビティを確認します。