使用 Azure 数据工厂或 Azure Synapse Analytics 从 SharePoint Online 列表复制数据
适用于:Azure 数据工厂 Azure Synapse Analytics
本文概述如何使用 Azure 数据工厂和 Azure Synapse Analytics 中的复制活动从 SharePoint Online 列表复制数据。 本文根据复制活动一文(其中大致介绍了复制活动)编写。
支持的功能
此 SharePoint Online 列表连接器支持以下功能:
支持的功能 | IR |
---|---|
复制活动(源/-) | ① ② |
Lookup 活动 | ① ② |
① Azure 集成运行时 ② 自承载集成运行时
如需可以用作源或接收器的数据存储的列表,请参阅支持的数据存储表。
具体而言,此 SharePoint Online 列表连接器使用服务主体身份验证,并通过 OData 协议检索数据。
提示
此连接器支持从 SharePoint Online 列表而不是文件复制数据。 通过从 SharePoint Online 复制文件部分了解如何复制文件。
开始使用
若要使用管道执行复制活动,可以使用以下工具或 SDK 之一:
使用 UI 创建到 SharePoint Online 列表的链接服务
使用以下步骤在 Azure 门户 UI 中创建一个到 SharePoint Online 列表的链接服务。
浏览到 Azure 数据工厂或 Synapse 工作区中的“管理”选项卡并选择“链接服务”,然后单击“新建”:
搜索 SharePoint 并选择 SharePoint Online 列表连接器。
配置服务详细信息、测试连接并创建新的链接服务。
连接器配置详细信息
对于特定于 SharePoint Online 列表连接器的实体,以下部分提供了可用于定义这些实体的属性的详细信息。
链接服务属性
SharePoint Online 列表链接的服务支持以下属性:
属性 | 说明 | 必需 |
---|---|---|
type | type 属性必须设置为:SharePointOnlineList。 | 是 |
siteUrl | SharePoint Online 网站 URL,例如 https://contoso.sharepoint.com/sites/siteName 。 |
是 |
servicePrincipalId | 在 Microsoft Entra ID 中注册的应用程序的应用程序(客户端)ID。 | 是 |
servicePrincipalCredentialType | 指定要用于服务主体身份验证的凭据类型。 允许的值为 ServicePrincipalCert 和 ServicePrincipalKey 。 |
否 |
适用于 ServicePrincipalCert | ||
servicePrincipalEmbeddedCert | 指定在 Microsoft Entra ID 中注册的应用程序的 Base64 编码证书,并确保证书内容类型为 PKCS #12。 请将此字段标记为 SecureString 以安全地存储它,或引用存储在 Azure Key Vault 中的机密。 需要配置引用此文章的权限设置。 | 否 |
servicePrincipalEmbeddedCertPassword | 如果使用密码保护证书,请指定证书的密码。 请将此字段标记为 SecureString 以安全地存储它,或引用存储在 Azure Key Vault 中的机密。 | 否 |
适用于 ServicePrincipalKey | ||
servicePrincipalKey | 应用程序的密钥。 请将此字段标记为 SecureString 以安全地存储它,或引用存储在 Azure Key Vault 中的机密。 有关包括权限设置在内的更多详细信息,请参阅此节。 | 否 |
tenantId | 应用程序所在的租户 ID。 | 是 |
connectVia | 用于连接到数据存储的 Integration Runtime。 如果未指定,则使用默认 Azure Integration Runtime。 | 否 |
注意
如果使用基于 Azure ACS(访问控制服务)的服务主体密钥身份验证,鉴于 ACS 停用计划,建议切换到“服务主体证书身份验证”。
示例 1:使用服务主体密钥身份验证
{
"name": "SharePointOnlineList",
"properties": {
"type": "SharePointOnlineList",
"typeProperties": {
"siteUrl": "<site URL>",
"servicePrincipalId": "<service principal id>",
"servicePrincipalCredentialType": "ServicePrincipalKey",
"servicePrincipalKey": {
"type": "SecureString",
"value": "<service principal key>"
},
"tenantId": "<tenant ID>"
},
"connectVia": {
"referenceName": "<name of Integration Runtime>",
"type": "IntegrationRuntimeReference"
}
}
}
示例 2:使用服务主体证书身份验证
{
"name": "SharePointOnlineList",
"properties": {
"type": "SharePointOnlineList",
"typeProperties": {
"siteUrl": "<site URL>",
"servicePrincipalId": "<service principal id>",
"servicePrincipalCredentialType": "ServicePrincipalCert",
"servicePrincipalEmbeddedCert": {
"type": "SecureString",
"value": "<base64 encoded string of (.pfx) certificate data>"
},
"servicePrincipalEmbeddedCertPassword": {
"type": "SecureString",
"value": "<password of your certificate>"
},
"tenantId": "<tenant ID>"
},
"connectVia": {
"referenceName": "<name of Integration Runtime>",
"type": "IntegrationRuntimeReference"
}
}
}
授予使用服务主体密钥的权限
SharePoint Online 列表连接器使用服务主体身份验证连接到 SharePoint。 请按照以下步骤进行设置:
将应用程序注册到 Microsoft 标识平台。 快速入门:通过 Microsoft 标识平台注册应用程序。 记下以下值,这些值用于定义链接服务:
- 应用程序 ID
- 应用程序密钥
- 租户 ID
按照以下步骤,向你注册的应用程序授予 SharePoint Online 网站权限。 为此,需要具有站点管理员角色。
打开你的 SharePoint Online 网站 链接。 例如格式为
https://<your-site-url>/_layouts/15/appinv.aspx
的 URL,其中的占位符<your-site-url>
是你的站点。搜索已注册的应用程序 ID,填写空字段,然后单击“创建”。
应用程序域:
contoso.com
重定向 URL:
https://www.contoso.com
权限请求 XML:
<AppPermissionRequests AllowAppOnlyPolicy="true"> <AppPermissionRequest Scope="http://sharepoint/content/sitecollection/web" Right="Read"/> </AppPermissionRequests>
注意
在配置 SharePoint 连接器的上下文中,“应用域”和“重定向 URL”指的是 Microsoft Entra ID 中注册的用于访问 SharePoint 数据的 SharePoint 应用。 “应用域”是托管 SharePoint 站点的域。 例如,如果 SharePoint 站点位于 https://contoso.sharepoint.com",则“应用域”为“contoso.sharepoint.com”。 “重定向 URL”是 SharePoint 应用在用户向该应用验证身份并获取其权限后重定向到的 URL。 此 URL 应是应用有权访问的 SharePoint 站点页面。 例如,你可以使用显示库中文件列表的页面的 URL,也可以使用显示文档内容的页面的 URL。
对此应用单击“信任它”。
数据集属性
有关可用于定义数据集的各部分和属性的完整列表,请参阅数据集和链接服务。 以下部分提供 SAP 表数据集支持的属性列表。
properties | 描述 | 必需 |
---|---|---|
type | 数据集的 type 属性必须设置为 SharePointOnlineLResource。 | 是 |
listName | SharePoint Online 列表的名称。 请注意,文件名中不允许使用撇号 (')。 | 是 |
示例
{
"name": "SharePointOnlineListDataset",
"properties":
{
"type": "SharePointOnlineListResource",
"linkedServiceName": {
"referenceName": "<SharePoint Online List linked service name>",
"type": "LinkedServiceReference"
},
"typeProperties":
{
"listName": "<name of the list>"
}
}
}
复制活动属性
有关可用于定义活动的各个部分和属性的完整列表,请参阅管道。 以下部分提供 SharePoint Online 列表源支持的属性列表。
SharePoint Online 列表作为源
若要从 SharePoint Online 列表复制数据,复制活动“源”部分支持以下属性:
properties | 描述 | 必需 |
---|---|---|
type | 复制活动源的 type 属性必须设置为 SharePointOnlineListSource。 | 是 |
query | 用于筛选数据的自定义 OData 查询选项。 示例:"$top=10&$select=Title,Number" 。 |
否 |
httpRequestTimeout | 用于获取响应的 HTTP 请求的超时(以秒为单位)。 默认值为 300(5 分钟)。 | 否 |
示例
"activities":[
{
"name": "CopyFromSharePointOnlineList",
"type": "Copy",
"inputs": [
{
"referenceName": "<SharePoint Online List input dataset name>",
"type": "DatasetReference"
}
],
"outputs": [
{
"referenceName": "<output dataset name>",
"type": "DatasetReference"
}
],
"typeProperties": {
"source": {
"type": "SharePointOnlineListSource",
"query": "<OData query e.g. $top=10&$select=Title,Number>"
},
"sink": {
"type": "<sink type>"
}
}
}
]
注意
无法为 SharePoint Online 列表源选择多选数据类型。
SharePoint Online 列表的数据类型映射
从 SharePoint Online 列表复制数据时,在 SharePoint Online 列表数据类型和此服务在内部使用的临时数据类型之间使用以下映射。
SharePoint Online 数据类型 | OData 数据类型 | 临时数据类型 |
---|---|---|
单个文本行 | Edm.String | 字符串 |
多行文本 | Edm.String | 字符串 |
选项(可供选择的菜单) | Edm.String | 字符串 |
数字(1、1.0、100) | Edm.Double | Double |
货币($、¥、€) | Edm.Double | Double |
日期和时间 | Edm.DateTime | DateTime |
查阅项(此网站已有的信息) | Edm.Int32 | Int32 |
是/否(复选框) | Edm.Boolean | Boolean |
个人或团体 | Edm.Int32 | Int32 |
超链接或图片 | Edm.String | 字符串 |
计算(基于其他列的计算) | Edm.String/Edm.Double/Edm.DateTime/Edm.Boolean | 字符串/Double/DateTime/Boolean |
附件 | 不支持 | |
任务结果 | 不支持 | |
外部数据 | 不支持 | |
托管元数据 | 不支持 |
从 SharePoint Online 复制文件
您可以使用以下方法从 SharePoint Online 复制文件:使用 Web 活动进行身份验证并从 SPO 中获取访问令牌,然后传递到后续的复制活动以使用 HTTP 连接器作为源复制数据。
按照授予使用服务主体密钥的权限一节中的说明,创建 Microsoft Entra 应用程序并向 SharePoint Online 授予权限。
创建 Web 活动以从 SharePoint Online 获取访问令牌:
- URL:
https://accounts.accesscontrol.chinacloudapi.cn/[Tenant-ID]/tokens/OAuth/2
替换租户 ID。 - 方法:POST
- 标头:
- 内容类型:application/x-www-form-urlencoded
- 正文:
grant_type=client_credentials&client_id=[Client-ID]@[Tenant-ID]&client_secret=[Client-Secret]&resource=00000003-0000-0ff1-ce00-000000000000/[Tenant-Name].sharepoint.com@[Tenant-ID]
。 替换客户端 ID(应用程序 ID)、客户端密码(应用程序密钥)、租户 ID 和(SharePoint 租户的)租户名称。
注意
在 Web 活动中,将“安全输出”选项设置为 true,以防止令牌值以纯文本格式记录。 使用此值的任何其他活动都应将其“安全输入”选项设置为 true。
- URL:
与 HTTP 连接器作为源的复制活动链接以复制 SharePoint Online 文件内容:
- HTTP 链接服务:
- 基 URL:
https://[site-url]/_api/web/GetFileByServerRelativeUrl('[relative-path-to-file]')/$value
替换网站 URL 和文件的相对路径。 请确保包含 SharePoint 站点 URL 以及域名,例如https://[sharepoint-domain-name].sharepoint.com/sites/[sharepoint-site]/_api/web/GetFileByServerRelativeUrl('/sites/[sharepoint-site]/[relative-path-to-file]')/$value
。 - 身份验证类型:匿名(稍后使用复制活动源中配置的持有者令牌)
- 基 URL:
- 数据集:选择所需的格式。 若要按原样复制文件,请选择“二进制”类型。
- 复制活动源:
- 请求方法:GET
- 其他标头:使用以下表达式
@{concat('Authorization: Bearer ', activity('<Web-activity-name>').output.access_token)}
,该表达式将上游 Web 活动生成的持有者令牌用作授权标头。 替换 Web 活动名称。
- 为任何受支持的接收器目标配置复制活动接收器。
- HTTP 链接服务:
注意
即使 Microsoft Entra 应用程序具有对 SharePoint Online 的 FullControl
权限,也不能从启用了 IRM 的文档库中复制文件。
查找活动属性
若要了解有关属性的详细信息,请查看 Lookup 活动。
相关内容
有关复制活动支持作为源和接收器的数据存储的列表,请参阅支持的数据存储和格式。