AB
AB
AiBoss

All Categories

Tutorials

Azure AI Search 接入 SharePoint Online 文档：从 Entra 授权到知识源创建

Tutorials

Azure AI Search 接入 SharePoint Online 文档：从 Entra 授权到知识源创建

用 Azure AI Search 的 Indexed SharePoint Knowledge Source 把 SharePoint Online 文档库接入检索与智能体知识库。本文按顺序说明权限方式选择、托管标识启用、Entra 应用注册与站点级授权、联合凭据配置、门户向导创建知识源以及抓取结果校验，并给出 Graph Explorer 与 PnP PowerShell 两条授权路径。

把 SharePoint Online 里的文档库变成可检索的知识，是很多团队做企业搜索或智能体问答时的第一步。Azure AI Search 提供的 Indexed SharePoint Knowledge Source 就是为此设计的：创建知识源后，Azure AI Search 会自动生成 SharePoint 专用的数据源、技能组、索引和索引器，省去手工拼装各组件的麻烦。本文面向负责搭建检索服务的工程师与管理员，按顺序走完从权限规划到抓取校验的全过程。需要提前说明的是，SharePoint 索引器属于预览功能，功能范围与可用性可能变化，落地前请以官网当前信息为准。

准备工作

开始之前，先确认下面这些条件都已具备，否则中途很容易卡在授权环节。

  • 一个可用的 Azure AI Search 服务。
  • 一个 SharePoint Online 站点，以及要抓取的目标文档库。
  • 能够为目标站点配置权限的 SharePoint 管理员。
  • 能够注册 Microsoft Entra 应用并授予管理员同意的管理员。
  • 创建知识源所需的 Azure AI Search 权限。推荐使用 Search Service Contributor 与 Search Index Data Contributor。
  • 如果要做向量化，需要提前部署嵌入模型，例如 Foundry 模型中的嵌入模型。

另外要理解整体结构：知识源只是把数据源、技能组、索引、索引器打包在一起的封装。即使不通过知识源，而是手工分别配置这些组件，基本的设置流程也是一致的。本文走的是门户向导这条路径。

操作步骤

第一步：确定 SharePoint 的权限方式

抓取用的 Entra 应用需要具备读取 SharePoint 内容的应用程序权限。常见的有两种选择，访问范围差别很大，实际配置时按需求二选一即可。

权限访问范围设置后还需要做什么
Sites.Read.All应用可广泛读取租户内的 SharePoint 站点为 Entra 应用授予管理员同意
Sites.Selected应用只能访问被单独指定的站点除管理员同意外，还要为每个目标站点单独授予应用权限

对于标准的文档库抓取场景，一种常见做法是把 Microsoft Graph 的应用程序权限设为 Files.Read.All 与 Sites.Read.All。如果选择 Sites.Selected，仅添加权限是不够的，必须逐个站点授权，否则应用依然读不到内容。

第二步：启用 Azure AI Search 的托管标识

在 Azure 门户中打开 Azure AI Search 服务，进入「设置」下的「标识」，把「系统分配」的状态切换为开启并保存。保存后页面上会显示该标识的对象（主体）ID，请记下来——后面为 Entra 应用创建联合凭据时，需要用它来指定信任哪个托管标识。

第三步：注册抓取用的 Entra 应用并配置权限

在 Azure 门户中进入「Microsoft Entra ID」→「应用注册」→「新注册」，输入应用名称，在目标租户中完成注册。

接着打开该应用的「API 权限」，选择「添加权限」→「Microsoft Graph」→「应用程序权限」，按上一步选定的方式添加：

  • 使用 Sites.Read.All 方式时：添加 Sites.Read.All、Files.Read.All、User.Read。
  • 使用 Sites.Selected 方式时：添加 Sites.Selected、Files.Read.All、User.Read。

添加完成后，选择「代表管理员授予同意」。这一步需要具备授予租户级管理员同意的管理员来操作。

如果选择的是 Sites.Selected，还需要为每个要索引的 SharePoint 站点单独授予应用访问权限。抓取内容的目的下，至少授予 read 角色。下面给出两条路径，按组织策略选择其一。

路径 A：用 Graph Explorer 执行 REST API

Graph Explorer 是 Microsoft 提供的一个应用，以登录用户的身份委派权限来调用 Microsoft Graph API。使用它本身也需要为 Graph Explorer 授予委派权限并完成管理员同意，这与前面给抓取应用授予 Sites.Selected 管理员同意是两件独立的事。

1. 登录并授予 Graph Explorer 权限。打开 Graph Explorer，用目标租户的管理员账号登录。如果弹出读取用户信息的同意提示，选择同意。然后在个人资料菜单中找到「Consent to permissions」，搜索 Sites.FullControl.All 并点击同意。在管理员同意页面确认请求的权限与目标组织后，选择「以组织代表的身份同意」。这一步需要能够授予租户级管理员同意的管理员。仅仅登录并不会自动获得 Sites.FullControl.All。同意页面是否出现、何时出现，取决于现有的同意状态与组织策略；如果所需权限此前已由管理员同意，页面可能不再弹出。若组织不允许向 Graph Explorer 授权，请改用下面的 PowerShell 路径。

2. 获取目标站点的 siteId。假设目标站点 URL 为 https://<tenant>.sharepoint.com/sites/AUSearch，在 Graph Explorer 中执行：

GET https://graph.microsoft.com/v1.0/sites/<tenant>.sharepoint.com:/sites/AUSearch

响应中的 id 就是下一步要用的 siteId。它的格式是主机名、站点集合 ID、站点 ID 三者用逗号连接：

{
  "id": "contoso.sharepoint.com,<site-collection-id>,<site-id>",
  "webUrl": "https://contoso.sharepoint.com/sites/AUSearch"
}

在 Graph Explorer 中读取站点，要求登录用户本身能访问该站点，同时 Graph Explorer 侧具备所需的 Microsoft Graph 权限。调用是以登录用户的委派权限执行的。

3. 通过 REST API 给抓取应用授予 read。把上一步拿到的完整 id 填入 URL 中的 {siteId} 位置，执行下面的 POST 请求。请求体里 application.id 填抓取应用的客户端 ID：

POST https://graph.microsoft.com/v1.0/sites/{siteId}/permissions
Content-Type: application/json

{
  "roles": ["read"],
  "grantedToIdentities": [
    {
      "application": {
        "id": "<抓取用应用的客户端ID>",
        "displayName": "<抓取用应用的显示名>"
      }
    }
  ]
}

抓取应用的客户端 ID 与显示名可以在应用注册的概述页面找到。返回 201 Created，且响应中包含目标应用与 roles: ["read"]，即表示授权成功。

路径 B：用 PnP PowerShell 配合管理用应用

如果组织不允许把权限委派给 Graph Explorer，可以另外创建一个管理用应用，在 PowerShell 登录时使用。这条路径同样是对交互式登录的委派认证，使用的是登录管理员的权限，区别只是委派对象从 Microsoft 提供的 Graph Explorer 换成了自己注册的应用。

1. 安装 PnP PowerShell。在 PowerShell 7.4 及以上版本中执行：

Install-Module PnP.PowerShell -Scope CurrentUser

请使用 PowerShell 7，不要用 Windows PowerShell 5.1。

2. 准备 PowerShell 管理用的 Entra 应用。这个应用要与 Azure AI Search 的抓取应用分开注册。如果组织已有获批的 PnP 管理用应用，可以直接复用。两者的分工如下：

应用用途与站点授权相关的 Microsoft Graph 权限
抓取用应用Azure AI Search 读取目标站点应用程序权限 Sites.Selected
PowerShell 管理用应用管理员为抓取应用授予站点权限委派权限 Sites.FullControl.All

管理用应用的配置步骤：在「Microsoft Entra ID」→「应用注册」→「新注册」中注册，记下应用程序（客户端）ID；在「认证」→「添加平台」→「移动应用和桌面应用」中，把重定向 URI 设为 http://localhost；在「API 权限」→「添加权限」→「Microsoft Graph」→「委派权限」中添加 Sites.FullControl.All，并由有权限的管理员选择「代表管理员授予同意」。

3. 以管理员身份连接并授予 read。把下面的值替换成实际环境后执行。浏览器打开后，用具备 SharePoint 管理员及以上角色的账号登录：

$siteUrl = "https://<tenant>.sharepoint.com/sites/<site-name>"
$managementAppId = "<PowerShell 管理用应用的客户端ID>"
$ingestionAppId = "<抓取用应用的客户端ID>"

Connect-PnPOnline `
  -Url $siteUrl `
  -ClientId $managementAppId `
  -Interactive

$permission = Grant-PnPEntraIDAppSitePermission `
  -AppId $ingestionAppId `
  -DisplayName "<抓取用应用的显示名>" `
  -Permissions Read `
  -Site $siteUrl

$permission

注意区分两个 ID：Connect-PnPOnline 的 -ClientId 是管理用应用，Grant-PnPEntraIDAppSitePermission 的 -AppId 是抓取用应用。不要与 Azure AI Search 的托管标识混淆。

4. 确认已授予的权限。执行下面的命令，检查返回的 Roles 是否为 read：

Get-PnPEntraIDAppSitePermission `
  -Site $siteUrl `
  -PermissionId $permission.Id

Disconnect-PnPOnline

这里有一个限制：不指定 PermissionId 的查询不会显示 Roles，所以要使用授权时返回的 ID 来查询。如果目标站点有多个，需要逐个站点执行连接、授权与确认。

第四步：为 Entra 应用添加联合凭据

打开抓取用应用注册的「证书和密码」→「联合凭据」，选择「添加凭据」。场景选择「托管标识」，然后选中第二步启用的 Azure AI Search 托管标识，起个名字并保存。这样 Entra 应用就会信任 Azure AI Search 的托管标识，实现无需密码的认证。

第五步：在门户向导中创建知识源

1. 打开创建页面。在 Azure 门户中打开目标 Azure AI Search 服务，进入「Agentic retrieval」→「Knowledge sources」→「添加知识源」，选择用于 SharePoint 索引抓取的来源类型。

2. 配置 SharePoint 连接信息。输入知识源名称后，启用托管标识认证，用第三步、第四步准备好的抓取应用与联合认证连接目标 SharePoint 站点。需要填写的信息如下：

设置项取值
SharePoint 站点 URL要抓取的站点 URL
应用程序 ID已配置 SharePoint 权限的抓取用应用的客户端 ID
租户 ID拥有该 SharePoint 站点的 Entra 租户 ID
联合认证使用的 IDAzure AI Search 托管标识的对象 ID

应用程序 ID 与租户 ID 可以在应用的概述页面确认，联合认证使用的 ID 可以在应用的「证书和密码」页面确认。

在指定文档库与抓取范围的项目中，确认目标库。抓取默认文档库的设置对应默认站点库（API 上为 defaultSiteLibrary）。如果要用 query 指定抓取范围，容器名使用 useQuery。下面是查询栏的输入示例，URL 请替换为实际的站点与库：

  • 只抓取特定文档库：includeLibrary=<库的URL>
  • 从站点内全部库中排除指定库：includeLibrariesInSite=<库的URL>，多个用分号 ; 分隔。

要注意，query 只用于指定抓取对象，并不会扩大应用的访问权限。

如果界面要求填写连接字符串，使用下面的格式：

SharePointOnlineEndpoint=https://<tenant>.sharepoint.com/sites/<site-name>;ApplicationId=<抓取用应用的客户端ID>;TenantId=<SharePoint的租户ID>;FederatedCredentialApplicationId=<Search托管标识的客户端ID>

连接字符串方式下，ApplicationId 是抓取用应用的客户端 ID，FederatedCredentialApplicationId 是 Azure AI Search 托管标识的客户端 ID。不要填成 Graph Explorer 或 PowerShell 管理用应用的 ID，也不要填托管标识的对象 ID。客户端 ID 可以在 Entra ID 中通过搜索对象 ID 得到。

3. 确认向量化等抓取设置。如果要做文本向量化，在向导的向量化设置中指定准备好的嵌入模型资源与部署。访问模型时使用 Azure AI Search 的托管标识进行认证，因此该托管标识还需要在嵌入模型资源上具备 Cognitive Services User 或 Foundry User 角色。如果界面出现图像处理、同步计划、权限元数据抓取等项目，按实际用途确认即可。若希望检索时反映 SharePoint 的权限，需要额外关注 ACL 相关的配置。

4. 检查设置并创建。确认站点 URL、认证信息、抓取范围与模型设置后创建知识源。创建完成后，确认它出现在 Knowledge sources 列表中。随着知识源创建，SharePoint 用的数据源、技能组、索引与索引器也会一并生成。

第六步：确认抓取状态

在 Azure 门户的 Azure AI Search 服务中打开生成的索引器，从运行历史查看抓取执行结果，确认没有错误或失败的文档；如果有警告，也要逐条查看内容。

接着打开生成的索引，确认文档数量，并用搜索资源管理器检索目标文档，验证结果是否符合预期。

一个完整示例

下面把关键环节串成一个最小可跑通的流程，站点为 https://contoso.sharepoint.com/sites/AUSearch，采用 Sites.Selected 方式。

  1. 在 Azure 门户中打开 Azure AI Search 服务，进入「设置」→「标识」，开启系统分配的托管标识，记下对象 ID。
  2. 在「Microsoft Entra ID」→「应用注册」中新建应用 sp-ingest-app，在「API 权限」中添加 Microsoft Graph 应用程序权限 Sites.Selected、Files.Read.All、User.Read，并授予管理员同意。
  3. 在 Graph Explorer 中登录管理员账号，为 Graph Explorer 授予 Sites.FullControl.All 的委派权限并完成管理员同意。
  4. 执行 GET https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com:/sites/AUSearch，从响应中取出形如 contoso.sharepoint.com,<site-collection-id>,<site-id> 的 id。
  5. 执行 POST https://graph.microsoft.com/v1.0/sites/{siteId}/permissions，请求体中的 application.id 填 sp-ingest-app 的客户端 ID，roles 为 ["read"]，确认返回 201 Created。
  6. 回到 sp-ingest-app 的「证书和密码」→「联合凭据」，添加托管标识类型的凭据，选中第 1 步的 Azure AI Search 托管标识。
  7. 在 Azure AI Search 服务中进入「Agentic retrieval」→「Knowledge sources」→「添加知识源」，选择 SharePoint 来源，启用托管标识认证，填入站点 URL、sp-ingest-app 的客户端 ID、SharePoint 租户 ID 与托管标识对象 ID，抓取范围按需填写 includeLibrary=。
  8. 创建知识源后，打开自动生成的索引器查看运行历史，再打开索引确认文档数量，并在搜索资源管理器中检索一篇已知文档。

注意事项

  • SharePoint 索引器是预览功能，功能范围、可用性与行为可能变化，正式使用前请以官网当前信息为准。
  • Sites.Selected 与 Sites.Read.All 的访问范围不同。选择 Sites.Selected 时，仅完成管理员同意并不能让应用读到站点内容，必须为每个目标站点单独授予 read 权限。
  • 为 Graph Explorer 授予 Sites.FullControl.All 与为抓取应用授予 Sites.Selected 是两次独立的同意操作，不要混为一谈。若组织策略不允许向 Graph Explorer 委派权限，改用自建管理用应用配合 PnP PowerShell。
  • PnP PowerShell 需要 PowerShell 7.4 及以上版本，不要使用 Windows PowerShell 5.1。
  • 查询已授予的站点权限时，必须指定授权时返回的 PermissionId，否则返回结果中不会显示 Roles。
  • 连接字符串中的 ApplicationId 与 FederatedCredentialApplicationId 都要求客户端 ID，不要误填对象 ID，也不要填成 Graph Explorer 或管理用应用的 ID。
  • query 参数只控制抓取对象，不会扩大应用的访问权限。
  • 做向量化时，Azure AI Search 的托管标识需要在嵌入模型资源上具备 Cognitive Services User 或 Foundry User 角色。
  • 多个目标站点需要逐个执行授权与确认。
Back