在 Foundry IQ(Azure AI 搜尋服務)中排除 SharePoint 權限篩選問題

附註

Foundry IQ(Azure AI 搜尋服務)提供直接的索引與查詢 API,並搭配高階知識來源與知識庫 API 用於受控檢索。 使用 Azure 入口網站、REST API 或 Azure SDK 來設定這些功能,或將代理連線到 Microsoft Foundry 入口網站 中的知識庫。

如果對已建立索引的 SharePoint 內容進行查詢時,權限篩選傳回遺漏的結果或非預期的結果,或者經過權限篩選的查詢失敗,請參閱本文。

先決條件

  • 一個由 Microsoft 365 索引器中 SharePoint 填充的索引,並已設定 ACL 擷取。
  • 查詢時的權限篩選已按照 查詢時 ACL 與 RBAC 強制執行中的說明完成設定。
  • SharePoint 權限篩選的 REST API 版本2026-10-01。
  • 存取索引定義、產生或明確索引器狀態,以及測試使用者的 SharePoint 權限。
  • 若需要比較篩選與未篩選的結果,需具備 Search Index Data Contributor 或同等的提高讀取權限。

請依照故障排除決策樹操作

請依序完成這些檢查。 一旦觀察到的結果指出需要修正的設定或權限,就停止。

1. 確認失敗發生於查詢時

本文介紹了 SharePoint 內容與 ACL 元資料索引後的權限過濾。

只有當有索引權限的元資料存在且查詢時會出現症狀時,請繼續此處。

2. 識別三個身分識別

記錄哪個身分擔任各個角色。 不要用一個識別碼替代另一個。

Identity Purpose 驗證地點
正在查詢使用者 委派的使用者憑證 x-ms-query-source-authorization 決定使用者可檢索哪些受保護文件。 你的應用程式認證流程和查詢請求。
SharePoint connector 應用程式註冊 索引上的 sharePointConnectorAppRegistration 可讓 Foundry IQ(Azure AI 搜尋服務)解析查詢使用者的 SharePoint 網站群組成員資格。 設定 SharePoint 群組支援中所述的索引定義和應用程式註冊。
Foundry IQ 請求身分 Authorization 標頭中的 Microsoft Entra 持有人權杖,或 api-key 標頭中的 API 金鑰,用來驗證對 Foundry IQ 服務提出的要求。 該身分必須具有查詢索引的權限。 您的查詢用戶端與 Foundry IQ 資料平面角色指派。

3. 檢查權限過濾器設定

將索引、索引器和產生的物件與其擁有者文章進行比較。

  1. 確認指數已 permissionFilterOption 設定為 enabled。
  2. 確認 UserIds 並 GroupIds 取得正確的 permissionFilter 數值。
  3. 對於 SharePoint 網站群組,請確認索引具有 sharePointConnectorAppRegistration 以及含有 sharepointSiteUrl: true 的 SharePointSiteUrl 欄位。
  4. 確認每個索引文件或區塊都包含適用的權限欄位。 如果技能組使用索引投影,請確認 ACL 欄位位於 indexProjections.selectors[].mappings 中。
  5. 確認索引中有所需的 metadata_spo_item_path 欄位,且投影區塊保留來源路徑。 資產/項目 ID 或網站 URL 並不能取代它。

如果缺少任何值,請返回 「設定您的 Foundry IQ 服務以進行 ACL 匯入及查詢時強制執行」。

對於元資料與生命週期徵狀,請將檢查範圍縮小至受影響的來源項目及其索引文件或區塊。

徵兆 重點檢查與下一步行動
來源路徑遺失或與項目不符 將 metadata_spo_item_path 與來源中繼資料比較。 檢查所需的命名欄位以及每個區塊的 /document/metadata_spo_item_path 投影結果。 項目金鑰、網頁 URL 或網站 URL 並不能作為替代。 修正對應並重新處理受影響項目。
不同站點的原生站點群組存取方式有所不同 將每個項目 metadata_spo_site_url 與標示為 sharepointSiteUrl: true的欄位進行比較。 檢查投影是否保留來源網站,而非固定網站。 檢視每個站點的連接器同意與所選站點授權。
清單、頁面或混合項目遺失或有意外的鍵值 對於使用 allSiteLists、allSitePages 或 allSiteContent 直接設定的索引器,請檢查 metadata_spo_site_asset_item_id 鍵對應與編碼。 請使用連接器的金鑰說明,而非以路徑或網站 URL 作為替代。
父層項目看起來正確,但區塊卻不同 檢視所產生或明確技能組合的投影及實際的子紀錄。 在每個區塊上驗證內容、來源路徑、ACL 以及適用的網站上下文。 不要為投影產生的鍵或父身份新增手動對應。
舊紀錄在重新整理、移動、重新命名或刪除後仍保留 檢查來源選擇路徑、索引器警告與失敗,以及目前與較早的文件與區塊鍵。 區分 權限刷新與內容及生命週期處理;請分別核對過時的紀錄。

使用索引器診斷工具處理遺失、空路徑、畸形或無法解決的路徑;不要僅從欄位值推斷出特定的錯誤或授權結果。 對於已編入索引的知識來源,也要完成其 生成資源檢查。

4. 安全地檢查查詢令牌

不要記錄、不要貼上支援請求,也不要分享完整存取權杖。 只解碼本地的標記有效載荷,並在擷取診斷輸出前先清除識別碼。

  1. 請確認該要求包含 x-ms-query-source-authorization,並附有測試使用者目前有效的委派權杖。
  2. 在本機解碼承載資料,並確認 oid 識別的是預期的測試使用者。 記錄一個經過消毒的值,例如 <test-user-object-id>。
  3. 如果令牌遺失或過期,請重新驗證並重試。

若使用者代幣被省略,權限保護的內容將無法回傳。 僅靠 Authorization 標頭並不能取代 x-ms-query-source-authorization。

5. 檢查 Microsoft Entra 權限

  1. 確認索引UserIds或GroupIds包含預期的 Microsoft Entra 物件 ID。 僅限於此次診斷比較使用 提高讀取權限的查詢。
  2. 確認測試使用者是否擁有直接指派,或在支援的五個巢狀層級內透過巢狀群組關係隸屬於已指派的群組。
  3. 如果 Microsoft Entra 群組巢狀於 SharePoint 群組 內,請檢查巢狀深度及 SharePoint 群組 設定。 超過五層的路徑不會透過該路徑授與存取權;另一個受支援的授權仍可能適用。

關於具體的支持邊界,請參見 支持性團體關係。

6. 檢查 SharePoint 網站群組權限

當文件 ACL 依賴於擁有者、會員、訪客或自訂 SharePoint 網站群組時,請完成此步驟。

  1. 使用 elevated-read 查詢確認 GroupIds 是否包含帶有預期 spg: 前綴的群組 ID,且 SharePointSiteUrl 可識別來源網站。
  2. 確認測試使用者是否是該 SharePoint 群組 的直接成員,或是透過支援的 Microsoft Entra 群組巢狀路徑連接該群組。
  3. 確認索引sharePointConnectorAppRegistration是否使用了 SharePoint 群組支援所需的識別碼和權限。

如果索引欄位是空的或過時的,請先修正擷取或同步 SharePoint 權限,再重新測試查詢。

對於缺少巢狀群組結果,請同時檢視 站點層級的 10,000 個安全性主體限制。 它和巢狀深度以及測試使用者的群組數是分開的。 僅靠重新索引無法解決此查詢時門檻。

成員資格結果會快取,因此網站群組設定的變更可能不會在下一次查詢中顯示。 將支援的直接指派與巢狀群組路徑進行比較,以隔離問題。 如果問題持續存在,請收集 請求關聯詳細資料 以供支援使用,而非反覆重新索引。 調查期間請保持權限過濾功能啟用。

7. 檢查查詢請求

  1. 使用 REST API 版本2026-10-01用於 SharePoint 權限篩選器。
  2. 確認 Authorization 會驗證可查詢索引的主體身分。
  3. 確認 x-ms-query-source-authorization 包含委派的測試使用者標記。
  4. 重新嘗試同一個查詢,不要使用無關的篩選或排名變更,這樣你才能隔離權限行為。

使用一般查詢範例,並以其要求格式為準。 請勿在儲存的要求或記錄中包含完整權杖。

如果無法評估授權,請在不回傳受保護內容或以提升或未過濾存取方式重試的情況下處理錯誤。 請參閱「 處理授權與更新失敗 」以了解應用程式與推送管線的職責。

8. 比較預期結果與實際結果

  1. 選擇一份測試使用者能存取的文件,以及一份使用者無法在 SharePoint 存取的文件。
  2. 以測試使用者身份執行權限篩選查詢,僅記錄文件金鑰或其他非秘密識別碼。
  3. 執行以提高權限執行的讀取查詢,並將儲存的 UserIds、GroupIds 和 SharePointSiteUrl 值與來源權限進行比較。
  4. 如果 elevated read 回傳預期文件,但使用者查詢沒有,請檢查使用者標記、儲存的 ACL 值與新鮮度,以及群組解析。 如果 elevated read 也漏掉了,請檢查內容匯入、來源選擇及索引鍵。

比較支援的明確使用者與群組指派,包括繼承的指派,而非組織範圍的共用連結。 不支援全組織連結及分享連結過期強制執行。 連結過期並不代表獨立的明確授權被撤銷。 在 SharePoint 中開啟檔案,與擷取其已索引內容是分開的存取檢查。

在來源權限變更後,檢查同步情境表及索引器執行狀態。 查詢不會啟動索引器,且要求的執行未顯示 ACL 處理已完成。

  1. 在 SharePoint 中,檢查受影響項目是否繼承權限或擁有獨特權限。 例如,繼承資料夾權限的檔案會跟隨該資料夾的指派;具有獨特權限的檔案會保留其自身的指派。
  2. 確認相關索引器執行已完成,然後將索引中的 ACL 與該項目的來源指派進行比較。 對於區塊內容,也要檢查受影響的區塊。
  3. 依照情境表選擇一般增量處理、權限重新同步或來源項目重新處理。 如果結果仍不一樣,請擷取 請求關聯詳細資料。

提高權限後進行讀取僅供調查之用。 不要用它來回傳無限制的結果給終端使用者。

9. 擷取請求關聯詳細資料

如果查詢仍然失敗,請擷取 API 版本、UTC 時間戳、經過消毒的請求主體、HTTP 狀態、回應標頭,以及服務回傳的任何請求或關聯 ID。 請提供索引名稱,以及提高權限後進行讀取時是否會顯示同一份文件。

在與 Microsoft 支援服務 分享診斷資料前,請移除存取權杖、API 金鑰、秘密、使用者名稱及租戶專屬網址。