Azure Data Factory または Azure Synapse Analytics を使用して HTTP エンドポイントからデータをコピーする
- [アーティクル]
-
-
適用対象: Azure Data Factory Azure Synapse Analytics
この記事では、Azure Data Factory および Azure Synapse で Copy アクティビティを使用して、HTTP エンドポイントからデータをコピーする方法について説明します。 この記事は、Copy アクティビティの概要を説明する Copy アクティビティに関する記事に基づいています。
この HTTP コネクタ、REST コネクタおよび Web テーブル コネクタの違いは次のとおりです。
- REST コネクタでは、具体的には RESTful API からのデータのコピーがサポートされます。
- HTTP コネクタでは一般的に、HTTP エンドポイントからデータを取得します (たとえば、ファイルをダウンロードします)。 REST コネクタが使用可能になる前に、HTTP コネクタを使用して RESTful API からデータをコピーする場合があります。これはサポートされますが、REST コネクタと比べると機能は低くなります。
- Web テーブル コネクタでは、HTML Web ページからテーブルの内容を抽出します。
この HTTP コネクタは、次の機能でサポートされます。
① Azure 統合ランタイム ② セルフホステッド統合ランタイム
ソースおよびシンクとしてサポートされているデータ ストアの一覧については、「サポートされているデータ ストア」を参照してください。
この HTTP コネクタは、以下のために使用できます。
- HTTP の GET または POST メソッドを使用して、HTTP/S エンドポイントからデータを取得する。
- 次の認証のいずれかを使用してデータを取得する: Anonymous、Basic、Digest、Windows、ClientCertificate。
- HTTP 応答をそのままコピーするか、サポートされているファイル形式と圧縮コーデックを使用して解析する。
ヒント
HTTP コネクタを構成する前に、データ取得のために HTTP 要求をテストするには、ヘッダーおよび本文の要件に関する API 仕様を確認してください。 Visual Studio、PowerShell の Invoke-RestMethod、Web ブラウザーなどのツールを使用して検証を行うことができます。
データ ストアがオンプレ ミスネットワーク、Azure 仮想ネットワーク、または Amazon Virtual Private Cloud 内にある場合は、それに接続するようセルフホステッド統合ランタイムを構成する必要があります。
データ ストアがマネージド クラウド データ サービスである場合は、Azure Integration Runtime を使用できます。 ファイアウォール規則で承認されている IP にアクセスが制限されている場合は、Azure Integration Runtime の IP を許可リストに追加できます。
また、Azure Data Factory のマネージド仮想ネットワーク統合ランタイム機能を使用すれば、セルフホステッド統合ランタイムをインストールして構成しなくても、オンプレミス ネットワークにアクセスすることができます。
Data Factory によってサポートされるネットワーク セキュリティ メカニズムやオプションの詳細については、「データ アクセス戦略」を参照してください。
パイプラインでコピー アクティビティを実行するには、次のいずれかのツールまたは SDK を使用します。
UI を使用して HTTP ソースのリンク サービスを作成する
次の手順を使用して、Azure portal UI で HTTP ソースのリンク サービスを作成します。
Azure Data Factory または Synapse ワークスペースの [管理] タブに移動し、[リンクされたサービス] を選択して、[新規] をクリックします。
HTTP を検索し、HTTP コネクタを選択します。
サービスの詳細を構成し、接続をテストして、新しいリンク サービスを作成します。
以下のセクションでは、HTTP コネクタに固有のエンティティの定義に使用できるプロパティについて詳しく説明します。
HTTP のリンクされたサービスでは、次のプロパティがサポートされます。
プロパティ |
内容 |
必須 |
type |
type プロパティを HttpServer に設定する必要があります。 |
はい |
url |
Web サーバーへのベース URL |
はい |
enableServerCertificateValidation |
HTTP エンドポイントに接続するときに、サーバーの TLS/SSL 証明書の検証を有効にするかどうかを指定します。 HTTPS サーバーが自己署名証明書を使用している場合は、このプロパティを false に設定します。 |
いいえ (既定値は true です)。 |
authenticationType |
認証の種類を指定します。 使用できる値は、Anonymous、Basic、Digest、Windows、ClientCertificate です。 authHeader プロパティで認証ヘッダーを追加で構成することもできます。 このような認証の種類のその他のプロパティと JSON サンプルについては、この表の後のセクションを参照してください。 |
はい |
authHeaders |
追加の認証用 HTTP 要求ヘッダー。 たとえば、API キー認証を使うには、認証の種類として "匿名" を選択し、ヘッダーに API キーを指定します。 |
いいえ |
connectVia |
データ ストアに接続するために使用される Integration Runtime。 詳細については、「前提条件」セクションを参照してください。 指定されていない場合は、既定の Azure Integration Runtime が使用されます。 |
いいえ |
基本、ダイジェスト、または Windows 認証の使用
authenticationType プロパティを Basic、Digest、または Windows に設定します。 前のセクションで説明した汎用的なプロパティに加えて、次のプロパティを指定します。
プロパティ |
内容 |
必要 |
userName |
HTTP エンドポイントにアクセスするために使用するユーザー名。 |
はい |
password |
ユーザー (userName 値) のパスワード。 安全に保存するには、このフィールドを SecureString 型としてマークします。 Azure Key Vault に格納されているシークレットを参照することもできます。 |
はい |
例
{
"name": "HttpLinkedService",
"properties": {
"type": "HttpServer",
"typeProperties": {
"authenticationType": "Basic",
"url" : "<HTTP endpoint>",
"userName": "<user name>",
"password": {
"type": "SecureString",
"value": "<password>"
}
},
"connectVia": {
"referenceName": "<name of Integration Runtime>",
"type": "IntegrationRuntimeReference"
}
}
}
ClientCertificate 認証を使用するには、authenticationType プロパティを ClientCertificate に設定します。 前のセクションで説明した汎用的なプロパティに加えて、次のプロパティを指定します。
プロパティ |
内容 |
必須 |
embeddedCertData |
Base64 でエンコードされた証明書データ。 |
embeddedCertData または certThumbprint のいずれかを指定します。 |
certThumbprint |
セルフホステッド統合ランタイム マシンの証明書ストアにインストールされている証明書の拇印。 セルフホステッド型の統合ランタイムが connectVia プロパティで指定されている場合にのみ適用されます。 |
embeddedCertData または certThumbprint のいずれかを指定します。 |
password |
証明書に関連付けられているパスワード。 安全に保存するには、このフィールドを SecureString 型としてマークします。 Azure Key Vault に格納されているシークレットを参照することもできます。 |
いいえ |
認証に certThumbprint を使用し、証明書がローカル コンピューターの個人用ストアにインストールされている場合は、セルフホステッド統合ランタイムに読み取りアクセス許可を付与します。
- Microsoft 管理コンソール (MMC) を開きます。 ローカル コンピューターを対象とする [証明書] スナップインを追加します。
- [証明書]>[個人] を展開し、 [証明書] を選択します。
- 個人用ストアの証明書を右クリックし、 [すべてのタスク]>[秘密キーの管理] の順に選択します。
- [セキュリティ] タブで、証明書に対する読み取りアクセス権を使用して Integration Runtime Host Service (DIAHostService) を実行しているユーザー アカウントを追加します。
- HTTP コネクタは、信頼できる証明書のみを読み込みます。 自己署名証明書または統合されていない CA 発行の証明書を使用している場合、信頼を有効にするには、次のいずれかのストアに証明書もインストールする必要があります。
- 信頼されたユーザー
- [サード パーティ ルート証明機関]
- 信頼されたルート証明機関
例 1: certThumbprint の使用
{
"name": "HttpLinkedService",
"properties": {
"type": "HttpServer",
"typeProperties": {
"authenticationType": "ClientCertificate",
"url": "<HTTP endpoint>",
"certThumbprint": "<thumbprint of certificate>"
},
"connectVia": {
"referenceName": "<name of Integration Runtime>",
"type": "IntegrationRuntimeReference"
}
}
}
例 2: embeddedCertData の使用
{
"name": "HttpLinkedService",
"properties": {
"type": "HttpServer",
"typeProperties": {
"authenticationType": "ClientCertificate",
"url": "<HTTP endpoint>",
"embeddedCertData": "<Base64-encoded cert data>",
"password": {
"type": "SecureString",
"value": "password of cert"
}
},
"connectVia": {
"referenceName": "<name of Integration Runtime>",
"type": "IntegrationRuntimeReference"
}
}
}
また、組み込みの認証の種類と共に、認証用の要求ヘッダーを構成できます。
例: API キー認証の使用
{
"name": "HttpLinkedService",
"properties": {
"type": "HttpServer",
"typeProperties": {
"url": "<HTTP endpoint>",
"authenticationType": "Anonymous",
"authHeader": {
"x-api-key": {
"type": "SecureString",
"value": "<API key>"
}
}
},
"connectVia": {
"referenceName": "<name of Integration Runtime>",
"type": "IntegrationRuntimeReference"
}
}
}
データセットを定義するために使用できるセクションとプロパティの完全な一覧については、データセットに関する記事をご覧ください。
Azure Data Factory では次のファイル形式がサポートされます。 形式ベースの設定については、各記事を参照してください。
HTTP では、形式ベースのデータセットの location
設定において、次のプロパティがサポートされています。
プロパティ |
内容 |
必須 |
type |
データセットの location の type プロパティは、HttpServerLocation に設定する必要があります。 |
はい |
relativeUrl |
データを含むリソースへの相対 URL。 HTTP コネクタは、次の結合された URL からデータをコピーします。[URL specified in linked service][relative URL specified in dataset] |
いいえ |
注意
サポートされる HTTP 要求のペイロード サイズは約 500 KB です。 Web エンドポイントに渡すペイロード サイズが 500 KB を超える場合は、より小さなチャンクにペイロードをまとめることを検討してください。
例:
{
"name": "DelimitedTextDataset",
"properties": {
"type": "DelimitedText",
"linkedServiceName": {
"referenceName": "<HTTP linked service name>",
"type": "LinkedServiceReference"
},
"schema": [ < physical schema, optional, auto retrieved during authoring > ],
"typeProperties": {
"location": {
"type": "HttpServerLocation",
"relativeUrl": "<relative url>"
},
"columnDelimiter": ",",
"quoteChar": "\"",
"firstRowAsHeader": true,
"compressionCodec": "gzip"
}
}
}
このセクションでは、HTTP ソースでサポートされているプロパティの一覧を示します。
アクティビティの定義に利用できるセクションとプロパティの完全な一覧については、パイプラインに関する記事を参照してください。
Azure Data Factory では次のファイル形式がサポートされます。 形式ベースの設定については、各記事を参照してください。
HTTP では、形式ベースのコピー ソースの storeSettings
設定において、次のプロパティがサポートされています。
プロパティ |
内容 |
必須 |
type |
storeSettings の type プロパティは HttpReadSettings に設定する必要があります。 |
はい |
requestMethod |
HTTP メソッド。 使用できる値は、Get (既定値) と Post です。 |
いいえ |
additionalHeaders |
追加の HTTP 要求ヘッダー。 |
いいえ |
requestBody |
HTTP 要求の本文。 |
いいえ |
httpRequestTimeout |
HTTP 要求が応答を取得する際のタイムアウト (TimeSpan 値)。 この値は、応答データの読み取りのタイムアウトではなく、応答の取得のタイムアウトです。 既定値は 00:01:40 です。 |
いいえ |
maxConcurrentConnections |
アクティビティの実行中にデータ ストアに対して確立されたコンカレント接続数の上限。 コンカレント接続を制限する場合にのみ、値を指定します。 |
いいえ |
例:
"activities":[
{
"name": "CopyFromHTTP",
"type": "Copy",
"inputs": [
{
"referenceName": "<Delimited text input dataset name>",
"type": "DatasetReference"
}
],
"outputs": [
{
"referenceName": "<output dataset name>",
"type": "DatasetReference"
}
],
"typeProperties": {
"source": {
"type": "DelimitedTextSource",
"formatSettings":{
"type": "DelimitedTextReadSettings",
"skipLineCount": 10
},
"storeSettings":{
"type": "HttpReadSettings",
"requestMethod": "Post",
"additionalHeaders": "<header key: header value>\n<header key: header value>\n",
"requestBody": "<body for POST HTTP request>"
}
},
"sink": {
"type": "<sink type>"
}
}
}
]
プロパティの詳細については、Lookup アクティビティに関するページを参照してください。
注意
次のモデルは、下位互換性のために引き続きそのままサポートされます。 今後は、上記のセクションで説明した新しいモデルを使用することをお勧めします。作成 UI は、新しいモデルを生成するように切り替えられています。
プロパティ |
内容 |
必須 |
type |
データセットの type プロパティを HttpFile に設定する必要があります。 |
はい |
relativeUrl |
データを含むリソースへの相対 URL。 このプロパティが指定されていない場合は、リンクされたサービス定義に指定されている URL のみが使用されます。 |
いいえ |
requestMethod |
HTTP メソッド。 使用できる値は、Get (既定値) と Post です。 |
いいえ |
additionalHeaders |
追加の HTTP 要求ヘッダー。 |
いいえ |
requestBody |
HTTP 要求の本文。 |
いいえ |
format |
データを解析せずにデータを HTTP エンドポイントからそのまま取得し、ファイル ベースのストアにデータをコピーする場合は、入力と出力の両方のデータセット定義で format セクションをスキップします。
コピー中に HTTP 応答の内容を解析する場合に、サポートされるファイル形式の種類は、TextFormat、JsonFormat、AvroFormat、OrcFormat、ParquetFormat。 format の type プロパティをいずれかの値に設定します。 詳細については、JSON 形式、Text 形式、Avro 形式、Orc 形式、Parquet 形式の各セクションを参照してください。 |
いいえ |
compression |
データの圧縮の種類とレベルを指定します。 詳細については、サポートされるファイル形式と圧縮コーデックに関する記事を参照してください。
サポートされる種類は、GZip、Deflate、BZip2、ZipDeflate です。 サポートされるレベルは、Optimal と Fastest です。 |
いいえ |
注意
サポートされる HTTP 要求のペイロード サイズは約 500 KB です。 Web エンドポイントに渡すペイロード サイズが 500 KB を超える場合は、より小さなチャンクにペイロードをまとめることを検討してください。
例 1: Get メソッド (既定値) を使用する
{
"name": "HttpSourceDataInput",
"properties": {
"type": "HttpFile",
"linkedServiceName": {
"referenceName": "<HTTP linked service name>",
"type": "LinkedServiceReference"
},
"typeProperties": {
"relativeUrl": "<relative url>",
"additionalHeaders": "Connection: keep-alive\nUser-Agent: Mozilla/5.0\n"
}
}
}
例 2: Post メソッドを使用する
{
"name": "HttpSourceDataInput",
"properties": {
"type": "HttpFile",
"linkedServiceName": {
"referenceName": "<HTTP linked service name>",
"type": "LinkedServiceReference"
},
"typeProperties": {
"relativeUrl": "<relative url>",
"requestMethod": "Post",
"requestBody": "<body for POST HTTP request>"
}
}
}
プロパティ |
内容 |
必須 |
type |
コピー アクティビティのソースの type プロパティを HttpSource に設定する必要があります。 |
はい |
httpRequestTimeout |
HTTP 要求が応答を取得する際のタイムアウト (TimeSpan 値)。 この値は、応答データの読み取りのタイムアウトではなく、応答の取得のタイムアウトです。 既定値は 00:01:40 です。 |
いいえ |
例
"activities":[
{
"name": "CopyFromHTTP",
"type": "Copy",
"inputs": [
{
"referenceName": "<HTTP input dataset name>",
"type": "DatasetReference"
}
],
"outputs": [
{
"referenceName": "<output dataset name>",
"type": "DatasetReference"
}
],
"typeProperties": {
"source": {
"type": "HttpSource",
"httpRequestTimeout": "00:01:00"
},
"sink": {
"type": "<sink type>"
}
}
}
]
コピー アクティビティでソースおよびシンクとしてサポートされているデータ ストアの一覧については、「サポートされるデータ ストアと形式」を参照してください。