Azure Data Factory と Azure Synapse Analytics の Web アクティビティ

[アーティクル]
09/25/2024

適用対象: Azure Data Factory Azure Synapse Analytics

ヒント

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

Web アクティビティを使用すると、Azure Data Factory または Synapse パイプラインからカスタム REST エンドポイントを呼び出すことができます。このアクティビティで使用したり、アクセスしたりするデータセットやリンクされたサービスを渡すことができます。

Note

Web アクティビティは、自己ホスト型統合ランタイムを利用することで、プライベート仮想ネットワークでホストされる URL の呼び出しでもサポートされています。統合ランタイムでは、URL エンドポイントへの通信経路が必要です。

Note

サポートされている出力応答ペイロードの最大サイズは 4 MB です。

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

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

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

構文

{
   "name":"MyWebActivity",
   "type":"WebActivity",
   "typeProperties":{
      "method":"Post",
      "url":"<URLEndpoint>",
      "httpRequestTimeout": "00:01:00"
      "connectVia": {
          "referenceName": "<integrationRuntimeName>",
          "type": "IntegrationRuntimeReference"
      }
      "headers":{
         "Content-Type":"application/json"
      },
      "authentication":{
         "type":"ClientCertificate",
         "pfx":"****",
         "password":"****"
      },
      "datasets":[
         {
            "referenceName":"<ConsumedDatasetName>",
            "type":"DatasetReference",
            "parameters":{
               ...
            }
         }
      ],
      "linkedServices":[
         {
            "referenceName":"<ConsumedLinkedServiceName>",
            "type":"LinkedServiceReference"
         }
      ]
   }
}

型のプロパティ

プロパティ	説明	使用できる値	必須
name	Web アクティビティの名前	String	はい
type	WebActivity に設定する必要があります。	String	はい
method	ターゲットエンドポイント用の REST API メソッド。	文字列をオンにします。サポートされる種類: "GET"、"POST"、"PUT"、"PATCH"、"DELETE"	はい
url	ターゲットエンドポイントおよびパス	文字列 (または文字列の resultType を含む式)。エンドポイントからの応答がない場合、アクティビティは 1 分でタイムアウトになり、エラーが発生します。 httpRequestTimeout プロパティを更新して、この応答タイムアウトを最大 10 分に増やすことができます	はい
httpRequestTimeout	応答タイムアウト期間	hh:mm:ss 形式で、最大値は 00:10:00。明示的に指定されていない場合、既定値は 00:01:00	いいえ
headers	要求に送信されるヘッダー。たとえば、要求で言語と種類を設定するには、次のようにします。`"headers" : { "Accept-Language": "en-us", "Content-Type": "application/json" }`	文字列 (または文字列の resultType を含む式)	いいえ
body	エンドポイントに送信されるペイロードを表します。	文字列 (または文字列の resultType を含む式)。「要求ペイロードのスキーマ」セクションにある要求ペイロードのスキーマを参照してください。	POST/PUT/PATCH メソッドには必須です。 DELETE メソッドの場合は省略可能です。
認証	エンドポイントを呼び出すために使用される認証方法。サポートされる種類は、"基本、クライアント証明書、システム割り当てマネージド ID、ユーザー割り当てマネージド ID、サービスプリンシパル" です。詳細については、「認証」セクションを参照してください。認証が必要ない場合は、このプロパティを除外します。	文字列 (または文字列の resultType を含む式)	いいえ
turnOffAsync	HTTP 202 応答の応答ヘッダーの場所フィールドで HTTP GET の呼び出しを無効にするオプション。 true に設定すると、応答ヘッダーで指定された http の場所で HTTP GET の呼び出しが停止されます。 false に設定すると、http 応答ヘッダーで指定された場所で HTTP GET 呼び出しが引き続き呼び出されます。	指定できる値は false (既定値) と true です。	いいえ
disableCertValidation	サーバー側の証明書検証を削除します (標準 CA 証明書を使用しない信頼されたサーバーに接続している場合を除き、推奨されません)。	指定できる値は false (既定値) と true です。	いいえ
datasets	エンドポイントに渡されるデータセットの一覧。	データセット参照の配列。空の配列にすることができます。	はい
linkedServices	エンドポイントに渡されるリンクされたサービスの一覧。	リンクされたサービスの参照の配列。空の配列にすることができます。	はい
connectVia	データストアに接続するために使用される統合ランタイム。データストアがプライベートネットワーク内にある場合、Azure Integration Runtime またはセルフホステッド統合ランタイムを使用できます。このプロパティが指定されていない場合は、サービスでは、既定の Azure Integration Runtime が使用されます。	統合ランタイム参照。	いいえ

注意

Web アクティビティが呼び出す REST エンドポイントは、型 JSON の応答を返す必要があります。エンドポイントからの応答がない場合、アクティビティは 1 分でタイムアウトになり、エラーが発生します。非同期要求-応答パターンをサポートするエンドポイントの場合、Web アクティビティはタイムアウトせずに (最大 7 日間)、またはエンドポイントがジョブの完了を通知するまで待機し続けます。

次の表に、JSON コンテンツの要件を示します。

値の型	要求本文	応答本文
JSON オブジェクト	サポートされています	サポートされています
JSON 配列	をサポートするようになりました (バグがあるため、現在、JSON 配列は動作していません。修正が進行中です)	サポートされていない
JSON 値	サポートされています	サポートされていない
非 JSON 型	サポートされていない	サポートされていない

認証

Web アクティビティでサポートされている認証の種類を以下に示します。

なし

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

Basic

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

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

クライアント証明書

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

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

証明書は x509 証明書である必要があります。 PFX ファイルへの変換には、任意のユーティリティを使用できます。 base-64 エンコードには、次の PowerShell スニペットを使用できます。

$fileContentBytes = get-content 'enr.dev.webactivity.pfx' -AsByteStream

[System.Convert]::ToBase64String($fileContentBytes) | Out-File ‘pfx-encoded-bytes.txt’

マネージド ID

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

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

Note

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

サービスプリンシパル

クライアントシークレットのセキュリティで保護された文字列を使用して、テナント ID、サービスプリンシパル ID、およびサービスプリンシパルキーを指定します。

"authentication": {
            "type": "ServicePrincipal",
            "tenant": "your_tenant_id",
            "servicePrincipalId": "your_client_id",
            "servicePrincipalKey": {
                "type": "SecureString",
                "value": "your_client_secret"
            },
            "resource": "https://management.azure.com/"
}

要求ペイロードのスキーマ

POST/PUT メソッドを使用する場合、body プロパティは、エンドポイントに送信されるペイロードを表します。そのペイロードの一部としてリンクされたサービスやデータセットを渡すことができます。ペイロードのスキーマを次に示します。

{
    "body": {
        "myMessage": "Sample",
        "datasets": [{
            "name": "MyDataset1",
            "properties": {
                ...
            }
        }],
        "linkedServices": [{
            "name": "MyStorageLinkedService1",
            "properties": {
                ...
            }
        }]
    }
}

例

この例では、パイプライン内の Web アクティビティが REST エンドポイントを呼び出します。 Azure SQL リンクされたサービスと Azure SQL データセットがエンドポイントに渡されます。 REST エンドポイントは、Azure SQL 接続文字列を使用して論理 SQL サーバーに接続し、SQL サーバーのインスタンスの名前を返します。

パイプラインの定義

{
    "name": "<MyWebActivityPipeline>",
    "properties": {
        "activities": [
            {
                "name": "<MyWebActivity>",
                "type": "WebActivity",
                "typeProperties": {
                    "method": "Post",
                    "url": "@pipeline().parameters.url",
                    "headers": {
                        "Content-Type": "application/json"
                    },
                    "authentication": {
                        "type": "ClientCertificate",
                        "pfx": "*****",
                        "password": "*****"
                    },
                    "datasets": [
                        {
                            "referenceName": "MySQLDataset",
                            "type": "DatasetReference",
                            "parameters": {
                                "SqlTableName": "@pipeline().parameters.sqlTableName"
                            }
                        }
                    ],
                    "linkedServices": [
                        {
                            "referenceName": "SqlLinkedService",
                            "type": "LinkedServiceReference"
                        }
                    ]
                }
            }
        ],
        "parameters": {
            "sqlTableName": {
                "type": "String"
            },
            "url": {
                "type": "String"
            }
        }
    }
}

パイプラインパラメーターの値

{
    "sqlTableName": "department",
    "url": "https://adftes.azurewebsites.net/api/execute/running"
}

Web サービスのエンドポイントコード


[HttpPost]
public HttpResponseMessage Execute(JObject payload)
{
    Trace.TraceInformation("Start Execute");

    JObject result = new JObject();
    result.Add("status", "complete");

    JArray datasets = payload.GetValue("datasets") as JArray;
    result.Add("sinktable", datasets[0]["properties"]["typeProperties"]["tableName"].ToString());

    JArray linkedServices = payload.GetValue("linkedServices") as JArray;
    string connString = linkedServices[0]["properties"]["typeProperties"]["connectionString"].ToString();

    System.Data.SqlClient.SqlConnection sqlConn = new System.Data.SqlClient.SqlConnection(connString);

    result.Add("sinkServer", sqlConn.DataSource);

    Trace.TraceInformation("Stop Execute");

    return this.Request.CreateResponse(HttpStatusCode.OK, result);
}

サポートされている他の制御フローアクティビティを参照してください。

次の方法で共有

Azure Data Factory と Azure Synapse Analytics の Web アクティビティ

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

構文

型のプロパティ

認証

なし

Basic

クライアント証明書

マネージド ID

サービスプリンシパル

要求ペイロードのスキーマ

例

パイプラインの定義

パイプラインパラメーターの値

Web サービスのエンドポイントコード

フィードバック

その他のリソース

次の方法で共有

Azure Data Factory と Azure Synapse Analytics の Web アクティビティ

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

構文

型のプロパティ

認証

なし

Basic

クライアント証明書

マネージド ID

サービス プリンシパル

要求ペイロードのスキーマ

例

パイプラインの定義

パイプライン パラメーターの値

Web サービスのエンドポイント コード

関連するコンテンツ

フィードバック

その他のリソース

サービスプリンシパル

パイプラインパラメーターの値

Web サービスのエンドポイントコード