Azure Data Factory の Web アクティビティWeb activity in Azure Data Factory

適用対象: はいAzure Data Factory はいAzure Synapse Analytics (プレビュー) APPLIES TO: yesAzure Data Factory yesAzure Synapse Analytics (Preview)

Web アクティビティを使用すると、Data Factory パイプラインからカスタム REST エンドポイントを呼び出すことができます。Web Activity can be used to call a custom REST endpoint from a Data Factory pipeline. このアクティビティで使用したり、アクセスしたりするデータセットやリンクされたサービスを渡すことができます。You can pass datasets and linked services to be consumed and accessed by the activity.

注意

Web アクティビティは、自己ホスト型統合ランタイムを利用することで、プライベート仮想ネットワークでホストされる URL の呼び出しでもサポートされています。Web Activity is supported for invoking URLs that are hosted in a private virtual network as well by leveraging self-hosted integration runtime. 統合ランタイムでは、URL エンドポイントへの通信経路が必要です。The integration runtime should have a line of sight to the URL endpoint.

構文Syntax

{
   "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"
         }
      ]
   }
}

型のプロパティType properties

プロパティProperty 説明Description 使用できる値Allowed values 必須Required
namename Web アクティビティの名前Name of the web activity StringString はいYes
typetype WebActivity に設定する必要があります。Must be set to WebActivity. StringString はいYes
methodmethod ターゲット エンドポイント用の Rest API メソッド。Rest API method for the target endpoint. 文字列 をオンにします。String.

サポートされている型"GET"、"POST"、"PUT"Supported Types: "GET", "POST", "PUT"
はいYes
urlurl ターゲット エンドポイントおよびパスTarget endpoint and path 文字列 (または文字列の resultType を含む式)。String (or expression with resultType of string). エンドポイントからの応答がない場合、アクティビティは 1 分でタイムアウトになり、エラーが発生します。The activity will timeout at 1 minute with an error if it does not receive a response from the endpoint. はいYes
headersheaders 要求に送信されるヘッダー。Headers that are sent to the request. たとえば、要求で言語と種類を設定するには、次のようにします。"headers" : { "Accept-Language": "en-us", "Content-Type": "application/json" }For example, to set the language and type on a request: "headers" : { "Accept-Language": "en-us", "Content-Type": "application/json" }. 文字列 (または文字列の resultType を含む式)String (or expression with resultType of string) あり。Content-type ヘッダーが必要です。Yes, Content-type header is required. "headers":{ "Content-Type":"application/json"}
bodybody エンドポイントに送信されるペイロードを表します。Represents the payload that is sent to the endpoint. 文字列 (または文字列の resultType を含む式)。String (or expression with resultType of string).

要求ペイロードのスキーマ」セクションにある要求ペイロードのスキーマを参照してください。See the schema of the request payload in Request payload schema section.
POST/PUT メソッドには必須です。Required for POST/PUT methods.
認証authentication エンドポイントを呼び出すために使用される認証方法。Authentication method used for calling the endpoint. サポートされるタイプは "Basic" または "ClientCertificate" です。Supported Types are "Basic, or ClientCertificate." 詳細については、「認証」セクションを参照してください。For more information, see Authentication section. 認証が必要ない場合は、このプロパティを除外します。If authentication is not required, exclude this property. 文字列 (または文字列の resultType を含む式)String (or expression with resultType of string) いいえNo
datasetsdatasets エンドポイントに渡されるデータセットの一覧。List of datasets passed to the endpoint. データセット参照の配列。Array of dataset references. 空の配列にすることができます。Can be an empty array. はいYes
linkedServiceslinkedServices エンドポイントに渡されるリンクされたサービスの一覧。List of linked services passed to endpoint. リンクされたサービスの参照の配列。Array of linked service references. 空の配列にすることができます。Can be an empty array. はいYes
connectViaconnectVia データ ストアに接続するために使用される統合ランタイムThe integration runtime to be used to connect to the data store. データ ストアがプライベート ネットワーク内にある場合、Azure Integration Runtime またはセルフホステッド統合ランタイムを使用できます。You can use the Azure integration runtime or the self-hosted integration runtime (if your data store is in a private network). このプロパティが指定されていない場合は、サービスでは、既定の Azure Integration Runtime が使用されます。If this property isn't specified, the service uses the default Azure integration runtime. 統合ランタイム参照。The integration runtime reference. いいえNo

注意

Web アクティビティが呼び出す REST エンドポイントは、型 JSON の応答を返す必要があります。REST endpoints that the web activity invokes must return a response of type JSON. エンドポイントからの応答がない場合、アクティビティは 1 分でタイムアウトになり、エラーが発生します。The activity will timeout at 1 minute with an error if it does not receive a response from the endpoint.

次の表に、JSON コンテンツの要件を示します。The following table shows the requirements for JSON content:

値の型Value type 要求本文Request body 応答本文Response body
JSON オブジェクトJSON object サポートSupported サポートSupported
JSON 配列JSON array サポートされていますSupported
(バグがあるため、現在、JSON 配列は動作していません。(At present, JSON arrays don't work as a result of a bug. 修正が進行中です)。A fix is in progress.)
サポートされていないUnsupported
JSON 値JSON value サポートされていますSupported サポートされていないUnsupported
非 JSON 型Non-JSON type サポートされていないUnsupported サポートされていないUnsupported

認証Authentication

Web アクティビティでサポートされている認証の種類を以下に示します。Below are the supported authentication types in the web activity.

なしNone

認証が必要ない場合は、"authentication" プロパティを含めないでください。If authentication is not required, do not include the "authentication" property.

BasicBasic

基本認証で使用するユーザー名とパスワードを指定します。Specify user name and password to use with the basic authentication.

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

クライアント証明書Client certificate

PFX ファイルの Base64 でエンコードされたコンテンツとパスワードを指定します。Specify base64-encoded contents of a PFX file and the password.

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

マネージド IDManaged Identity

データ ファクトリのマネージド ID を使用してアクセス トークンの要求対象となるリソース URI を指定します。Specify the resource uri for which the access token will be requested using the managed identity for the data factory. Azure Resource Management API を呼び出すには、https://management.azure.com/ を使用します。To call the Azure Resource Management API, use https://management.azure.com/. マネージド ID が機能する方法について詳しくは、Azure リソースのマネージド ID の概要に関するページを参照してください。For more information about how managed identities works see the managed identities for Azure resources overview page.

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

注意

ご利用のデータ ファクトリが git リポジトリを使用して構成されている場合、基本認証またはクライアント証明書認証を使用するには、ご自分の資格情報を Azure Key Vault に格納する必要があります。If your data factory is configured with a git repository, you must store your credentials in Azure Key Vault to use basic or client certificate authentication. Azure Data Factory では、git にパスワードは保存されません。Azure Data Factory doesn't store passwords in git.

要求ペイロードのスキーマRequest payload schema

POST/PUT メソッドを使用する場合、body プロパティは、エンドポイントに送信されるペイロードを表します。When you use the POST/PUT method, the body property represents the payload that is sent to the endpoint. そのペイロードの一部としてリンクされたサービスやデータセットを渡すことができます。You can pass linked services and datasets as part of the payload. ペイロードのスキーマを次に示します。Here is the schema for the payload:

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

Example

この例では、パイプライン内の Web アクティビティが REST エンドポイントを呼び出します。In this example, the web activity in the pipeline calls a REST end point. Azure SQL リンクされたサービスと Azure SQL データセットがエンドポイントに渡されます。It passes an Azure SQL linked service and an Azure SQL dataset to the endpoint. REST エンドポイントは、Azure SQL 接続文字列を使用して論理 SQL サーバーに接続し、SQL サーバーのインスタンスの名前を返します。The REST end point uses the Azure SQL connection string to connect to the logical SQL server and returns the name of the instance of SQL server.

パイプラインの定義Pipeline definition

{
    "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"
            }
        }
    }
}

パイプライン パラメーターの値Pipeline parameter values

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

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


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

次のステップNext steps

Data Factory でサポートされている他の制御フロー アクティビティを参照してください。See other control flow activities supported by Data Factory: