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

適用対象: Azure Data Factory Azure Synapse Analytics

ヒント

Data Factory in Microsoft Fabric は、よりシンプルなアーキテクチャ、組み込みの AI、および新機能を備えた次世代のAzure Data Factoryです。データ統合を初めて使用する場合は、Fabric Data Factory から始めます。既存の ADF ワークロードをFabricにアップグレードして、データサイエンス、リアルタイム分析、レポートの新機能にアクセスできます。

Fabric無料試用版を開始します。
Azure Data FactoryからMicrosoft FabricのData Factoryへアップグレードしてください。

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

注

このコネクタは、Microsoft Fabricの Data Factory でも使用できます。 Fabric固有の構成と機能については、Fabric REST コネクタのドキュメントを参照してください。

このRESTコネクタ、 HTTPコネクタ、 Webテーブルコネクタの違いは以下の通りです。

REST コネクタでは、特に RESTful API からのデータのコピーがサポートされます。
HTTPコネクタ は、例えばファイルのダウンロードなど、任意のHTTPエンドポイントからデータを取得するための汎用的なものです。このRESTコネクタの前は、HTTPコネクタを使ってRESTful APIからデータをコピーするかもしれません。これはサポートされていますが、RESTコネクタほど機能的ではありません。
Web テーブルコネクタでは、HTML Web ページからテーブルの内容を抽出します。

サポートされる機能

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

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

(1) Azure統合ランタイム (2) セルフホステッド統合ランタイム

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

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

GETまたはPOSTメソッドでRESTエンドポイントからデータをコピーし、POST、PUT、またはPATCHメソッドを使ってRESTエンドポイントにデータをコピーします。
以下のいずれかの認証を用いてデータのコピーを行います: Anonymous、 Basic、 Service Principal、 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 ポータル UI で REST のリンクされたサービスを作成するには、次の手順に従います。

Azure Data Factoryまたは Synapse ワークスペースの [管理] タブを参照し、[リンクされたサービス] を選択し、[新規] を選択します。
- Azureデータファクトリー
- Azure Synapse
Azure Data Factory UI を使用した新しいリンクサービスの作成のスクリーンショット
REST を検索し、REST コネクタを選択します。
サービスの詳細を構成し、接続をテストして、新しいリンクサービスを作成します。

コネクタの構成の詳細

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

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

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

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

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

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

基本認証を使用する

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

プロパティ	内容	必須
ユーザー名	REST エンドポイントにアクセスするために使用するユーザー名。	はい
パスワード	ユーザー (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 に設定します。前のセクションで説明した汎用的なプロパティに加えて、次のプロパティを指定します。

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

テナント	アプリケーションが存在するテナントの情報 (ドメイン名またはテナント ID) を指定します。 Azure ポータルの右上隅にマウスポインターを置いて取得します。	はい
aadResourceId	承認を要求するMicrosoft Entra リソースを指定します (例: `https://management.core.windows.net`)。	はい
Azureクラウドタイプ	サービスプリンシパル認証では、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から証明書をダウンロードできない場合は、このtemplateを使用して、変換されたサービスプリンシパル証明書をシークレットとしてAzure Key Vaultに保存できます。

OAuth2クライアント認証をご利用ください

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

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

例

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

データセットで requestMethod、 additionalHeaders、 requestBody、 paginationRules を設定しても、コピー操作はそれら as-isサポートしますが、今後は新しいモデルをアクティビティで使うべきです。

例:

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

Copy アクティビティのプロパティ

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

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

ソースとしての REST

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

プロパティ	内容	必須
型	コピーアクティビティのソースの type プロパティを RestSource に設定する必要があります	はい
リクエストメソッド (requestMethod)	HTTP メソッド。使用できる値は、GET (既定値) と POST です。	いいえ
additionalHeaders	その他の HTTP 要求ヘッダー。	いいえ
requestBody	HTTP 要求の本文。	いいえ
ページネーションルール	次のページ要求を構成するためのページネーションルール。詳細については、「pagination support」セクションを参照してください。	いいえ
HTTPリクエストタイムアウト	HTTP 要求が応答を取得する際のタイムアウト (TimeSpan 値)。この値は、応答データの読み取りのタイムアウトではなく、応答の取得のタイムアウトです。既定値は 00:01:40 です。	いいえ
requestInterval	次のページに対する要求を送信する前に待機する時間。既定値は 00:00:01 です。	いいえ

注

RESTコネクターは、Acceptで指定したadditionalHeadersヘッダーを無視します。 JSONレスポンスのみをサポートするため、ヘッダーを自動的に Accept: application/jsonに設定します。
最上位の構造体が JSON 配列である REST API 応答では、改ページはサポートされていません。

例 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 セクションでは、次のプロパティがサポートされます。

プロパティ	内容	必須
型	Copy アクティビティシンクの type プロパティは、RestSink に設定する必要があります。	はい
リクエストメソッド (requestMethod)	HTTP メソッド。使用できる値は、POST (既定値)、PUT、および PATCH です。	いいえ
additionalHeaders	その他の HTTP 要求ヘッダー。	いいえ
HTTPリクエストタイムアウト	HTTP 要求が応答を取得する際のタイムアウト (TimeSpan 値)。この値は、データを書き込むタイムアウトではなく、応答を取得するためのタイムアウトです。既定値は 00:01:40 です。	いいえ
requestInterval	異なる要求間の間隔時間 (ミリ秒単位)。要求間隔の値は、[10, 60000] の間の数値にする必要があります。	いいえ
HTTP圧縮タイプ	最適な圧縮レベルでデータを送信するときに使用する 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",
            },
        }
    }
]

データフローのマッピングプロパティ

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

ソース変換

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

シンク変換

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

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

REST Sinkのデータフローのスクリーンショットです。

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

シンクの前に行の変形を用いて、REST シンクでData Factoryにどのようなアクションを取るべきか指示しているのに注目してください。その操作は挿入、更新、アップサート、削除のいずれかです。

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

注

Data Flowでは、N ページを処理するときに、合計で N + 1 の API 呼び出しが生成されます。これには、スキーマを推論するための最初の呼び出しが 1 つ含まれ、その後にソースからフェッチされたページ数に対応する N 個の呼び出しが続きます。

ページネーションサポート

REST APIからデータをコピーする際、REST APIは通常、単一のリクエストの応答ペイロードサイズを合理的な数に制限します。大量のデータリターンを行うために、結果を複数のページに分割し、呼び出し者が連続してリクエストを送って次のページの結果を取得する必要があります。通常、1ページのリクエストは動的で、前のページの回答で返された情報から構成されます。

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

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

ページ設定ルール はデータセット内の辞書として定義され、1つ以上の大文字を区別するキー値ペアを含みます。この構成は2ページ目からリクエストを生成するために使用されます。コネクターはHTTPステータスコード204(No Content)を受け取るか、 paginationRules 内のJSONPath表現がnullを返すと反復を停止します。

ページネーションルールでサポートされるキー:

鍵	内容
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 つのヘッダー名を参照するユーザー定義です。
終了条件: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 つのプリミティブ値が返される必要があります。この値は、次の要求を発行するために使用されます。

注

データフローのマッピングにおけるページ化ルールは、コピー活動のルールとは以下の点で異なります。

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

改ページ規則の例

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

例 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: 次のスクリーンショットに示すように、sysparm_offset={offset} または相対 URL にを入力します。

クエリパラメーターに変数がある複数の要求を送信するための 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: リンクされたサービス構成ページの {id} またはデータセット接続ウィンドウの [相対 URL] のどちらかにを入力します。

絶対 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/ヘッダーに入っていて、エンド変数はあらかじめ定義されておらず、エンド条件はレスポンスに基づいています

この例では、変数が 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:$.Complete": "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」 で、応答中のヘッダーキーの値がユーザー定義のconst値と等しい場合にページを終了します。
例 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 応答 as-is をさまざまなファイルベースのストレージシステム (シンク) にエクスポートできます。このスキーマに依存しないコピー動作を有効にするには、デフォルトのスキーママッピングを使用してください(コピーアクティビティのマッピングタブでマッピングを定義しないでください)。

スキーママッピング

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

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

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-07-31

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

サポートされる機能

前提条件

概要

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

コネクタの構成の詳細

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

基本認証を使用する

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

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

OAuth2クライアント認証をご利用ください

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

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

認証ヘッダーの使用

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

Copy アクティビティのプロパティ

ソースとしての REST

シンクとしての REST

データフローのマッピングプロパティ

ソース変換

シンク変換

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

ページネーションサポート

改ページ規則の例

例 1: QueryParameters の変数

例2:AbsoluteUrl内の変数

例3:ヘッダー内の変数

例4:変数がAbsoluteUrl/QueryParameters/ヘッダーに入っていて、エンド変数はあらかじめ定義されておらず、エンド条件はレスポンスに基づいています

例5:範囲ルールが定義されていない場合に無限リクエストを避けるための終了条件を設定する

例6:無限リクエストを避けるために最大リクエスト数を設定する

例7:RFC 5988のページ割り当てルールはデフォルトでサポートされています

例 8a: データ フローのマッピングでページネーションを使用している場合、次のリクエスト URL はレスポンスボディに含まれています。

例 8b: Copy アクティビティでページネーションを使用する場合、次の要求 URL は応答本文に含まれる。

例 9: データフローのマッピングでページネーションを使用する場合、応答の形式はXMLであり、次のリクエストURLは応答本文から取得されます。

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

スキーマ マッピング

関連するコンテンツ

フィードバック

その他のリソース

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

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

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

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

例 8a: データフローのマッピングでページネーションを使用している場合、次のリクエスト URL はレスポンスボディに含まれています。

スキーママッピング