使用 SharePoint 索引器來擷取權限的元資料，並根據使用者存取權篩選搜尋結果（預覽）

SharePoint 權限元資料擷取（預覽版）使用 Azure AI 搜尋服務 索引器來保留權限元資料，例如存取控制清單（ACL），以及 Microsoft 365 中 SharePoint 的其他內容。 索引器會將權限以元資料形式儲存在每份被索引的文件上。 查詢時，使用者只會收到他們有權限存取的文件。

先決條件

• 任何區域中計費層級 (Basic 或更高) 的 Azure AI 搜尋服務。

• 在 Microsoft 365 的網站、函式庫、資料夾和檔案中使用 SharePoint，並為其設定權限。

• 完成 SharePoint 索引器文件 中的所有配置步驟，並依照本文所述的 ACL 特定要求。

• 設定 Microsoft Entra 應用程式權限和適合你情境的憑證。 請參見 ACL 授權情境。 ACL 匯入需要應用程式權限。 不支援委派權限。 關於應用與委派的決策，請參見 「選擇你的權限設定」。

• REST API 版本 2026-08-01-preview 或對應的預覽 SDK 套件。

限制

• 增量 ACL 更新需要使用 2026-05-01-preview REST API 或更新版本的 API。 在早期的預覽 API 版本中，系統僅在每個項目首次擷取時擷取 ACL。 後續權限變更則需明確重新索引。 關於遷移步驟，請參見 索引內容與來源內容之間的權限同步。

• 父範圍權限變更不會在後續索引器執行時自動被偵測。 如需瞭解重新整理選項，請參閱 同步索引內容與來源內容之間的權限。

• Azure 入口網站不支援這個功能。

• 此預覽版不支援下列功能：

  • SharePoint 資訊管理政策適用於使用者存取。 系統不會在查詢時評估、吸收或執行這些政策。

  • 可分享連結 範圍為「任何人」或「你組織中的人」。僅支援「特定人物」範圍的連結。

  • SharePoint群組（如擁有者、會員及訪客群組）自 2026-05-01-preview REST API 起支援。 請參見 配置 SharePoint 群組支援。 在較早的預覽 API 版本中，僅支援可解析為 Microsoft Entra 群組的 SharePoint 群組。

• 以下索引器功能不支援來自 SharePoint 的索引文件權限繼承。 如果你在技能組或索引器中使用這些功能，文件層級的權限不會包含在索引內容中。

  • 自訂的 Web API 功能

  • 知識存放區，包括代理式檢索中影像服務（預覽）所需的資產存放區。 因此，對於內嵌 SharePoint ACL 的知識來源，並不支援映像服務。

  • 索引器增益快取

  • 除錯工作階段

支援 SharePoint 權限模型

此預覽版支援文件、清單項目及現代 ASPX 網站頁面的基本 ACL。

支持性團體關係

Microsoft Entra 群組傳遞性適用於 Microsoft Entra 內部。 它不會展開屬於 SharePoint 群組成員的 Microsoft Entra 群組。

階層式權限如何被評估

SharePoint權限會繼承 Site → Library → Folder → File 的階層，除非繼承被破壞。

在擷取過程中，索引器會在每個層級收集使用者與群組識別碼（ID），並計算每個檔案的有效 ACL。

依 ACL 情境區分的權限

ACL 擷取所需的 Microsoft Entra 應用程式權限和憑證類型，取決於您要建立索引的項目類型和群組類型。 在應用程式註冊中，所有權限都會新增於 API 權限>新增權限 之下，而同盟憑證則會新增於 憑證與秘密>同盟憑證 之下。 如需逐步指示和螢幕擷取畫面，請參閱 步驟 3：建立 Microsoft Entra 應用程式註冊 和 使用受控識別設定已註冊的應用程式。

聯邦憑證是使用受信任的管理身份來驗證應用程式，而非用戶端秘密。 同一聯邦憑證同時涵蓋 SharePoint 網站群組的擷取（索引器）和查詢時的評估。 關於設定步驟，請參見 「以管理身份設定註冊應用程式」。

在啟用 ACL 攝取之前

請在您的註冊 Microsoft Entra 應用程式上完成以下步驟：

1. 根據您計劃編製索引的內容 (文件庫檔案、清單項目、ASPX 網站頁面)，以及是否必須遵守 SharePoint 網站群組，在前一個資料表中識別您的案例。
2. 在Microsoft Entra 系統管理中心開啟你的應用程式註冊，然後到 API 權限>新增權限。
3. 新增你情境中列出的 Microsoft Graph 權限。 授予管理員同意。
4. 如果你的情境也需要SharePoint權限，請再次選擇 新增權限，選擇 SharePoint API，並新增 Sites.FullControl.All（或 Sites.Selected）。 授予管理員同意。
5. 設定憑證：
   • 對於僅適用於 Microsoft Graph 的情境，您可以使用用戶端密碼（Certificates & secrets>Client secrets）或同盟憑證。
   • 對於任何包含SharePoint權限的情況，請在 Certificates & secretsFederated credentials 下新增一個聯邦憑證。 詳見 「以管理身份配置註冊應用程式」。
6. 授權應用程式存取目標SharePoint網站（尤其重要，當你使用 Sites.Selected 作為範圍存取時），這樣它才能讀取你想要索引的內容和權限。

找到正確的 Microsoft Entra 識別碼

每個識別碼會在 Azure 入口網站的不同位置出現，並對應到特定的配置欄位。 在使用同盟認證設定 SharePoint ACL 擷取時，請將本節作為參考。 這些識別碼會在 設定 SharePoint 群組支援以及資料來源連線字串中參照。

聯邦憑證申請識別碼

在資料來源連接字串中的 FederatedCredentialApplicationId 和索引定義中的 federatedCredentialId，請使用受控識別本身的應用程式（用戶端）ID，不要使用擷取應用程式的 ID。

系統指派的受控識別：

1. 前往您的 Azure AI 搜尋服務 服務。
2. 選擇 安全 + 網路>識別碼。
3. 在 系統指派 標籤中，注意物件 （主體）ID。
4. 前往 Microsoft Entra ID>管理>企業應用程式。
5. 搜尋你的搜尋服務名稱，或將 物件（主體）ID 貼上到搜尋框中。
6. 選擇結果並開啟 屬性。 複製此處顯示的應用程式 ID，其為資料來源中的 federatedCredentialId 值，以及索引中的 FederatedCredentialApplicationId 值。

使用者指派的受控識別：

1. 前往使用者指定的管理身份資源。
2. 選取 [設定]> [屬性]。
3. 複製 Client ID，也就是資料來源中 federatedCredentialId 的值，以及索引中 FederatedCredentialApplicationId 的值。

設定您的搜尋服務，以支援 ACL 擷取和查詢時強制執行

這些步驟會設定您的搜尋服務以便進行 ACL 擷取，並在查詢時啟用 ACL 接受。

選擇填入 ACL 欄位的位置

ACL 元資料欄位的映射位置取決於索引器是每個來源項目寫一份文件，還是每個來源項目寫多個區塊。

在所有分塊情境中，每個分塊都必須攜帶 ACL 欄位。 權限過濾器會依文件套用，因此缺少 ACL 欄位的區塊無法回傳給正確的呼叫者。

1. 資料來源配置

本節是在基礎步驟 4：建立資料來源逐步解說之上的差異。 在indexerPermissionOptions中設定，以便從 SharePoint 文件中索引userIds和groupIds。

{
  "name": "my-sharepoint-acl-datasource",
  "type": "sharepoint",
  "indexerPermissionOptions": ["userIds", "groupIds"],
  "credentials": {
    "connectionString": "<connection-string>;"
  },
  "container": {
    "name": "<library-name>",
    "query": "<optional-folder-path>"
  }
}

2. 在索引定義中加入權限欄位

在 你的索引架構定義 中加入欄位以儲存 ACL 並支援查詢時過濾。

{
  "fields": [
    { "name": "UserIds",  "type": "Collection(Edm.String)", "permissionFilter": "userIds",  "filterable": true, "retrievable": false },
    { "name": "GroupIds", "type": "Collection(Edm.String)", "permissionFilter": "groupIds", "filterable": true, "retrievable": false }
  ],
  "permissionFilterOption": "enabled"
}

在開發期間，僅將 retrievable 屬性設為 true 以驗證數值。 你可以將可提取性由 true 更改為 false，且不需要索引重建。

3. 在你的技能組中設定指標投影（如適用）

當啟用分區時，當 projectionMode 為 skipIndexingParentDocuments時，父文件不會寫入索引。 透過 indexProjections.selectors[].mappings 將 ACL 中繼資料傳遞到每個區塊中。

如果你的索引器使用資料分塊的技能，例如啟用整合向量化時的文字分割技能，務必用索引投影將 ACL 屬性映射到每個區塊。 //以下範例中的行是說明性註解，並非有效的 JSON。 提交申請前請先移除這些資料。

PUT https://{service}.search.windows.net/skillsets/{skillset}?api-version=2026-08-01-preview
{
  "name": "my-skillset",
  "skills": [
    {
      "@odata.type": "#Microsoft.Skills.Text.SplitSkill",
      "name": "#split",
      "context": "/document",
      "inputs": [{ "name": "text", "source": "/document/content" }],
      "outputs": [{ "name": "textItems", "targetName": "chunks" }]
    }
    // ... (other skills such as embeddings, entity recognition, etc.)
  ],
  "indexProjections": {
    "selectors": [
      {
        "targetIndexName": "chunks-index",
        "parentKeyFieldName": "parentId",          // must exist in target index
        "sourceContext": "/document/chunks/*",     // match your split output path
        "mappings": [
          { "name": "chunkId",           "source": "/document/chunks/*/id" },     // if you create an id per chunk
          { "name": "content",           "source": "/document/chunks/*/text" },   // chunk text
          { "name": "parentId",          "source": "/document/id" },              // parent doc id
          { "name": "UserIds",  "source": "/document/metadata_user_ids" },
          { "name": "GroupIds",  "source": "/document/metadata_group_ids" },
          { "name": "SharePointSiteUrl", "source": "/document/metadata_spo_site_url" } // include when the index has sharePointConnectorAppRegistration (SharePoint groups support)
        ]
      }
    ],
    "parameters": {
      "projectionMode": "skipIndexingParentDocuments"
    }
  }
}

UserIds、GroupIds 和 SharePointSiteUrl 映射讀取由 SharePoint 索引器（/document/metadata_*）所發出的來源層元資料，並將值寫入每個區塊。

4. 配置索引器欄位與 ACL 的映射关系

當索引器為每個來源項目寫入一份文件（不進行分塊），或同時維護獨立的父索引和區塊索引時，請使用索引器欄位對應。 如果您的技能組使用 projectionMode: skipIndexingParentDocuments 將文件分塊到單一目標索引中，這裡顯示的欄位對應會由前一步中針對區塊索引的 indexProjections.mappings 取代。

除了你必須的 indexer 配置外，還需要將來自 SharePoint 的原始元數據 ACL 欄位映射到你的索引欄位。

{
  "fieldMappings": [
    { "sourceFieldName": "metadata_user_ids",  "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids", "targetFieldName": "GroupIds" }
  ]
}

5. 執行索引器

索引器執行時會擷取 ACL 元資料。 在建立或更新索引器（見 步驟 6：建立索引器）後，觸發執行，讓索引器同時吸收 ACL 和內容。

POST https://[service name].search.windows.net/indexers/[indexer-name]/run?api-version=2026-08-01-preview
api-key: [admin key]

如果你在已編製索引項目的現有索引器上啟用 ACL 擷取，請使用 /resync 呼叫 options: ["permissions"]，以回填這些項目的 ACL；或者使用 /resetdocs 重新擷取特定項目。

6. 驗證 ACL 擷取

確認 ACL 值已正確填入：

1. 在你的索引定義中，暫時將 retrievable 在 true 和 UserIds 上設為 GroupIds。 更改 retrievable 不需要重新建立指數。
2. 執行一個 提升讀取的查詢 ，選擇 UserIds 和 GroupIds，並確認集合不是空的。 對於分塊情境，請確認每個分塊同時包含兩個欄位。
3. 驗證後，將retrievable返回至false。

設定 SharePoint 群組支援

從 2026-05-01-preview REST API 開始，SharePoint 索引器可以整合 SharePoint 網站群組成員資格（擁有者、成員、訪客及自訂網站群組）。 它會在查詢時遵守這些群組。 SharePoint 群組 ID 會在 metadata_group_ids 欄位中輸出，並加上 spg: 前綴，以便與 Microsoft Entra 群組物件 ID 區別。

此逐步解說為獨立內容：依序完成步驟以設定索引、索引子欄位對應，並使用 SharePoint 網站群組強制執行查詢索引。

以下元件協同運作以啟用 SharePoint 站點群組解析：

1.Prerequisites

• SharePoint 索引器已經設定好可以擷取 ACL 了。 請參見「配置索引器欄位映射以支援 ACL」。
• Microsoft Entra 應用程式註冊使用聯邦身份憑證。 詳見 「以管理身份配置註冊應用程式」。
• REST API 2026-05-01-preview 或較新版本。

2. 配置索引

將 sharePointConnectorAppRegistration 組態和 SharePointSiteUrl 欄位加入，並與 UserIds 和 GroupIds 權限篩選欄位並列，讓完整的索引結構集中在同一處。 保留 permissionFilterOption: "enabled"。

PUT https://{service}.search.windows.net/indexes/{index}?api-version=2026-08-01-preview
{
  "name": "my-sharepoint-acl-index",
  "sharePointConnectorAppRegistration": {
      "applicationId": "<ingestion-app-client-id>",
      "federatedCredentialId": "<managed-identity-application-id>",
     "tenantId": "<sharepoint-tenant-id>"
  },
  "fields": [
    { "name": "UserIds",           "type": "Collection(Edm.String)", "permissionFilter": "userIds",  "filterable": true, "retrievable": false },
    { "name": "GroupIds",          "type": "Collection(Edm.String)", "permissionFilter": "groupIds", "filterable": true, "retrievable": false },
    { "name": "SharePointSiteUrl", "type": "Edm.String", "sharepointSiteUrl": true, "filterable": false, "retrievable": false }
  ],
  "permissionFilterOption": "enabled"
}

3. 配置索引器欄位映射

將 SharePoint 的元資料欄位映射到單一合併映射區塊中的索引欄位。 前兩種映射與標準 ACL 擷取相同;第三個映射則啟動 SharePoint 群組解析。

{
  "fieldMappings": [
    { "sourceFieldName": "metadata_user_ids",             "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids",            "targetFieldName": "GroupIds" },
    { "sourceFieldName": "metadata_spo_site_url",  "targetFieldName": "SharePointSiteUrl" }
  ]
}

如果您的技能組會將文件分塊（例如使用 Text Split 技能進行整合式向量化時），請改為透過 SharePointSiteUrl 將 indexProjections.mappings 投影到每個區塊。 請參閱 「選擇填入 ACL 欄位的位置」。

4. 查詢索引

用戶端不需更改。 同一個 x-ms-query-source-authorization 標記同時啟動 Microsoft Entra 和 SharePoint 站點群組強制執行。 搜尋服務會在伺服器端使用 sharePointConnectorAppRegistration 在索引上解析 SharePoint 群組成員資格。

關於要求格式，請參閱 一般查詢範例以及 SharePoint 專屬的 含有 SharePoint 網站群組強制執行的範例。

5. 驗證

要確認索引中有SharePoint 群組 ID，請執行 elevated-read查詢，選擇 GroupIds，並在回應中尋找 spg: 前綴值。

同步索引內容與來源內容之間的權限

自 2026-05-01-preview REST API 起，對於具有獨特權限的項目，ACL 變更會在每次成功執行索引器時被偵測並刷新。 索引器使用 SharePoint 變更標記，逐步接收角色分配的新增與移除，就像接收內容變更一樣。

某些情境仍然需要明確執行重新整理：

重置特定文件

您可以重設特定文件，以重新完整擷取內容與 ACL。

POST https://{service}.search.windows.net/indexers/{indexer}/resetdocs?api-version=2026-08-01-preview
{
  "documentKeys": ["doc123", "doc456"]
}

在完整資料來源中重新同步 ACL

你可以在初次擷取後 重新同步完整的 ACL 內容 。 要完全成功，此操作需要在完成後 執行索引器 。

POST https://{service}.search.windows.net/indexers/{indexer}/resync?api-version=2026-08-01-preview
{
  "options": ["permissions"]
}

索引完資料和 ACL 後，你可以查詢索引。

Troubleshooting

如需了解在 ACL 中繼資料建立索引後查詢時遺失、非預期或失敗的結果，請參閱 疑難排解 SharePoint 權限篩選。

相關內容

• 索引Azure AI 搜尋服務（預覽）中的 SharePoint 內容
• 查詢時 ACL 強制執行