Share via


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

適用対象: 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 アクティビティを使用するには、次の手順を実行します。

  1. パイプラインの [アクティビティ] ペイン内で Web を検索し、Web アクティビティをパイプライン キャンバスにドラッグします。

  2. キャンバス上で新しい Web アクティビティ (まだ選択されていない場合)、その [設定] タブの順に選択して、その詳細を編集します。

    Shows the UI for a Web activity.

  3. URL を指定します。これには、リテラル URL 文字列、または動的な式、関数システム変数、または他のアクティビティからの出力の任意の組み合わせを使用できます。 要求と共に送信されるその他の詳細を指定します。

  4. アクティビティからの出力を他のアクティビティへの入力として使用し、宛先アクティビティで動的コンテンツがサポートされている任意の場所で出力を参照します。

構文

{
   "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 に格納されません。

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

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

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