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

適用対象: Azure Data Factory Azure Synapse Analytics

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

注意

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

注意

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

構文

{
   "name":"MyWebActivity",
   "type":"WebActivity",
   "typeProperties":{
      "method":"Post",
      "url":"<URLEndpoint>",
      "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"
はい
url ターゲット エンドポイントおよびパス 文字列 (または文字列の resultType を含む式)。 エンドポイントからの応答がない場合、アクティビティは 1 分でタイムアウトになり、エラーが発生します。 はい
headers 要求に送信されるヘッダー。 たとえば、要求で言語と種類を設定するには、次のようにします。"headers" : { "Accept-Language": "en-us", "Content-Type": "application/json" } 文字列 (または文字列の resultType を含む式) あり。Content-type ヘッダーが必要です。 "headers":{ "Content-Type":"application/json"}
body エンドポイントに送信されるペイロードを表します。 文字列 (または文字列の resultType を含む式)。

要求ペイロードのスキーマ」セクションにある要求ペイロードのスキーマを参照してください。
POST/PUT メソッドには必須です。
認証 エンドポイントを呼び出すために使用される認証方法。 サポートされるタイプは "Basic" または "ClientCertificate" です。 詳細については、「認証」セクションを参照してください。 認証が必要ない場合は、このプロパティを除外します。 文字列 (または文字列の resultType を含む式) いいえ
datasets エンドポイントに渡されるデータセットの一覧。 データセット参照の配列。 空の配列にすることができます。 はい
linkedServices エンドポイントに渡されるリンクされたサービスの一覧。 リンクされたサービスの参照の配列。 空の配列にすることができます。 はい
connectVia データ ストアに接続するために使用される統合ランタイム。 データ ストアがプライベート ネットワーク内にある場合、Azure Integration Runtime またはセルフホステッド統合ランタイムを使用できます。 このプロパティが指定されていない場合は、サービスでは、既定の Azure Integration Runtime が使用されます。 統合ランタイム参照。 いいえ

注意

Web アクティビティが呼び出す REST エンドポイントは、型 JSON の応答を返す必要があります。 エンドポイントからの応答がない場合、アクティビティは 1 分でタイムアウトになり、エラーが発生します。

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

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

認証

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

なし

認証が必要ない場合は、"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/"
}

注意

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

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

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);
}

次のステップ

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