疑難排解 Azure AI 搜尋服務 中的 SharePoint 權限篩選問題 (預覽)

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

先決條件

• 一個由 Microsoft 365 索引器中 SharePoint 填充的索引，並已設定 ACL 擷取。
• 查詢時的權限篩選已按照 查詢時 ACL 與 RBAC 強制執行中的說明完成設定。
• 使用 SharePoint 站點群組時，請使用REST API 版本2026-08-01-preview或等效的預覽 SDK 套件。
• 存取索引定義、產生或明確索引器狀態，以及測試使用者的 SharePoint 權限。
• 如果你需要比較篩選與未篩選結果，請搜尋索引資料貢獻者或等效的升讀權限。

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

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

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

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

• 如果建立資料來源或執行索引子時回報 Invalid AAD tenant，請依照 Microsoft Entra 租用戶補救措施進行處理。
• 如果您需要更正TenantId、驗證或資料來源連接字串，請參閱設定 Microsoft 365 中的 SharePoint 索引器。
• 如果在建立索引期間缺少 UserIds、GroupIds 或 SharePointSiteUrl，請使用 ACL 擷取疑難排解表。

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

2. 識別三個身分識別

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

3. 檢查權限過濾器設定

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

1. 確認指數已 permissionFilterOption 設定為 enabled。
2. 確認 UserIds 並 GroupIds 取得正確的 permissionFilter 數值。
3. 對於 SharePoint 網站群組，請確認索引具有 sharePointConnectorAppRegistration 以及含有 sharepointSiteUrl: true 的 SharePointSiteUrl 欄位。
4. 確認每個索引文件或區塊都包含適用的權限欄位。 如果技能組使用索引投影，請確認 ACL 欄位位於 indexProjections.mappings 中。

若缺少任何值，請回到 設定搜尋服務以進行 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. 確認測試使用者已獲得直接指派，或透過遞移 Microsoft Entra 群組成員資格加入已獲指派的 Microsoft Entra 群組。
3. 如果 Microsoft Entra 群組巢狀在 SharePoint 群組內，請變更指派。 這種混合關係無法擴大，可能導致結果缺失。 將使用者直接加入 SharePoint 群組，或透過支援的 Microsoft Entra 群組指派授予權限。

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

6. 檢查 SharePoint 網站群組權限

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

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

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

7. 檢查查詢請求

1. 使用 REST API 版本2026-08-01-preview或等效的預覽 SDK 套件來控制 SharePoint 站點群組權限篩選器。
2. 確認 Authorization 會驗證可查詢索引的主體身分。
3. 確認 x-ms-query-source-authorization 包含委派的測試使用者標記。
4. 重新嘗試同一個查詢，不要使用無關的篩選或排名變更，這樣你才能隔離權限行為。

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

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

1. 選擇一份測試使用者能存取的文件，以及一份使用者無法在 SharePoint 存取的文件。
2. 以測試使用者身份執行權限篩選查詢，僅記錄文件金鑰或其他非秘密識別碼。
3. 執行以提高權限執行的讀取查詢，並將儲存的 UserIds、GroupIds 和 SharePointSiteUrl 值與來源權限進行比較。
4. 如果 elevated read 回傳預期文件，但使用者查詢沒有，請專注於使用者標記和群組解析。 如果提高權限後進行讀取仍找不到該文件，請著重檢查擷取、對應和 ACL 同步。

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

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

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

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

相關內容

• 查詢時 ACL 與 RBAC 實施
• 使用 SharePoint 索引器來擷取權限元資料
• 在 Microsoft 365 索引器中設定 SharePoint