使用 Azure Data Factory 從 REST 端點複製資料並轉換資料到 REST 端點

發行項
07/12/2024

適用於：Azure Data Factory Azure Synapse Analytics

提示

試用 Microsoft Fabric 中的 Data Factory，這是適用於企業的全方位分析解決方案。 Microsoft Fabric 涵蓋從資料移動到資料科學、即時分析、商業智慧和報告的所有項目。了解如何免費開始新的試用！

本文概述如何使用 Azure Data Factory 中的「複製活動」，從 REST 端點複製資料和複製到 REST 端點。本文以 Azure Data Factory 中的複製活動為基礎，呈現複製活動的一般概觀。

此 REST 連接器、HTTP 連接器和 Web 資料表連接器之間的差異如下：

REST 連接器特別支援從 RESTful API 複製資料。
HTTP 連接器是通用的，可從任何 HTTP 端點擷取資料，例如下載檔案。在使用此 REST 連接器之前，您可能會使用 HTTP 連接器從 RESTful API 複製資料，儘管 HTTP 連接器支援，但與 REST 連接器相比功能較少。
Web 資料表連接器從 HTML 網頁擷取資料表內容。

支援的功能

下列功能支援此 REST 連接器：

支援的功能	IR
複製活動 (來源/接收)	① ②
對應資料流 (來源/接收)	①

① Azure 整合執行階段 ② 自我裝載整合執行階段

如需支援做為來源/接收器的資料存放區清單，請參閱支援的資料存放區。

具體而言，此泛型 REST 連接器支援：

使用 GET 或 POST 方法，從 REST 端點複製資料，並使用 POST、PUT 或 PATCH 方法，將資料複製到 REST 端點。
使用下列其中一種驗證來複製資料：匿名、基本、服務主體、OAuth2 用戶端認證、系統指派的受控識別和 使用者指派的受控識別。
REST API 中的分頁。
若將 REST 當作來源，請複製 REST JSON 回應的原狀或使用結構描述對應加以剖析。僅支援 JSON 格式的回應承載。

提示

若要在 Data Factory 中設定 REST 連接器之前，測試擷取資料的要求，請先了解 API 規格中的標頭和本文需求。您可以使用 Postman 或網頁瀏覽器之類的工具進行驗證。

必要條件

如果您的資料存放區位於內部部署網路、Azure 虛擬網路或 Amazon 虛擬私人雲端中，則必須設定自我裝載整合執行階段以與其連線。

如果您的資料存放區是受控雲端資料服務，則可使用 Azure Integration Runtime。如果只能存取防火牆規則中核准的 IP，您可以將 Azure Integration Runtime IP 新增至允許清單。

您也可以使用 Azure Data Factory 中的受控虛擬網路整合執行階段功能來存取內部部署網路，而不需要安裝和設定自我裝載整合執行階段。

如需 Data Factory 支援的網路安全性機制和選項的詳細資訊，請參閱資料存取策略。

開始使用

若要透過管線執行複製活動，您可以使用下列其中一個工具或 SDK：

使用 UI 建立 REST 連結服務

使用下列步驟，在 Azure 入口網站 UI 中建立 REST 連結服務。

瀏覽至 Azure Data Factory 或 Synapse 工作區中的 [管理] 索引標籤，並選取 [連結服務]，然後選取 [新增]：
- Azure Data Factory
- Azure Synapse
搜尋 REST 並選取 REST 連接器。
設定服務詳細資料，測試連線，然後建立新的連結服務。

連接器設定詳細資料

下列各節提供屬性的相關詳細資料，您可使用這些屬性來定義 REST 連接器專屬的 Data Factory 實體。

連結服務屬性

以下是針對 REST 連結服務支援的屬性：

屬性	描述	必要
type	type 屬性必須設定為 RestService。	Yes
URL	REST 服務的基底 URL。	Yes
enableServerCertificateValidation	連線到端點時，是否要驗證伺服器端的 TLS/SSL 憑證。	No (預設值為 true)
authenticationType	用來連線到 REST 服務的驗證類型。允許的值為 Anonymous、Basic、AadServicePrincipal、OAuth2ClientCredential 和ManagedServiceIdentity。您可以在 `authHeaders` 屬性中額外設定驗證標頭。請分別參閱下列有關更多屬性和範例的對應區段。	Yes
authHeaders	用於驗證的其他 HTTP 要求標頭。例如，若要使用 API 金鑰驗證，您可以選取驗證類型 “Anonymous”，並在標頭中指定 API 金鑰。	No
connectVia	用來連線到資料存放區的整合執行階段。深入了解必要條件一節。如果未指定，此屬性會使用預設的 Azure Integration Runtime。	No

如需不同的驗證類型，請參閱對應的各章節以進一步了解詳細資料。

基本驗證
服務主體驗證
OAuth2 用戶端認證驗證
系統指派的受控身分識別驗證
使用者指派的受控身分識別驗證
匿名驗證

使用基本驗證

將 authenticationType 屬性設定為 [Basic]。除了上一節所述的一般屬性以外，請指定下列屬性：

屬性	描述	必要
userName	用來存取 REST 端點的使用者名稱。	Yes
password	使用者 (userName 值) 的密碼。將此欄位標記為 SecureString 類型，將它安全地儲存在 Data Factory 中。您也可以參考 Azure Key Vault 中儲存的認證。	Yes

範例

{
    "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 應用程式的用戶端識別碼。	Yes
servicePrincipalKey	指定 Microsoft Entra 應用程式的金鑰。將此欄位標記為 SecureString，將它安全地儲存在 Data Factory 中，或參考 Azure Key Vault 中儲存的祕密。	Yes
tenant	指定您的應用程式所在租用戶的資訊 (網域名稱或租用戶識別碼)。將滑鼠游標暫留在 Azure 入口網站右上角，即可擷取它。	Yes
aadResourceId	指定您要求授權的 Microsoft Entra 資源。例如: `https://management.core.windows.net`。	Yes
azureCloudType	針對服務主體驗證，請指定註冊 Microsoft Entra 應用程式的 Azure 雲端環境類型。允許的值為 AzurePublic、AzureChina、AzureUsGovernment 和 AzureGermany。預設會使用資料處理站的雲端環境。	No

範例

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint e.g. https://www.example.com/>",
            "authenticationType": "AadServicePrincipal",
            "servicePrincipalId": "<service principal id>",
            "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"
        }
    }
}

使用 OAuth2 用戶端認證驗證

將 authenticationType 屬性設為 OAuth2ClientCredential。除了上一節所述的一般屬性以外，請指定下列屬性：

屬性	描述	必要
tokenEndpoint	授權伺服器的權杖端點，用於取得存取權杖。	Yes
clientId	與應用程式相關的用戶端識別碼。	Yes
clientSecret	與您的應用程式相關的用戶端密碼。將此欄位標記為 SecureString 類型，將它安全地儲存在 Data Factory 中。您也可以參考 Azure Key Vault 中儲存的認證。	Yes
範圍 (scope)	所需的存取範圍。它會描述要求的存取權種類。	No
resource	要求存取的目標服務或資源。	No

範例

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

使用系統指派的受控識別驗證

將 authenticationType 屬性設定為 [ManagedServiceIdentity]。除了上一節所述的一般屬性以外，請指定下列屬性：

屬性	描述	必要
aadResourceId	指定您要求授權的 Microsoft Entra 資源。例如: `https://management.core.windows.net`。	Yes

範例

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

使用使用者指派的受控識別驗證

將 authenticationType 屬性設定為 [ManagedServiceIdentity]。除了上一節所述的一般屬性以外，請指定下列屬性：

屬性	描述	必要
aadResourceId	指定您要求授權的 Microsoft Entra 資源。例如: `https://management.core.windows.net`。	Yes
credentials	將使用者指派的受控身分識別指定為認證物件。	Yes

範例

{
    "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]。	Yes
relativeUrl	包含資料之資源的相對 URL。若未指定此屬性，則只會使用在連結服務定義中指定的 URL。 HTTP 連接器會從合併的 URL 複製資料：`[URL specified in linked service]/[relative URL specified in dataset]`。	No

如果您在資料集中設定 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]。	Yes
requestMethod	HTTP 方法。允許的值為 GET (預設值) 和 POST。	No
additionalHeaders	其他 HTTP 要求標頭。	No
requestBody	HTTP 要求的主體。	No
paginationRules	用來撰寫下一個頁面要求的分頁規則。請參閱分頁支援區段以取得詳細資料。	No
httpRequestTimeout	用來取得回應的 HTTP 要求會有的逾時值 (TimeSpan 值)。此值是取得回應的逾時值，而非讀取回應資料的逾時值。預設值為 00:01:40。	No
requestInterval	傳送下一個頁面要求之前的等候時間。預設值為 [00:00:01]	No

注意

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	複製活動接收器的 type 屬性必須設定為 RestSink。	Yes
requestMethod	HTTP 方法。允許的值為 POST (預設值)、PUT 和 PATCH。	No
additionalHeaders	其他 HTTP 要求標頭。	No
httpRequestTimeout	用來取得回應的 HTTP 要求會有的逾時值 (TimeSpan 值)。此值是取得回應的逾時值，而非寫入資料的逾時值。預設值為 00:01:40。	No
requestInterval	不同要求之間的間隔時間，以毫秒為單位。要求間隔值應為介於 [10, 60000] 之間的數字。	No
httpCompressionType	使用最佳壓縮等級傳送資料時使用的 HTTP 壓縮類型。允許的值為 none 和 gzip。	No
writeBatchSize	每個批次寫入 REST 接收器的記錄筆數。預設值為 10000。	No

當作接收器的 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。	Yes
relativeUrl	包含資料之資源的相對 URL。若未指定此屬性，則只會使用在連結服務定義中指定的 URL。 HTTP 連接器會從合併的 URL 複製資料：`[URL specified in linked service]/[relative URL specified in dataset]`。	No
additionalHeaders	其他 HTTP 要求標頭。	No
httpRequestTimeout	用來取得回應的 HTTP 要求會有的逾時值 (TimeSpan 值)。此值是取得回應的逾時值，而非寫入資料的逾時值。預設值為 00:01:40。	No
requestInterval	不同要求之間的間隔時間，以毫秒為單位。要求間隔值應為介於 [10, 60000] 之間的數字。	No
QueryParameters.request_query_parameter 或 QueryParameters['request_query_parameter']	使用者定義的 "request_query_parameter" 會參考下一個 HTTP 要求 URL 中的一個查詢參數名稱。	No

接收轉換

屬性	描述	必要
additionalHeaders	其他 HTTP 要求標頭。	No
httpRequestTimeout	用來取得回應的 HTTP 要求會有的逾時值 (TimeSpan 值)。此值是取得回應的逾時值，而非寫入資料的逾時值。預設值為 00:01:40。	No
requestInterval	不同要求之間的間隔時間，以毫秒為單位。要求間隔值應為介於 [10, 60000] 之間的數字。	No
httpCompressionType	使用最佳壓縮等級傳送資料時使用的 HTTP 壓縮類型。允許的值為 none 和 gzip。	No
writeBatchSize	每個批次寫入 REST 接收器的記錄筆數。預設值為 10000。	No

您可以設定刪除、插入、更新和 upsert 方法，以及針對 CRUD 作業傳送至 REST 接收器的相對資料列資料。

資料流程 REST 接收器

範例資料流程指令碼

請注意，在接收之前透過更改資料列轉換，指示 ADF 使用 REST 接收器採取的動作類型。即插入、更新、upsert、刪除。

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 會將單一要求的回應承載大小限制在一個合理的數字；如果傳回大量資料，就會將結果分割成多個頁面，並且要求呼叫者傳送連續要求，以取得結果的下一頁。通常，單一頁面要求是動態的，並且由前頁回應所傳回的資訊所組成。

此泛型 REST 連接器支援下列分頁模式：

下一個要求的絕對或相對 URL = 目前回應本文中的屬性值
下一個要求的絕對或相對 URL = 目前回應標頭中的標頭值
下一個要求的查詢參數 = 目前回應本文中的屬性值
下一個要求的查詢參數 = 目前回應標頭中的標頭值
下一個要求的標頭 = 目前回應本文中的屬性值
下一個要求的標頭 = 目前回應標頭中的標頭值

分頁規則會定義為資料集中的字典，資料集包含一個或多個區分大小寫的機碼值組。此設定將用來產生從第二個頁面開始的要求。連接器會在取得 HTTP 狀態碼 204 (沒有內容)，或任何 "paginationRules" 中的 JSONPath 運算式傳回 null 時，停止逐一查看。

分頁規則中的支援金鑰：

關鍵	描述
AbsoluteUrl	指示 URL 發出下一個要求。可以是絕對 URL 或相對 URL。
QueryParameters.request_query_parameter 或 QueryParameters['request_query_parameter']	使用者定義的 "request_query_parameter" 會參考下一個 HTTP 要求 URL 中的一個查詢參數名稱。
Headers.request_header 或 Headers['request_header']	使用者定義的 "request_header" 會參考下一個 HTTP 要求中的一個標頭名稱。
EndCondition:end_condition	使用者定義的 "end_condition" 表示會在下一個 HTTP 要求結束分頁迴圈的條件。
MaxRequestNumber	表示分頁要求數量上限。留白表示沒有限制。
SupportRFC5988	如果未定義分頁規則，預設為 true。您可以將 `supportRFC5988` 設定為 false，或從指令碼中移除此屬性，以停用此規則。

分頁規則中的支援值：

值	Description
Headers.response_header 或 Headers['response_header']	使用者定義的 "response_header" 會參考目前 HTTP 回應中的一個標頭名稱，其值會用來發出下一個要求。
JSONPath 運算式會以 "$" 開頭 (代表回應本文的根)	回應本文應該只包含一個 JSON 物件，而且不支援物件陣列作為回應本文。 JSONPath 運算式應會傳回單一基本值，而這會用來發出下一個要求。

注意

對應資料流中的分頁規則不同於下列層面複製活動的分頁規則：

對應資料流不支援範圍。
對應資料流不支援 ['']。請改用 {} 逸出特殊字元。例如 body.{@odata.nextLink}，其 JSON 節點 @odata.nextLink 包含特殊字元 .。
對應資料流支援結束條件，但條件語法不同於複製活動的條件語法。 body 用來表示回應本文，而不是 $。 header 用來表示回應標頭，而不是 headers。以下是說明此差異的兩個範例：
- 範例 1：
  複製活動："EndCondition:$.data": "Empty"
  對應資料流："EndCondition:body.data": "Empty"
- 範例 2：
  複製活動："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：在 [基底 URL] 或 [相對 URL] 中輸入 sysparm_offset={offset}，如下列螢幕擷取畫面所示：

顯示可傳送多個要求之設定的螢幕擷取畫面，該要求的變數位於 Query Parameters 中。

或

顯示另一個可傳送多個要求之設定的螢幕擷取畫面，該要求的變數位於 Query Parameters 中。

步驟 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 中。

或

顯示另一個可傳送多個要求之設定的螢幕擷取畫面，該要求的變數位於絕對 URL 中。

步驟 2：將 [分頁規則] 設定為 "AbsoluteUrl.{id}" :"RANGE:1:100:1"。

範例 3：Headers 中的變數

此範例提供設定步驟，傳送變數位於 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}" : "RARNGE: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,
......

此範例中遇到的兩個回應：

回應 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.3：分頁在回應中的特定節點有值時結束

REST API 會以下列結構傳回最後一個回應：
```
{
    Data: [
        {key1: val991, key2: val992
        },
        {key1: val993, key2: val994
        }
    ],
            Complete: true
}
```
將結束條件規則設定為 "EndCondition:$.Complete": "Exist"，以在回應中的特定節點有值時結束分頁。
範例 4.4：分頁在回應中特定節點的值為使用者定義 const 值時結束

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"，以在回應中特定節點的值為使用者定義 const 值時，結束分頁。
範例 4.5：分頁在回應中標頭索引鍵的值等於使用者定義 const 值時結束

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 設定的螢幕擷取畫面。

範例 8：在對應資料流中使用分頁時，下一個要求 URL 來自回應本文

此範例說明下一個要求 URL 來自回應本文時，如何設定對應資料流中的分頁規則和結束條件規則。

回應結構描述如下所示︰

顯示範例 8 的回應結構描述的螢幕擷取畫面。

分頁規則應設定為以下螢幕擷取畫面：

顯示如何設定範例 8 的分頁規則的螢幕擷取畫面。

分頁預設會在本文.{@odata.nextLink}** 為 null 或空白時停止。

但如果上一個回應本文中的 @odata.nextLink 值等於最後一個要求 URL，則會導致無限迴圈。若要避免此條件，請定義結束條件規則。

如果最後一個回應中的 Value 為 Empty，則可將結束條件規則設定如下：
如果回應標頭中完整索引鍵的值等於 true，表示分頁結束，則可以將結束條件規則設定如下：

範例 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 端點複製資料並轉換資料到 REST 端點

支援的功能

必要條件

開始使用

使用 UI 建立 REST 連結服務

連接器設定詳細資料

連結服務屬性

使用基本驗證

使用服務主體驗證

使用 OAuth2 用戶端認證驗證

使用系統指派的受控識別驗證

使用使用者指派的受控識別驗證

使用驗證標頭

資料集屬性

複製活動屬性

REST 作為來源

REST 作為接收器

對應資料流程屬性

來源轉換

接收轉換

範例資料流程指令碼

範例 1：QueryParameters 中的變數

範例 2：AbsoluteUrl 中的變數

範例 3：Headers 中的變數

範例 4：變數位於 AbsoluteUrl/QueryParameters/Headers 中，未預先定義結束變數，且結束條件是根據回應

範例 5：未定義範圍規則時，設定結束條件以避免無止盡的要求

範例 6：設定要求上限數量以避免無止盡的要求

匯出 JSON 回應的原狀

結構描述對應

意見反應

意見反應

其他資源

共用方式為

使用 Azure Data Factory 從 REST 端點複製資料並轉換資料到 REST 端點

支援的功能

必要條件

開始使用

使用 UI 建立 REST 連結服務

連接器設定詳細資料

連結服務屬性

使用基本驗證

使用服務主體驗證

使用 OAuth2 用戶端認證驗證

使用系統指派的受控識別驗證

使用使用者指派的受控識別驗證

使用驗證標頭

資料集屬性

複製活動屬性

REST 作為來源

REST 作為接收器

對應資料流程屬性

來源轉換

接收轉換

範例資料流程指令碼

分頁支援

分頁規則範例

範例 1：QueryParameters 中的變數

範例 2：AbsoluteUrl 中的變數

範例 3：Headers 中的變數

範例 4：變數位於 AbsoluteUrl/QueryParameters/Headers 中，未預先定義結束變數，且結束條件是根據回應

範例 5：未定義範圍規則時，設定結束條件以避免無止盡的要求

範例 6：設定要求上限數量以避免無止盡的要求

範例 7：預設支援 RFC 5988 分頁規則

範例 8：在對應資料流中使用分頁時，下一個要求 URL 來自回應本文

範例 9：在對應資料流中使用分頁時，回應格式為 XML 且下一個要求 URL 來自回應本文

匯出 JSON 回應的原狀

結構描述對應

相關內容

意見反應

意見反應

其他資源