使用 Azure 数据工厂从/向 REST 终结点复制和转换数据

适用于: Azure 数据工厂 Azure Synapse Analytics

提示

试用 Microsoft Fabric 中的数据工厂,这是一种适用于企业的一站式分析解决方案。 Microsoft Fabric 涵盖从数据移动到数据科学、实时分析、商业智能和报告的所有内容。 了解如何免费开始新的试用

本文概述了如何使用 Azure 数据工厂中的复制活动从 REST 终结点复制数据以及向其中复制数据。 本文是根据总体概述复制活动的 Azure 数据工厂中的复制活动编写的。

此 REST 连接器、HTTP 连接器Web 表连接器之间的区别如下:

  • REST connector 连接器专门支持从 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 格式的响应有效负载。

提示

若要在数据工厂中配置 REST 连接器之前测试数据检索请求,请了解标头和正文的 API 规范要求。 可以使用 Postman 或 Web 浏览器等工具进行验证。

先决条件

如果数据存储位于本地网络、Azure 虚拟网络或 Amazon Virtual Private Cloud 内部,则需要配置自承载集成运行时才能连接到该数据存储。

如果数据存储是托管的云数据服务,则可以使用 Azure Integration Runtime。 如果访问范围限制为防火墙规则中允许的 IP,你可以选择将 Azure Integration Runtime IP 添加到允许列表。

此外,还可以使用 Azure 数据工厂中的托管虚拟网络集成运行时功能访问本地网络,而无需安装和配置自承载集成运行时。

要详细了解网络安全机制和数据工厂支持的选项,请参阅数据访问策略

入门

若要使用管道执行复制活动,可以使用以下工具或 SDK 之一:

使用 UI 创建 REST 链接服务

使用以下步骤在 Azure 门户 UI 中创建 REST 链接服务。

  1. 浏览到 Azure 数据工厂或 Synapse 工作区中的“管理”选项卡,并选择“链接服务”,然后单击“新建”:

  2. 搜索“REST”并选择 REST 连接器。

    Select REST connector.

  3. 配置服务详细信息、测试连接并创建新的链接服务。

    Configure REST linked service.

连接器配置详细信息

对于特定于 REST 连接器的数据工厂实体,以下部分提供了有关用于定义这些实体的属性的详细信息。

链接服务属性

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。

有关不同的身份验证类型,请参阅相应的部分了解详细信息。

使用基本身份验证

authenticationType 属性设置为 Basic。 除了前面部分所述的通用属性,还指定以下属性:

属性 描述 必选
userName 用于访问 REST 终结点的用户名。
password 用户(userName 值)的密码 。 将此字段标记为 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。
servicePrincipalKey 指定 Microsoft Entra 应用程序的密钥。 将此字段标记为 SecureString 以安全地将其存储在数据工厂中或引用存储在 Azure Key Vault 中的机密
tenant 指定应用程序的租户信息(域名或租户 ID)。 将鼠标悬停在 Azure 门户右上角进行检索。
aadResourceId 指定要请求授权的 Microsoft Entra 资源,例如 https://management.core.chinacloudapi.cn
azureCloudType 对于服务主体身份验证,请指定 Microsoft Entra 应用程序注册到的 Azure 云环境的类型。
允许的值为“AzureChina”。 默认情况下,使用数据工厂的云环境。

示例

{
    "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.partner.onmschina.cn>",
            "aadResourceId": "<Azure AD resource URL e.g. https://management.core.chinacloudapi.cn>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

使用 OAuth2 客户端凭据身份验证

将 authenticationType 属性设置为 OAuth2ClientCredential。 除了前面部分所述的通用属性,还指定以下属性:

属性 描述 必需
tokenEndpoint 用于获取访问令牌的授权服务器的令牌终结点。
clientId 与应用程序关联的客户端 ID。
clientSecret 与应用程序关联的客户端密码。 将此字段标记为 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>"
        }
    }
}

使用系统分配的托管标识身份验证

authenticationType 属性设置为 ManagedServiceIdentity。 除了前面部分所述的通用属性,还指定以下属性:

属性 描述 必须
aadResourceId 指定要请求授权的 Microsoft Entra 资源,例如 https://management.core.chinacloudapi.cn

示例

{
    "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.chinacloudapi.cn
凭据 将用户分配的托管标识指定为凭据对象。

示例

{
    "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.chinacloudapi.cn>",
            "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]

如果你在数据集中设置了 requestMethodadditionalHeadersrequestBodypaginationRules,我们仍按原样支持该数据集,但建议你以后在活动中使用新模型。

示例:

{
    "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 用于撰写下一页请求的分页规则。 有关详细信息,请参阅分页支持部分。
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 作为接收器

复制活动接收器部分中支持以下属性:

属性 描述 必需
type 复制活动接收器的 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",
            },
        }
    }
]

映射数据流属性

集成数据集和内联数据集的数据流中支持 REST。

源转换

属性 描述 必需
requestMethod HTTP 方法。 允许的值为 GETPOST
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 中的一个查询参数名称。

接收器转换

属性 描述 必需
additionalHeaders 附加的 HTTP 请求标头。
httpRequestTimeout 用于获取响应的 HTTP 请求的超时 (TimeSpan 值) 。 此值是获取响应时的超时,而不是写入数据时的超时。 默认值为 00:01:40 。
requestInterval 不同请求之间的间隔时间(以毫秒为单位)。 请求时间间隔值应当为 [10, 60000] 范围中的数字。
httpCompressionType 使用最佳压缩级别发送数据时要使用的 HTTP 压缩类型。 允许的值为 none 和 gzip。
writeBatchSize 每批向 REST 接收器中写入的记录数。 默认值为 10000。

可以设置 delete、insert、update 和 upsert 方法,以及要发送到 REST 接收器以进行 CRUD 操作的相对行数据。

Data flow REST sink

示例数据流脚本

请注意,先于接收器使用更改行转换,指示 ADF 要对 REST 接收器执行哪种类型的操作。 例如 insert、update、upsert、delete。

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 或从脚本中删除此属性来禁用该规则。

分页规则中支持的值

Value 说明
Headers.response_header 或 Headers['response_header'] “response_header”由用户定义,引用当前 HTTP 响应中的一个标头名称,其值用于发出下一个请求。
以“$”(表示响应正文的根)开头的 JSONPath 表达式 响应正文应只包含一个 JSON 对象。 JSONPath 表达式应返回单个基元值,该值用于发出下一个请求。

备注

在以下几个方面,映射数据流中的分页规则不同于复制活动中的分页规则:

  1. 映射数据流不支持范围。
  2. [''] 在映射数据流中不受支持。 请改为使用 {} 对特殊字符进行转义。 例如 body.{@odata.nextLink},其 JSON 节点 @odata.nextLink 包含特殊字符 .
  3. 结束条件在映射数据流中受支持,但条件语法不同于复制活动中的条件语法。 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},如以下屏幕截图所示:

Screenshot showing one configuration to send multiple requests whose variables are in Query Parameters.

Screenshot showing another configuration to send multiple requests whose variables are in 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}

Screenshot showing one configuration to send multiple requests whose variables are in Absolute Url.

Screenshot showing another configuration to send multiple requests whose variables are in Absolute Url.

步骤 2:将“分页规则”设置为 "AbsoluteUrl.{id}" :"RANGE:1:100:1"。

示例 3:Headers 中的变量

此示例提供用于发送多个请求(其变量在 Headers 中)的配置步骤。

多个请求:
RequestUrl:https://example/table
请求 1:Header(id->0)
请求 2:Header(id->10)
......
请求 100:Header(id->100)

步骤 1:在“其他标头”中输入 {id}

步骤 2:将“分页规则”设置为 "Headers.{id}" : "RARNGE:0:100:10"。

Screenshot showing the pagination rule to send multiple requests whose variables are in Headers.

示例 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",以便在响应中的特定节点的值为空时结束分页。

    Screenshot showing the End Condition setting for Example 4.1.

  • 示例 4.2:当响应中特定节点的值不存在时,分页结束

    REST API 返回采用以下结构的上一个响应:

    {}
    

    将结束条件规则设置为 "EndCondition:$.data": "NonExist",以便在响应中特定节点的值不存在时结束分页。

    Screenshot showing the End Condition setting for Example 4.2.

  • 示例 4.3:当响应中的特定节点的值存在时,分页结束

    REST API 返回采用以下结构的上一个响应:

    {
        Data: [
            {key1: val991, key2: val992
            },
            {key1: val993, key2: val994
            }
        ],
                Complete: true
    }
    

    将结束条件规则设置为 "EndCondition:$.Complete": "Exist",以便在响应中的特定节点的值存在时结束分页。

    Screenshot showing the End Condition setting for Example 4.3.

  • 示例 4.4:当响应中的特定节点的值是用户定义的常量值时,分页结束

    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",以便在响应中的特定节点的值是用户定义的常量值时结束分页。

    Screenshot showing the End Condition setting for Example 4.4.

  • 示例 4.5:当响应中的标头键的值是用户定义的常量值时,分页结束

    REST API 响应中的标头键按照下面的结构显示:

    响应头 1:header(Complete->0)
    ......
    上一个响应头:header(Complete->1)

    将结束条件规则设置为 "EndCondition:headers.Complete": "Const:1",以便在响应中的标头键的值等于用户定义的常量值时结束分页。

    Screenshot showing the End Condition setting for Example 4.5.

  • 示例 4.6:当响应头中存在该键时,分页结束

    REST API 响应中的标头键按照下面的结构显示:

    响应头 1:header()
    ......
    上一个响应头:header(CompleteTime->20220920)

    将结束条件规则设置为 "EndCondition:headers.CompleteTime": "Exist",以便在响应头中存在该键时结束分页。

    Screenshot showing the End Condition setting for Example 4.6.

示例 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 以避免无限请求,如以下屏幕截图所示:

Screenshot showing the Max Request Number setting for Example 6.

示例 7:默认支持 RFC 5988 分页规则

后端将基于标头中的 RFC 5988 样式链接自动获取下一个 URL。

Screenshot showing samples of the http header that complies with R F C 5988.

提示

如果不想启用此默认分页规则,可以在脚本中将 supportRFC5988 设置为 false 或将其删除。

Screenshot showing how to disable R F C 5988 setting for Example 7.

示例 8:在映射数据流中使用分页时,下一个请求 URL 来自响应正文

此示例说明当下一个请求 URL 来自响应正文时,如何在映射数据流中设置分页规则与结束条件规则。

响应架构如下所示:

Screenshot showing the response schema of Example 8.

应按以下屏幕截图所示设置分页规则:

Screenshot showing how to set the pagination rule for Example 8.

默认情况下,当 body.{@odata.nextLink}** 为 null 或为空时,将停止分页。

但如果上一个响应正文中 @odata.nextLink 的值等于上一个请求 URL,则会导致无限循环。 若要避免这种情况,请定义结束条件规则。

  • 如果上一个响应中的“值”为空,则可以按下面所示设置结束条件规则:

    Screenshot showing setting the end condition rule when the last response is empty.

  • 如果响应头中完成键的值等于 true 指示分页结束,则可以按下面所示设置结束条件规则:

    Screenshot showing setting the end condition rule when the complete key in the response header equals to true indicates the end of pagination.

示例 9:在映射数据流中使用分页时,响应格式为 XML 并且下一个请求 URL 来自响应正文

此示例说明当响应格式为 XML 并且下一个请求 URL 来自响应正文时,如何在映射数据流中设置分页规则。 如以下屏幕截图所示,第一个 URL 是 https://<user>.dfs.core.chinacloudapi.cn/bugfix/test/movie_1.xml

Screenshot showing the response format is X M L and the next request U R L is from the response body.

响应架构如下所示:

Screenshot showing the response schema of Example 9.

分页规则语法与示例 8 中的语法相同,应按以下示例所示进行设置:

Screenshot showing setting the pagination rule for Example 9.

按原样导出 JSON 响应

可以使用此 REST 连接器将 REST API JSON 响应按原样导出到各种基于文件的存储。 若要实现这种架构不可知的复制,请跳过数据集中的“结构”(也称为“架构”)节和复制活动中的架构映射 。

架构映射

若要将数据从 REST 终结点复制到表格接收器,请参阅架构映射

有关 Azure 数据工厂中复制活动支持用作源和接收器的数据存储的列表,请参阅支持的数据存储和格式