你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

使用 Azure 数据工厂或 Azure Synapse Analytics 从 SharePoint Online 列表复制数据

项目
09/14/2024

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

提示

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

本文概述如何使用 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 工作区中的“管理”选项卡并选择“链接服务”，然后单击“新建”：
- Azure 数据工厂
- 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 网站权限。为此，需要具有站点管理员角色。
1. 打开你的 SharePoint Online 网站链接。例如格式为 https://<your-site-url>/_layouts/15/appinv.aspx 的 URL，其中的占位符 <your-site-url> 是你的站点。
2. 搜索已注册的应用程序 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。
3. 对此应用单击“信任它”。

数据集属性

有关可用于定义数据集的各部分和属性的完整列表，请参阅数据集和链接服务。以下部分提供 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 连接器作为源复制数据。

SharePoint 复制文件流

按照授予使用服务主体密钥的权限一节中的说明，创建 Microsoft Entra 应用程序并向 SharePoint Online 授予权限。
创建 Web 活动以从 SharePoint Online 获取访问令牌：
- URL：https://accounts.accesscontrol.windows.net/[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。
与 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。
  - 身份验证类型：匿名（稍后使用复制活动源中配置的持有者令牌）
- 数据集：选择所需的格式。若要按原样复制文件，请选择“二进制”类型。
- 复制活动源：
  - 请求方法：GET
  - 其他标头：使用以下表达式@{concat('Authorization: Bearer ', activity('<Web-activity-name>').output.access_token)}，该表达式将上游 Web 活动生成的持有者令牌用作授权标头。替换 Web 活动名称。
- 为任何受支持的接收器目标配置复制活动接收器。

注意

即使 Microsoft Entra 应用程序具有对 SharePoint Online 的 FullControl 权限，也不能从启用了 IRM 的文档库中复制文件。

查找活动属性

若要了解有关属性的详细信息，请查看 Lookup 活动。

有关复制活动支持作为源和接收器的数据存储的列表，请参阅支持的数据存储和格式。

通过

使用 Azure 数据工厂或 Azure Synapse Analytics 从 SharePoint Online 列表复制数据

支持的功能

开始使用

使用 UI 创建到 SharePoint Online 列表的链接服务

连接器配置详细信息

链接服务属性

授予使用服务主体密钥的权限

数据集属性

复制活动属性

SharePoint Online 列表作为源

SharePoint Online 列表的数据类型映射

从 SharePoint Online 复制文件

查找活动属性

反馈

其他资源

通过

使用 Azure 数据工厂或 Azure Synapse Analytics 从 SharePoint Online 列表复制数据

支持的功能

开始使用

使用 UI 创建到 SharePoint Online 列表的链接服务

连接器配置详细信息

链接服务属性

授予使用服务主体密钥的权限

数据集属性

复制活动属性

SharePoint Online 列表作为源

SharePoint Online 列表的数据类型映射

从 SharePoint Online 复制文件

查找活动属性

相关内容

反馈

其他资源