Azure Data Factory を使用して REST エンドポイントとの間でデータをコピーおよび変換する

[アーティクル]
10/17/2024

適用対象: Azure Data Factory Azure Synapse Analytics

ヒント

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

この記事では、Azure Data Factory の Copy アクティビティを使用して、REST エンドポイントとの間でデータコピーする方法について説明します。この記事は、コピーアクティビティの概要が説明されている「Azure Data Factory のコピーアクティビティ」を基に作成されています。

この REST コネクタ、HTTP コネクタ、および Web テーブルコネクタの違いは次のとおりです。

REST コネクタでは、特に RESTful API からのデータのコピーがサポートされます。
HTTP コネクタは、ファイルをダウンロードするなど、任意の HTTP エンドポイントからデータを取得するための一般的なものです。この REST コネクタの前に、HTTP コネクタを使用して RESTful API からデータをコピーする場合があります。これはサポートされますが、REST コネクタと比べると機能は低くなります。
Web テーブルコネクタでは、HTML Web ページからテーブルの内容を抽出します。

サポートされる機能

この REST コネクタでは、次の機能がサポートされます。

サポートされる機能	IR
Copy アクティビティ (ソース/シンク)	① ②
マッピングデータフロー (ソース/シンク)	①

① Azure 統合ランタイム ② セルフホステッド統合ランタイム

ソースおよびシンクとしてサポートされているデータストアの一覧については、「サポートされているデータストア」を参照してください。

具体的には、この汎用 REST コネクタは以下をサポートします。

GET または POST メソッドを使用した REST エンドポイントからのデータのコピー、および POST、PUT または PATCH メソッドを使用した REST エンドポイントへのデータのコピー。
匿名、基本、サービスプリンシパル、OAuth2 クライアント資格情報、システム割り当てマネージド ID、ユーザー割り当てマネージド ID のいずれかの認証を使用したデータのコピー。
REST API 内の 改ページ位置の自動修正 。
ソースとしての REST の場合、REST JSON 応答をそのままコピーするか、スキーママッピングを使用して解析する。 JSON では応答ペイロードのみがサポートされます。

ヒント

Data Factory で REST コネクタを構成する前に、データ取得のために要求をテストするには、ヘッダーおよび本文の要件に関する 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 を使用して REST のリンクサービスを作成する

次の手順を使用して、Azure portal UI で REST のリンクサービスを作成します。

Azure Data Factory または Synapse ワークスペースの [管理] タブに移動し、[リンクサービス] を選択して、[新規] を選択します。
- Azure Data Factory
- Azure Synapse
REST を検索し、REST コネクタを選択します。
サービスの詳細を構成し、接続をテストして、新しいリンクサービスを作成します。

コネクタの構成の詳細

次のセクションでは、REST コネクタに固有の Data Factory エンティティの定義に使用できるプロパティについて詳しく説明します。

リンクされたサービスのプロパティ

REST のリンクされたサービスでは、次のプロパティがサポートされます。

プロパティ	内容	必須
type	type プロパティには RestService を設定する必要があります。	はい
url	REST サービスのベース URL。	はい
enableServerCertificateValidation	エンドポイントに接続するときに、サーバー側の TLS/SSL 証明書を検証するかどうか。	いいえ (既定値は true です)。
authenticationType	REST サービスへの接続に使用される認証の種類。使用できる値は、Anonymous、Basic、AadServicePrincipal、OAuth2ClientCredential、ManagedServiceIdentity です。 `authHeaders` プロパティで認証ヘッダーを追加で構成することもできます。それぞれのプロパティとサンプルについては、以下の対応するセクションを参照してください。	はい
authHeaders	追加の認証用 HTTP 要求ヘッダー。たとえば、API キー認証を使うには、認証の種類として "匿名" を選択し、ヘッダーに API キーを指定します。	いいえ
connectVia	データストアに接続するために使用される Integration Runtime。詳細については、「前提条件」セクションを参照してください。指定されていない場合は、既定の Azure Integration Runtime が使用されます。	いいえ

各種の認証の種類については、対応するセクションで詳細を参照してください。

基本認証
サービスプリンシパル認証
OAuth2 クライアント資格情報認証
システム割り当てマネージド ID 認証
ユーザー割り当てマネージド ID 認証
[匿名認証]

基本認証を使用する

authenticationType プロパティを Basic に設定します。前のセクションで説明した汎用的なプロパティに加えて、次のプロパティを指定します。

プロパティ	内容	必要
userName	REST エンドポイントにアクセスするために使用するユーザー名。	はい
password	ユーザー (userName 値) のパスワード。 Data Factory に安全に格納するには、このフィールドを SecureString 型として指定します。 Azure Key Vault に格納されているシークレットを参照することもできます。	はい

例

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "authenticationType": "Basic",
            "url" : "<REST endpoint>",
            "userName": "<user name>",
            "password": {
                "type": "SecureString",
                "value": "<password>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

サービスプリンシパル認証を使用する

authenticationType プロパティを AadServicePrincipal に設定します。前のセクションで説明した汎用的なプロパティに加えて、次のプロパティを指定します。

プロパティ	内容	必須
servicePrincipalId	Microsoft Entra アプリケーションのクライアント ID を指定します。	はい
servicePrincipalCredentialType	サービスプリンシパル認証に使用する資格情報の種類を指定します。使用できる値は `ServicePrincipalKey` と `ServicePrincipalCert` です。	いいえ
ServicePrincipalKey に関して
servicePrincipalKey	Microsoft Entra アプリケーションのキーを指定します。このフィールドを SecureString としてマークして Data Factory に安全に保管するか、Azure Key Vault に格納されているシークレットを参照します。	いいえ
ServicePrincipalCert に関して
servicePrincipalEmbeddedCert	Microsoft Entra ID に登録されているアプリケーションの base64 でエンコードされた証明書を指定し、証明書のコンテンツタイプが PKCS #12 であることを確認します。このフィールドを SecureString とマークして安全に保存するか、Azure Key Vault に保存されているシークレットを参照します。証明書を Azure Key Vault に保存する方法については、こちらのセクションを参照してください。	いいえ
servicePrincipalEmbeddedCertPassword	証明書がパスワードで保護されている場合は、証明書のパスワードを指定します。このフィールドを SecureString とマークして安全に保存するか、Azure Key Vault に保存されているシークレットを参照します。	いいえ

tenant	アプリケーションが存在するテナントの情報 (ドメイン名またはテナント ID) を指定します。 Azure portal の右上隅にマウスを置くことで取得します。	はい
aadResourceId	認可を要求する Microsoft Entra リソースを指定します (たとえば、`https://management.core.windows.net`)。	はい
azureCloudType	サービスプリンシパル認証用に、Microsoft Entra アプリケーションが登録されている Azure クラウド環境の種類を指定します。指定できる値は、AzurePublic、AzureChina、AzureUsGovernment、および AzureGermany です。既定では、データファクトリのクラウド環境が使用されます。	いいえ

例 1: サービスプリンシパルキー認証を使用する

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint e.g. https://www.example.com/>",
            "authenticationType": "AadServicePrincipal",
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalCredentialType": "ServicePrincipalKey",
            "servicePrincipalKey": {
                "value": "<service principal key>",
                "type": "SecureString"
            },
            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>",
            "aadResourceId": "<Azure AD resource URL e.g. https://management.core.windows.net>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

例 2: サービスプリンシパル証明書認証を使用する

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint e.g. https://www.example.com/>",
            "authenticationType": "AadServicePrincipal",
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalCredentialType": "ServicePrincipalCert",
            "servicePrincipalEmbeddedCert": {
                "type": "SecureString",
                "value": "<the base64 encoded certificate of your application registered in Microsoft Entra ID>"
            },
            "servicePrincipalEmbeddedCertPassword": {
                "type": "SecureString",
                "value": "<password of your certificate>"
            },
            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>",
            "aadResourceId": "<Azure AD resource URL e.g. https://management.core.windows.net>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

サービスプリンシパル証明書を Azure Key Vault に保存する

サービスプリンシパル証明書を Azure Key Vault に保存するには、次の 2 つのオプションがあります。

方法 1
1. サービスプリンシパル証明書を base64 文字列に変換します。詳しくは、こちらの記事をご覧ください。
2. base64 文字列をシークレットとして Azure Key Vault に保存します。
オプション 2

Azure Key Vault から証明書をダウンロードできない場合は、こちらのテンプレートを使用して、変換されたサービスプリンシパル証明書をシークレットとして Azure Key Vault に保存できます。

OAuth2 クライアント資格情報認証を使用する

authenticationType プロパティを OAuth2ClientCredential に設定します。前のセクションで説明した汎用的なプロパティに加えて、次のプロパティを指定します。

プロパティ	内容	必須
tokenEndpoint	アクセストークンを取得するための承認サーバーのトークンエンドポイント。	はい
clientId	アプリケーションに関連するクライアント ID。	はい
clientSecret	アプリケーションに関連するクライアントシークレット。 Data Factory に安全に格納するには、このフィールドを SecureString 型として指定します。 Azure Key Vault に格納されているシークレットを参照することもできます。	はい
scope	必要なアクセスのスコープ。要求されるアクセスの種類について説明します。	いいえ
resource	アクセスが要求される対象のターゲットサービスまたはリソース。	いいえ

例

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint e.g. https://www.example.com/>",
            "enableServerCertificateValidation": true,
            "authenticationType": "OAuth2ClientCredential",
            "clientId": "<client ID>",
            "clientSecret": {
                "type": "SecureString",
                "value": "<client secret>"
            },
            "tokenEndpoint": "<token endpoint>",
            "scope": "<scope>",
            "resource": "<resource>"
        }
    }
}

システム割り当てマネージド ID 認証を使用する

authenticationType プロパティを ManagedServiceIdentity に設定します。前のセクションで説明した汎用的なプロパティに加えて、次のプロパティを指定します。

プロパティ	内容	必須
aadResourceId	認可を要求する Microsoft Entra リソースを指定します (たとえば、`https://management.core.windows.net`)。	はい

例

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint e.g. https://www.example.com/>",
            "authenticationType": "ManagedServiceIdentity",
            "aadResourceId": "<AAD resource URL e.g. https://management.core.windows.net>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

ユーザー割り当てマネージド ID 認証を使用する

プロパティ	内容	必須
aadResourceId	認可を要求する Microsoft Entra リソースを指定します (たとえば、`https://management.core.windows.net`)。	はい
資格情報	ユーザー割り当てマネージド ID を資格情報オブジェクトとして指定します。	はい

例

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint e.g. https://www.example.com/>",
            "authenticationType": "ManagedServiceIdentity",
            "aadResourceId": "<Azure AD resource URL e.g. https://management.core.windows.net>",
            "credential": {
                "referenceName": "credential1",
                "type": "CredentialReference"
            }    
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

認証ヘッダーの使用

また、組み込みの認証の種類と共に、認証用の要求ヘッダーを構成できます。

例: API キー認証の使用

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint>",
            "authenticationType": "Anonymous",
            "authHeaders": {
                "x-api-key": {
                    "type": "SecureString",
                    "value": "<API key>"
                }
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

データセットのプロパティ

このセクションでは、REST データセットでサポートされているプロパティの一覧を示します。

データセットの定義に使用できるセクションとプロパティの完全な一覧については、「データセットとリンクされたサービス」を参照してください。

REST からのデータコピーについては、次のプロパティがサポートされています。

プロパティ	内容	必須
type	データセットの type プロパティを RestResource に設定する必要があります。	はい
relativeUrl	データを含むリソースへの相対 URL。このプロパティが指定されていない場合は、リンクされたサービス定義に指定されている URL のみが使用されます。 HTTP コネクタは、次の結合された URL からデータをコピーします。`[URL specified in linked service]/[relative URL specified in dataset]`	いいえ

データセットに requestMethod、additionalHeaders、requestBody、paginationRules を設定していた場合は現状のまま引き続きサポートされますが、今後のアクティビティでは新しいモデルを使用することをお勧めします。

例:

{
    "name": "RESTDataset",
    "properties": {
        "type": "RestResource",
        "typeProperties": {
            "relativeUrl": "<relative url>"
        },
        "schema": [],
        "linkedServiceName": {
            "referenceName": "<REST linked service name>",
            "type": "LinkedServiceReference"
        }
    }
}

コピーアクティビティのプロパティ

このセクションでは、REST のソースとシンクでサポートされるプロパティの一覧を示します。

アクティビティの定義に利用できるセクションとプロパティの完全な一覧については、パイプラインに関する記事を参照してください。

ソースとしての REST

コピーアクティビティの source セクションでは、次のプロパティがサポートされます。

プロパティ	内容	必須
type	コピーアクティビティのソースの type プロパティを RestSource に設定する必要があります	はい
requestMethod	HTTP メソッド。使用できる値は、GET (既定値) と POST です。	いいえ
additionalHeaders	追加の HTTP 要求ヘッダー。	いいえ
requestBody	HTTP 要求の本文。	いいえ
paginationRules	次のページ要求を作成する改ページ位置の自動修正規則。詳細については、「pagination support」(改ページ位置の自動調整のサポート) セクションを参照してください。	いいえ
httpRequestTimeout	HTTP 要求が応答を取得する際のタイムアウト (TimeSpan 値)。この値は、応答データの読み取りのタイムアウトではなく、応答の取得のタイムアウトです。既定値は 00:01:40 です。	いいえ
requestInterval	次のページに対する要求を送信する前に待機する時間。既定値は 00:00:01 です。	いいえ

注意

REST コネクタは、additionalHeaders で指定された "Accept" ヘッダーをすべて無視します。 REST コネクタは JSON の応答のみをサポートし、Accept: application/json のヘッダーを自動生成します。
応答本文としてのオブジェクトの配列は、改ページ位置の自動修正ではサポートされていません。

例 1: 改ページ位置の自動修正で Get メソッドを使用する

"activities":[
    {
        "name": "CopyFromREST",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<REST input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "RestSource",
                "additionalHeaders": {
                    "x-user-defined": "helloworld"
                },
                "paginationRules": {
                    "AbsoluteUrl": "$.paging.next"
                },
                "httpRequestTimeout": "00:01:00"
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

例 2: Post メソッドを使用する

"activities":[
    {
        "name": "CopyFromREST",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<REST input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "RestSource",
                "requestMethod": "Post",
                "requestBody": "<body for POST REST request>",
                "httpRequestTimeout": "00:01:00"
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

シンクとしての REST

コピーアクティビティの sink セクションでは、次のプロパティがサポートされます。

プロパティ	内容	必須
type	Copy アクティビティのシンクの type プロパティには RestSink を設定する必要があります。	はい
requestMethod	HTTP メソッド。使用できる値は、POST (既定値)、PUT、および PATCH です。	いいえ
additionalHeaders	追加の HTTP 要求ヘッダー。	いいえ
httpRequestTimeout	HTTP 要求が応答を取得する際のタイムアウト (TimeSpan 値)。この値は、データの書き込みのタイムアウトではなく、応答の取得のタイムアウトです。既定値は 00:01:40 です。	いいえ
requestInterval	異なる要求間の間隔時間 (ミリ秒単位)。要求間隔の値は、[10, 60000] の間の数値にする必要があります。	いいえ
httpCompressionType	最適な圧縮レベルでデータを送信するときに使用する HTTP 圧縮の種類。使用できる値は none と gzip です。	いいえ
writeBatchSize	バッチごとに REST シンクに書き込むレコードの数。既定値は 10000 です。	いいえ

シンクとしての REST コネクタは、JSON を受け入れる REST API と連携します。データは次のパターンで JSON で送信されます。必要に応じて、コピーアクティビティスキーママッピングを使用し、REST API によって求められるペイロードに準拠するようにソースデータを整形できます。

[
    { <data object> },
    { <data object> },
    ...
]

例:

"activities":[
    {
        "name": "CopyToREST",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<REST output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "<source type>"
            },
            "sink": {
                "type": "RestSink",
                "requestMethod": "POST",
                "httpRequestTimeout": "00:01:40",
                "requestInterval": 10,
                "writeBatchSize": 10000,
                "httpCompressionType": "none",
            },
        }
    }
]

Mapping Data Flow のプロパティ

REST は、統合データセットとインラインデータセットの両方のデータフローでサポートされています。

ソース変換

プロパティ	内容	必須
requestMethod	HTTP メソッド。使用できる値は GET と POST です。	はい
relativeUrl	データを含むリソースへの相対 URL。このプロパティが指定されていない場合は、リンクされたサービス定義に指定されている URL のみが使用されます。 HTTP コネクタは、次の結合された URL からデータをコピーします。`[URL specified in linked service]/[relative URL specified in dataset]`	いいえ
additionalHeaders	追加の HTTP 要求ヘッダー。	いいえ
httpRequestTimeout	HTTP 要求が応答を取得する際のタイムアウト (TimeSpan 値)。この値は、データの書き込みのタイムアウトではなく、応答の取得のタイムアウトです。既定値は 00:01:40 です。	いいえ
requestInterval	異なる要求間の間隔時間 (ミリ秒単位)。要求間隔の値は、[10, 60000] の間の数値にする必要があります。	いいえ
QueryParameters.request_query_parameter または QueryParameters['request_query_parameter']	"request_query_parameter" は、次の HTTP 要求 URL 内で 1 つのクエリパラメーター名を参照するユーザー定義です。	いいえ

シンク変換

プロパティ	内容	必須
additionalHeaders	追加の HTTP 要求ヘッダー。	いいえ
httpRequestTimeout	HTTP 要求が応答を取得する際のタイムアウト (TimeSpan 値)。この値は、データの書き込みのタイムアウトではなく、応答の取得のタイムアウトです。既定値は 00:01:40 です。	いいえ
requestInterval	異なる要求間の間隔時間 (ミリ秒単位)。要求間隔の値は、[10, 60000] の間の数値にする必要があります。	いいえ
httpCompressionType	最適な圧縮レベルでデータを送信するときに使用する HTTP 圧縮の種類。使用できる値は none と gzip です。	いいえ
writeBatchSize	バッチごとに REST シンクに書き込むレコードの数。既定値は 10000 です。	いいえ

削除、挿入、更新、アップサートの各メソッドと、CRUD 操作のために REST シンクに送信する相対行データを設定できます。

データフロー REST シンク

データフロースクリプトのサンプル

シンクの前に行の変更変換を使用して、REST シンクで実行するアクションの種類 (挿入、更新、アップサート、削除) を ADF に指示します。

AlterRow1 sink(allowSchemaDrift: true,
	validateSchema: false,
	deletable:true,
	insertable:true,
	updateable:true,
	upsertable:true,
	rowRelativeUrl: 'periods',
	insertHttpMethod: 'PUT',
	deleteHttpMethod: 'DELETE',
	upsertHttpMethod: 'PUT',
	updateHttpMethod: 'PATCH',
	timeout: 30,
	requestFormat: ['type' -> 'json'],
	skipDuplicateMapInputs: true,
	skipDuplicateMapOutputs: true) ~> sink1

改ページ位置の自動調整のサポート

REST API からデータをコピーするとき、通常、REST API では、1 つの要求の応答ペイロードのサイズが適切な数値を超えないように制限されています。大量のデータが返される場合は、結果が複数のページに分割され、呼び出し元に連続する要求を送信して結果の次のページを取得することが要求されます。通常、1 つのページに対する要求は動的で、前のページの応答から返される情報で構成されます。

この汎用 REST コネクタでは、次の改ページ位置の自動修正パターンをサポートしています。

次の要求の絶対または相対 URL = 現在の応答本文のプロパティ値
次の要求の絶対または相対 URL = 現在の応答ヘッダーのヘッダー値
次の要求のクエリパラメーター = 現在の応答本文のプロパティ値
次の要求のクエリパラメーター = 現在の応答ヘッダーのヘッダー値
次の要求のヘッダー = 現在の応答本文のプロパティ値
次の要求のヘッダー = 現在の応答ヘッダーのヘッダー値

改ページ位置の自動修正規則はデータセット内のディクショナリとして定義されます。これには、大文字と小文字が区別される、1 つまたは複数のキーと値のペアが含まれます。構成は 2 番目のページから始まる要求を生成するのに使用されます。コネクタで HTTP 状態コード 204 (コンテンツなし) が取得されるか、"paginationRules" 内のいずれかの JSONPath 式で null が返されると、繰り返し処理が停止されます。

改ページ位置の自動修正規則でサポートされるキー:

Key	説明
AbsoluteUrl	次の要求を発行する URL を示します。これは、絶対 URL と相対 URL のどちらかです。
QueryParameters.request_query_parameter または QueryParameters['request_query_parameter']	"request_query_parameter" は、次の HTTP 要求 URL 内で 1 つのクエリパラメーター名を参照するユーザー定義です。
Headers.request_header または Headers['request_header']	"request_header" は、次の HTTP 要求内で 1 つのヘッダー名を参照するユーザー定義です。
EndCondition:end_condition	"end_condition" は、次の HTTP 要求で改ページループを終了させる条件を示すユーザー定義です。
MaxRequestNumber	改ページ要求の最大数を示します。これを空のままにすると、制限がなくなります。
SupportRFC5988	既定では、改ページ規則が定義されていない場合、これは true に設定されます。この規則を無効にするには、`supportRFC5988` を false に設定するか、スクリプトからこのプロパティを削除します。

改ページ位置の自動修正規則でサポートされる値:

値	説明
Headers.response_header または Headers['response_header']	"response_header" は、現在の HTTP 応答内で 1 つのヘッダー名を参照するユーザー定義で、その値は、次の要求を発行するために使用されます。
(応答本文のルートを表す) "$" から始まる JSONPath 式	応答本文には 1 つの JSON オブジェクトのみを含める必要があります。応答本文としてのオブジェクトの配列はサポートされていません。 JSONPath 式では、1 つのプリミティブ値が返される必要があります。この値は、次の要求を発行するために使用されます。

注意

マッピングデータフローの改ページ規則は、次のアスペクトで Copy アクティビティとは異なります。

範囲は、マッピングデータフローではサポートされていません。
[''] は、マッピングデータフローではサポートされていません。代わりに、{} を使用して特殊文字をエスケープします。たとえば、body.{@odata.nextLink}、JSON ノード@odata.nextLinkに特殊文字が含まれているとします. 。
終了条件はマッピングデータフローでサポートされますが、条件の構文は Copy アクティビティの場合とは異なります。 body は、$ ではなく応答本文を示すために使用されます。 header は、headers ではなく応答ヘッダーを示すために使用されます。この違いを示す 2 つの例を次に示します。
- 例 1:
  Copy アクティビティ: "EndCondition:$.data": "Empty"
  マッピングデータフロー: "EndCondition:body.data": "Empty"
- 例 2:
  Copy アクティビティ: "EndCondition:headers.complete": "Exist"
  マッピングデータフロー: "EndCondition:body.data": "Empty"

改ページ規則の例

このセクションでは、改ページ規則の設定の例の一覧を示します。

例 1: QueryParameters の変数

この例では、QueryParameters に変数が含まれる複数の要求を送信する構成手順を示します。

複数の要求:

baseUrl/api/now/table/incident?sysparm_limit=1000&sysparm_offset=0,
baseUrl/api/now/table/incident?sysparm_limit=1000&sysparm_offset=1000,
...... 
baseUrl/api/now/table/incident?sysparm_limit=1000&sysparm_offset=10000

手順 1: 次のスクリーンショットに示すように、ベース URL または相対 URL に sysparm_offset={offset} を入力します。

クエリパラメーターに変数がある複数の要求を送信するための 1 つの構成を示すスクリーンショット。

または

クエリパラメーターに変数がある複数の要求を送信するための別の構成を示すスクリーンショット。

手順 2: 改ページ規則をオプション 1 またはオプション 2 として次のように設定します。

オプション 1: "QueryParameters.{offset}" : "RANGE:0:10000:1000"
オプション 2: "AbsoluteUrl.{offset}" : "RANGE:0:10000:1000"

例 2 : AbsoluteUrl の変数

この例では、AbsoluteUrl に変数が含まれる複数の要求を送信する構成手順を示します。

複数の要求:

BaseUrl/api/now/table/t1
BaseUrl/api/now/table/t2
...... 
BaseUrl/api/now/table/t100

手順 1: リンクされたサービス構成ページの [ベース URL ] またはデータセット接続ウィンドウの [相対 URL] のどちらかに {id} を入力します。

絶対 URL に変数がある複数の要求を送信するための 1 つの構成を示すスクリーンショット。

または

絶対 URL に変数がある複数の要求を送信するための別の構成を示すスクリーンショット。

手順 2: 改ページ規則を "AbsoluteUrl.{id}" :"RANGE:1:100:1" として設定します。

例 3: ヘッダー内の変数

この例では、Headers に変数が含まれる複数の要求を送信する構成手順を示します。

複数の要求:
RequestUrl: https://example/table
Request 1: Header(id->0)
Request 2: Header(id->10)
......
Request 100: Header(id->100)

手順 1: [追加のヘッダー] に {id} を入力します。

手順 2: 改ページ規則を "Headers.{id}" : "RANGE:0:100:10" として設定します。

ヘッダーに変数がある複数の要求を送信するための改ページ規則を示すスクリーンショット。

例 4: 変数は AbsoluteUrl/QueryParameters/Headers に含まれています。終了変数は事前に定義されておらず、終了条件は応答に基づいています

この例では、変数は AbsoluteUrl/QueryParameters/Headers にありますが、終了変数が定義されていない複数の要求を送信する構成手順を示します。異なる応答ごとに、異なる終了条件ルールの設定が「例 4.1-4.6」に示されています。

複数の要求:

Request 1: baseUrl/api/now/table/incident?sysparm_limit=1000&sysparm_offset=0, 
Request 2: baseUrl/api/now/table/incident?sysparm_limit=1000&sysparm_offset=1000,
Request 3: baseUrl/api/now/table/incident?sysparm_limit=1000&sysparm_offset=2000,
......

この例では、次の 2 つの応答が発生しました。

応答 1:

{
    Data: [
        {key1: val1, key2: val2
        },
        {key1: val3, key2: val4
        }
    ]
}

応答 2:

{
    Data: [
        {key1: val5, key2: val6
        },
        {key1: val7, key2: val8
        }
    ]
}

手順 1: 改ページ規則の範囲を例 1 として設定し、"AbsoluteUrl.{offset}": "RANGE:0::1000" として範囲の末尾を空にしておきます。

手順 2: 最後の応答ごとに異なる終了条件ルールを設定します。次の例を参照してください。

例 4.1: 応答の特定のノードの値が空の場合に改ページが終了する

REST API は、次の構造体の最後の応答を返します。
```
{
    Data: []
}
```
応答の特定のノードの値が空の場合に改ページ調整を終了するには、終了条件ルールを "EndCondition:$.data": "Empty" に設定します。
例 4.2: 応答の特定のノードの値が存在しない場合に改ページが終了する

REST API は、次の構造体の最後の応答を返します。
```
{}
```
応答の特定のノードの値が存在しない場合に改ページ調整を終了するには、終了条件ルールを "EndCondition:$.data": "NonExist" に設定します。
例 4.1: 応答の特定のノードの値が存在する場合に改ページが終了する

REST API は、次の構造体の最後の応答を返します。
```
{
    Data: [
        {key1: val991, key2: val992
        },
        {key1: val993, key2: val994
        }
    ],
            Complete: true
}
```
応答の特定のノードの値が存在する場合に改ページ調整を終了するには、終了条件ルールを "EndCondition:$.data": "Exist" に設定します。
例 4.1: 応答の特定のノードの値がユーザー定義の定数値の場合に改ページが終了する

REST API は、次の構造体の応答を返します。
```
{
    Data: [
        {key1: val1, key2: val2
        },
        {key1: val3, key2: val4
        }
    ],
            Complete: false
}
```
......

最後の応答は次の構造です。
```
{
    Data: [
        {key1: val991, key2: val992
        },
        {key1: val993, key2: val994
        }
    ],
            Complete: true
}
```
応答の特定のノードの値がユーザー定義の定数値である場合に改ページ調整を終了するには、終了条件ルールを "EndCondition:$.Complete": "Const:true" に設定します。
例 4.5: 応答のヘッダーキーの値がユーザー定義の定数値に等しい場合に改ページが終了する

REST API 応答のヘッダーキーは、次の構造に示されています。

応答ヘッダー 1: header(Complete->0)
......
最後の応答ヘッダー: header(Complete->1)

応答のヘッダーキーの値がユーザー定義の定数値と同等である場合に改ページ調整を終了するには、終了条件ルールを "EndCondition:headers.Complete": "Const:1" に設定します。
例 4.6: 応答ヘッダーにキーが存在するときに、改ページ位置の自動修正が終了する

REST API 応答のヘッダーキーは、次の構造に示されています。

応答ヘッダー 1: header()
......
最後の応答ヘッダー: header(CompleteTime->20220920)

終了条件規則を "EndCondition:headers.CompleteTime": "Exist" として設定し、キーが応答ヘッダーに存在する場合に改ページを終了します。

例 5: 範囲ルールが定義されていない場合に際限のない要求を回避するように終了条件を設定する

この例では、範囲ルールが使用されていない場合に複数の要求を送信する構成手順を示します。終了条件では、際限のない要求を避けるため、4.1-4.6 の例を参照して設定できます。 REST API によって、次の構造で応答が返されます。この場合、次のページの URL は paging.next で表されます。

{
    "data": [
        {
            "created_time": "2017-12-12T14:12:20+0000",
            "name": "album1",
            "id": "1809938745705498_1809939942372045"
        },
        {
            "created_time": "2017-12-12T14:14:03+0000",
            "name": "album2",
            "id": "1809938745705498_1809941802371859"
        },
        {
            "created_time": "2017-12-12T14:14:11+0000",
            "name": "album3",
            "id": "1809938745705498_1809941879038518"
        }
    ],
    "paging": {
        "cursors": {
            "after": "MTAxNTExOTQ1MjAwNzI5NDE=",
            "before": "NDMyNzQyODI3OTQw"
        },
        "previous": "https://graph.facebook.com/me/albums?limit=25&before=NDMyNzQyODI3OTQw",
        "next": "https://graph.facebook.com/me/albums?limit=25&after=MTAxNTExOTQ1MjAwNzI5NDE="
    }
}
...

最後の応答は次のとおりです。

{
    "data": [],
    "paging": {
        "cursors": {
            "after": "MTAxNTExOTQ1MjAwNzI5NDE=",
            "before": "NDMyNzQyODI3OTQw"
        },
        "previous": "https://graph.facebook.com/me/albums?limit=25&before=NDMyNzQyODI3OTQw",
        "next": "Same with Last Request URL"
    }
}

手順 1: 改ページ規則を "AbsoluteUrl": "$.paging.next" として設定します。

手順 2: 最後の応答の next が、最後の要求 URL と常に同じで、かつ空でない場合は、際限のない要求が送信されます。終了条件は、際限のない要求を回避するために使用できます。そのため、例 4.1-4.6 を参照して、終了条件規則を設定します。

例 6: 際限のない要求を回避するための最大要求数を設定する

次のスクリーンショットに示すように、 Maxrequestnumber を設定して際限のない要求を回避します。

例 6 の最大要求数の設定を示すスクリーンショット。

例 7: RFC 5988 の改ページ規則が既定でサポートされている

バックエンドは、ヘッダー内の RFC 5988 スタイルのリンクに基づいて次の URL を自動的に取得します。

RFC 5988 に準拠した http ヘッダーの例を示すスクリーンショット。

ヒント

この既定の改ページ規則を有効にしない場合は、supportRFC5988 を false に設定するか、スクリプト内で削除するだけです。

例 7 の RFC 5988 の設定を無効にする方法を示すスクリーンショット。

例 8a: データフローのマッピングで改ページ位置の自動修正を使用している場合、次の要求 URL は応答本文からのものである

この例では、次の要求 URL が応答本文からのものである場合に、データフローのマッピングで改ページ規則と終了条件規則を設定する方法を示します。

応答スキーマは次のようになります。

例 8 の応答スキーマを示すスクリーンショット。

改ページ規則は、次のスクリーンショットのように設定する必要があります。

例 8 の改ページ規則を設定する方法を示すスクリーンショット。

既定では、ページ分割は、body.{@odata.nextLink}** が null 値または空になると停止します。

ただし、最後の応答本文にある @odata.nextLink の値が最後の要求 URL と同じ場合は、無限ループになります。この状況を回避するには、終了条件の規則を定義します。

最後の応答の値が空の場合、終了条件規則は次のように設定できます。
応答ヘッダーの完全なキーの値が true と同等の場合は、改ページ位置の自動修正の終了を示し、次のように、終了条件規則を設定できます。

例 8b: Copy アクティビティで改ページ位置の自動修正を使用している場合、次の要求 URL は応答本文からのものである

この例では、次の要求 URL が応答本文に含まれている場合に Copy アクティビティで改ページ位置の自動修正ルールをどのように設定するかについて説明します。

応答スキーマは次のようになります。

例 8b の応答スキーマを示すスクリーンショット。

改ページ位置の自動修正ルールは、次のスクリーンショットに示すとおりに設定する必要があります。

例 8b の改ページ位置の自動修正ルールの設定方法を示すスクリーンショット。

例 9: データフローのマッピングで改ページ位置の自動修正次を使用している場合、応答の形式が XML であり、次の要求 URL は応答本文からのものである

この例では、応答の形式が XML であり、次の要求 URL が応答本文からのものである場合に、マッピングデータフローで改ページ規則を設定する方法を示します。次のスクリーンショットに示すように、最初の URL は https://<user>.dfs.core.windows.net/bugfix/test/movie_1.xml です

応答形式が XML で、次の要求 URL が応答本文からのものであることを示すスクリーンショット。

応答スキーマは次のようになります。

例 9 の応答スキーマを示すスクリーンショット。

改ページ規則の構文は例 8 と同じであり、次の例のように設定する必要があります。

例 9 の改ページ規則の設定を示すスクリーンショット。

JSON の応答をそのままエクスポートする

この REST コネクタを使用して REST API JSON の応答をそのままさまざまなファイルベースのストアにエクスポートできます。このようなスキーマに依存しないコピーを実現するには、データセットの "構造" ("スキーマ" とも呼ばれる) のセクションと、コピーアクティビティでのスキーママッピングをスキップします。

スキーママッピング

REST エンドポイントから表形式のシンクにデータをコピーするには、スキーママッピングを参照してください。

Azure Data Factory のコピーアクティビティによってソースおよびシンクとしてサポートされるデータストアの一覧については、「サポートされるデータストアと形式」を参照してください。

次の方法で共有

Azure Data Factory を使用して REST エンドポイントとの間でデータをコピーおよび変換する

サポートされる機能

前提条件

はじめに

UI を使用して REST のリンクサービスを作成する

コネクタの構成の詳細

リンクされたサービスのプロパティ

基本認証を使用する

サービスプリンシパル認証を使用する

サービスプリンシパル証明書を Azure Key Vault に保存する

OAuth2 クライアント資格情報認証を使用する

システム割り当てマネージド ID 認証を使用する

ユーザー割り当てマネージド ID 認証を使用する

認証ヘッダーの使用

データセットのプロパティ

コピーアクティビティのプロパティ

ソースとしての REST

シンクとしての REST

Mapping Data Flow のプロパティ

ソース変換

シンク変換

データフロースクリプトのサンプル

例 1: QueryParameters の変数

例 2 : AbsoluteUrl の変数

例 3: ヘッダー内の変数

例 4: 変数は AbsoluteUrl/QueryParameters/Headers に含まれています。終了変数は事前に定義されておらず、終了条件は応答に基づいています

例 5: 範囲ルールが定義されていない場合に際限のない要求を回避するように終了条件を設定する

例 6: 際限のない要求を回避するための最大要求数を設定する

JSON の応答をそのままエクスポートする

スキーママッピング

フィードバック

その他のリソース

次の方法で共有

Azure Data Factory を使用して REST エンドポイントとの間でデータをコピーおよび変換する

サポートされる機能

前提条件

はじめに

UI を使用して REST のリンク サービスを作成する

コネクタの構成の詳細

リンクされたサービスのプロパティ

基本認証を使用する

サービス プリンシパル認証を使用する

サービス プリンシパル証明書を Azure Key Vault に保存する

OAuth2 クライアント資格情報認証を使用する

システム割り当てマネージド ID 認証を使用する

ユーザー割り当てマネージド ID 認証を使用する

認証ヘッダーの使用

データセットのプロパティ

コピー アクティビティのプロパティ

ソースとしての REST

シンクとしての REST

Mapping Data Flow のプロパティ

ソース変換

シンク変換

データ フロー スクリプトのサンプル

改ページ位置の自動調整のサポート

改ページ規則の例

例 1: QueryParameters の変数

例 2 : AbsoluteUrl の変数

例 3: ヘッダー内の変数

例 4: 変数は AbsoluteUrl/QueryParameters/Headers に含まれています。終了変数は事前に定義されておらず、終了条件は応答に基づいています

例 5: 範囲ルールが定義されていない場合に際限のない要求を回避するように終了条件を設定する

例 6: 際限のない要求を回避するための最大要求数を設定する

例 7: RFC 5988 の改ページ規則が既定でサポートされている

例 8a: データ フローのマッピングで改ページ位置の自動修正を使用している場合、次の要求 URL は応答本文からのものである

例 8b: Copy アクティビティで改ページ位置の自動修正を使用している場合、次の要求 URL は応答本文からのものである

例 9: データ フローのマッピングで改ページ位置の自動修正次を使用している場合、応答の形式が XML であり、次の要求 URL は応答本文からのものである

JSON の応答をそのままエクスポートする

スキーマ マッピング

関連するコンテンツ

フィードバック

その他のリソース

UI を使用して REST のリンクサービスを作成する

サービスプリンシパル認証を使用する

サービスプリンシパル証明書を Azure Key Vault に保存する

コピーアクティビティのプロパティ

データフロースクリプトのサンプル

例 8a: データフローのマッピングで改ページ位置の自動修正を使用している場合、次の要求 URL は応答本文からのものである

例 9: データフローのマッピングで改ページ位置の自動修正次を使用している場合、応答の形式が XML であり、次の要求 URL は応答本文からのものである

スキーママッピング