将SharePoint文档同步到知识库

适用范围

开始操作前，请确保已准备以下资源：

• 一个已创建的PolarDB知识库。创建方法请参见使用企业知识空间。

• 一个SharePoint Online组织租户，以及待同步的文档库。

• 具备Microsoft Entra应用注册权限，并可联系有权授予管理员同意的 Microsoft Entra 管理员。

• 待同步SharePoint站点和文档库的访问权限：至少能够打开目标目录并复制地址。如需验证文件更新的同步效果，还需要对已同步文件的编辑权限。当前支持以下SharePoint Online环境：

  环境	SharePoint 域名示例
  全球版 Microsoft 365	contoso.sharepoint.com
  世纪互联运营的 Microsoft 365	contoso.sharepoint.cn

  说明

  不支持本地部署的SharePoint Server，也不支持个人OneDrive地址（域名中包含-my.sharepoint.）。

流程概述

1. 注册 Microsoft Entra 应用，获取目录（租户）ID 和应用程序（客户端）ID。

2. 为应用创建客户端密码。

3. 为应用开通 Microsoft Graph 的 SharePoint 站点读取权限，并授予管理员同意。

4. 从 SharePoint 复制待同步文档库或文件夹的完整地址。

5. 通过PolarDB创建 SharePoint 同步链路，填写应用凭证、SharePoint 地址和同步周期。

6. 等待下一个同步周期，检查目标知识库中的文件。

   说明

   同步的文件按原始格式保存，不做格式转换，能否被知识库解析以知识库当前支持的文件格式为准。更多信息，请参见同步行为与文件格式。

步骤一：注册 Microsoft Entra 应用

1. 登录所属租户对应的 Microsoft Entra 管理中心。

2. 进入 Microsoft Entra ID > 应用注册，单击新注册。

3. 填写应用名称，例如 PolarDB SharePoint 文档同步。

4. 在支持的帐户类型中，选择仅此组织目录中的帐户（单租户），然后完成注册。无需配置重定向 URI。

5. 进入应用的概述页面，复制并妥善保存以下信息：

   • 目录（租户）ID：创建同步链路时填写到 TenantId。

   • 应用程序（客户端）ID：创建同步链路时填写到 ClientId。

   重要

   请勿将对象 ID 填写为 ClientId，否则创建同步链路时会失败。

步骤二：创建客户端密码

1. 在应用页面进入证书和密码 > 客户端密码。

2. 单击新客户端密码，填写说明并选择有效期。

3. 创建后立即复制值列中的内容，创建同步链路时填写到 ClientSecret。

   重要

   客户端密码的值只会在创建后显示一次。请勿填写密码 ID，也不要通过邮件、即时通信或截图明文传递客户端密码。如果创建时未及时复制该值，请重新创建一个新的客户端密码，并使用新值创建同步链路。

步骤三：开通 Microsoft Graph 权限

1. 在应用页面进入 API 权限 > 添加权限。

2. 选择 Microsoft Graph > 应用程序权限。

3. 搜索并添加以下权限：

   API	权限类型	权限	用途
   Microsoft Graph	应用程序	Sites.Read.All	读取 SharePoint 站点、文档库、文件夹和文件内容。

4. 单击代表组织授予管理员同意。

5. 确认权限状态显示已为当前组织授予同意。

步骤四：获取 SharePoint 文档库或文件夹地址

1. 使用浏览器打开待同步的 SharePoint 站点。

2. 进入目标文档库：

   • 如果需要同步整个文档库，停留在文档库根目录。

   • 如果只需同步一个文件夹，进入该文件夹。

3. 从浏览器地址栏复制完整地址。

   说明

   请直接复制浏览器地址栏中的文档库视图地址，不要填写单个文件的分享链接、短链接或个人 OneDrive 地址，也无需手动获取站点 ID、文档库 ID 或文件夹 ID。

   格式要求：

   • 使用 HTTPS。

   • 域名以 .sharepoint.com 或 .sharepoint.cn 结尾。

   • 路径以 /Forms/AllItems.aspx 结尾。

   • 同步子文件夹时，地址中包含指向该文件夹的 id 查询参数。

   示例：

   1. 同步整个文档库的地址示例：

      https://contoso.sharepoint.com/sites/Knowledge/Shared%20Documents/Forms/AllItems.aspx

   2. 同步文档库中指定文件夹的地址示例：

      https://contoso.sharepoint.com/sites/Knowledge/Shared%20Documents/Forms/AllItems.aspx?id=%2Fsites%2FKnowledge%2FShared%20Documents%2FProductDocs

   3. 世纪互联环境的地址示例：

      https://contoso.sharepoint.cn/sites/Knowledge/Shared%20Documents/Forms/AllItems.aspx

步骤五：创建 SharePoint 同步链路

您可以通过控制台或CreateKBSyncLink OpenAPI创建SharePoint同步链路。

创建链路时，PolarDB会使用所填应用凭证访问 Microsoft Graph，并确认目标站点、文档库和文件夹可读取。创建成功后，系统返回 pkbl- 开头的同步链路 ID。请妥善记录该 ID，后续查询链路、调整同步周期或删除链路时需要使用。

步骤六：验证同步结果

1. 确认同步链路已创建，并且链路状态无异常。

2. 等待至少一个同步周期。首次同步需要递归扫描目录、下载文件并完成入库和索引处理，文件较多时可能需要更长时间。

3. 进入目标知识库的文件列表，确认已出现来自 SharePoint 的文件。

4. 修改一份已同步的 SharePoint 文件，等待下一个同步周期后检查知识库中的文件是否已更新。

同步行为与文件格式

• 系统会递归扫描所选文档库或文件夹中的子文件夹。

• SharePoint 文件按原始格式下载并同步，不会转换为其他格式。

• 文件是否可被知识库解析，以知识库当前支持的文件格式为准。

• SharePoint 列表项、网页和仅作为目录使用的文件夹不会作为文件同步。

• 当前版本会同步新增和更新的文件，但不会因为 SharePoint 源端删除文件而自动删除知识库中的对应文件。如需删除，请单独处理对应文件。

• TenantId、ClientId 和 ClientSecret 必须属于目标 SharePoint 组织租户，应用所在环境必须与 SharePoint 地址对应同一环境全球版 Microsoft 365 租户对应 .sharepoint.com 地址，世纪互联运营的 Microsoft 365 租户对应 .sharepoint.cn 地址。

常见问题

• Q：创建同步链路失败。

  A：请依次检查：

  • TenantId 是否填写目录（租户）ID。

  • ClientId 是否填写应用程序（客户端）ID，而不是对象 ID。

  • ClientSecret 是否填写客户端密码的值、是否完整且仍在有效期内。

  • Sites.Read.All 是否添加为应用程序权限并已授予管理员同意。

  • SourceDir 是否为浏览器地址栏中的完整文档库视图地址，并以 /Forms/AllItems.aspx 结尾。

  • 应用注册的租户、SharePoint 地址是否属于同一组织，且同属全球版 Microsoft 365 或世纪互联运营的 Microsoft 365 环境。

• Q：只同步了部分文件。

  A：常见原因包括：

  • SourceDir 指向文档库中的某个子文件夹，而不是文档库根目录。

  • 部分文件的格式不在知识库的可解析范围内。

  • 文件的后续入库或索引处理尚未完成。

• Q：修改文件后没有立即更新。

  A：同步任务按 SyncIntervalMinutes 周期执行，源文件下载完成后还需要入库和索引处理。请等待下一个同步周期并预留文件处理时间。