註
Foundry IQ(Azure AI 搜尋服務)提供直接的索引與查詢 API,並搭配高階知識來源與知識庫 API 用於受控檢索。 使用 Azure 入口網站、REST API 或 Azure SDK 來設定這些功能,或將代理連線到 Microsoft Foundry 入口網站 中的知識庫。
SharePoint 權限的中繼資料擷取會使用 Foundry IQ(Azure AI 搜尋服務)索引器,將支援的存取控制清單(ACL)與已索引的 SharePoint 內容一併儲存。 查詢時權限篩選器會評估這些已索引的中繼資料以及查詢使用者的身分。 來源權限變更 是透過權限同步傳送到索引,而非透過查詢。
重要
索引權限篩選並非完整 SharePoint 存取與原則模型的即時評估。 關於來源端要求時擷取與客戶管理的內嵌替代方案,請參閱「選擇可維持新鮮度的擷取方法」。
先決條件
Foundry IQ 在任何地區皆須為可計費層級(基本版或以上)。
在 Microsoft 365 的網站、函式庫、資料夾和檔案中使用 SharePoint,並為其設定權限。
完成 SharePoint 索引器文件 中的所有配置步驟,並依照本文所述的 ACL 特定要求。
設定 Microsoft Entra 應用程式權限和適合你情境的憑證。 請參見 ACL 授權情境。 ACL 匯入需要應用程式權限。 不支援委派權限。 關於應用與委派的決策,請參見 「選擇你的權限設定」。
2026-10-01 資料平面 REST API 適用於本文所述的一般可用 SharePoint 權限設定。
註
權限重新同步 已正式推出,並支援 REST API 2026-10-01。
Reset-docs 仍處於預覽階段,並使用 REST API 2026-11-01-preview。
限制
在支援時,請使用標準或預設文件解析(
parameters.configuration.parsingMode: "default")或基於內容理解的擷取。 每個產生的區塊都必須保留所需的權限元資料與來源上下文。 系統不支援專門由客戶選擇的解析模式。 關於排除模式與知識來源設定,請參閱 「權限擷取的支援解析與內容擷取」。啟用 Microsoft Entra 條件式存取 的租戶不受支援。 SharePoint 索引器的限制同樣適用於 ACL 擷取。
權限更新取決於來源變更通知及索引器處理成功。 支援的非根文件庫資料夾變更可在一般增量處理中重新整理未變更的後代。 請參閱「 同步索引內容與來源內容之間的權限 」以了解範圍與重新整理選項。
Azure 入口網站不支援這個功能。
不支援下列功能:
適用於使用者存取的 SharePoint 資訊管理原則。 系統不會在查詢時評估、吸收或執行這些政策。
可分享連結範圍為「任何人」或「您組織中的人員」,以及分享連結到期的強制執行。 使用支援的明確使用者或群組指派,包括支援的繼承指派。 分享連結過期不會撤銷另一份明確授權。
巢狀群組成員資格支援最多五個層級。 當超過 10,000 個適用的 Microsoft Entra 群組主體需要巢狀解析時,會適用獨立的站點層級限制。 參見 支持性團體關係。
以下功能不支援 SharePoint ACL 匯入:
當啟用 SharePoint ACL 匯入時,聊天完成豐富功能具有端點與權限限制。
支援 SharePoint 權限模型
權限擷取支援以下 SharePoint 權限模型子集,適用於文件、清單項目及現代 ASPX 網站頁面。
| SharePoint 功能 | 描述 | 支援 | 註釋 |
|---|---|---|---|
| 網站、文件庫、清單與頁面繼承 | 網站→函式庫/清單→資料夾→檔案/項目/頁面。 | ✔️ | 在擷取時評估;會針對每個項目計算有效 ACL。 |
| 資料夾、檔案、清單項目及頁面的唯一 ACL | 項目層級存取權。 | ✔️ | 當第一次擷取時存在,且後續執行偵測到具有唯一權限之項目的 ACL 變更時,會包含此項。 |
| SharePoint 清單項目 | 清單項目(allSiteLists 及 allSiteContent 容器)的權限。 |
✔️ | 需要依 依 ACL 情境列出的權限列出的權限。 |
| ASPX 網站頁面 | 現代網站頁面(allSitePages 及 allSiteContent 容器)上的權限。 |
✔️ | 需要依 依 ACL 情境列出的權限列出的權限。 |
| Microsoft Entra(Microsoft 365 與安全性)群組 | 基於群組的存取 | ✔️ | 當群組 ID 可解析為 Microsoft Entra 識別碼 (ID) 時會包含。 |
| SharePoint 站點群組 | 擁有者/會員/訪客與自訂網站群組。 | ✔️ | 需要 SharePoint 群組配置。 群組識別碼會以 spg: 為前綴輸出。 |
| 可分享的「任何人連結」或「你組織中的人連結」 | 組織範圍或公開存取。 | ❌ | 改用支援的明確使用者/群組指派。 |
| 共享連結到期強制執行 | 存取權會根據連結的到期日而改變。 | ❌ | 權限重新同步並不會啟用此不支援的功能。 |
| 外部/訪客使用者 | 賓客可進入。 | ❌ | 不支援。 |
| 資訊管理政策 | 制定政策以定義特定的權限要求。 | ❌ | 不支援。 |
| Purview 靈敏度標籤 | 文件層級的安全保障,涵蓋隱私、分類、權限與加密 | ❌ | 透過另一項功能支持: 保留並尊重敏感標籤。 |
支持性團體關係
支援的群組解決方式包括嵌套於 SharePoint 網站群組中的 Microsoft Entra 群組,最多可包含五個巢狀群組層級。
| 權限關係 | 支援 | 指導 |
|---|---|---|
| 直接指派至 SharePoint 項目的使用者或 Microsoft Entra 群組 | Yes | 索引器將使用者或 Microsoft Entra 群組物件 ID 儲存在項目的權限元資料中。 |
| 使用者透過巢狀的 Microsoft Entra 群組隸屬於指定的 Microsoft Entra 群組 | 是的,五級之內 | 超過支援深度的會員資格不會讓你透過該路徑取得存取權限。 |
| 使用者直接指派至擁有該項目存取權的 SharePoint 網站群組 | Yes | 設定 SharePoint 群組支援。 |
| 嵌套於 SharePoint 群組 中的 Microsoft Entra 群組 | 是的,五級之內 | 設定 SharePoint 群組支援。 以下的網站層級主體限制同樣適用。 |
| 成員路徑需要超過五個巢狀群組層級 | No | 如果這是使用者唯一的權限路徑,則存取將被拒絕。 獨立的直接授權或限制範圍內的授權仍可授予存取權限。 |
例如,考慮一個擁有項目存取權的 SharePoint 群組。 Entra 群組 G1 是該 SharePoint 群組 的成員;G2 是 G1 的成員,並持續到 G6。 直接屬於 G1、G2、G3、G4 或 G5 的使用者,可透過相應的一至五層路徑獲得存取權限。 僅屬於 G6 的成員身分並不能透過這條鏈條存取。 對使用者的直接指派會獨立評估。
如果網站有超過 10,000 個適用於巢狀解析的 Microsoft Entra 群組主體,這些巢狀成員資格不會被解析。 獨立支援的授權,例如直接使用者指派或直接 SharePoint 群組 成員資格,仍可適用。 此門檻計算適用的 Entra 站台主體,而非使用者群組、SharePoint 群組、索引站台或巢狀深度。 正好 10,000 並不會單憑此門檻而被排除。 關於缺少的結果,請參見故障排除 SharePoint 權限過濾。
階層式權限如何被評估
SharePoint 權限會遵循網站→文件庫或清單→資料夾→檔案、項目或頁面的階層,除非繼承已被中斷。
在匯入過程中,索引器會收集使用者與群組識別碼,並計算每個項目的有效 ACL。
依 ACL 情境區分的權限
ACL 擷取所需的 Microsoft Entra 應用程式權限和憑證類型,取決於您要建立索引的項目類型和群組類型。 在應用程式註冊中,所有權限都會新增於 API 權限>新增權限 之下,而同盟憑證則會新增於 憑證與秘密>同盟憑證 之下。 如需逐步指示和螢幕擷取畫面,請參閱 步驟 3:建立 Microsoft Entra 應用程式註冊 和 使用受控識別設定已註冊的應用程式。
| 劇本 | 要新增的 API 權限 | Credential |
|---|---|---|
| 文件庫檔案上的 ACL,當只透過 Microsoft Entra 使用者和標準群組 (Microsoft Entra 安全性群組、Microsoft 365 群組、郵件啟用的安全性群組) 授與存取權時 |
Microsoft Graph:Files.Read.All、Sites.FullControl.All(或 Sites.Selected 適用於範圍限定存取) |
用戶端秘密或聯邦憑證 |
| 文件庫檔案上的 ACL,當也必須遵守 SharePoint 網站群組 (擁有者、成員、訪客或自訂網站群組) 時 |
Microsoft Graph:Files.Read.All、Sites.FullControl.All(或 Sites.Selected)SharePoint: Sites.FullControl.All (或Sites.Selected) |
聯邦資格(必備) |
| SharePoint 清單項目的 ACL |
Microsoft Graph:Files.Read.All、Sites.FullControl.All(或 Sites.Selected)、User.Read.AllSharePoint: Sites.FullControl.All (或Sites.Selected) |
聯邦資格(必備) |
| ASPX 網站頁面中的內容與存取控制清單 |
Microsoft Graph: Sites.FullControl.All (或Sites.Selected), User.Read.All (如果您同時也在索引文件庫或清單,請保留Files.Read.All上述列的設定)SharePoint: Sites.FullControl.All (或Sites.Selected) |
聯邦資格(必備) |
透過 sharePointConnectorAppRegistration 在查詢時解析 SharePoint 網站群組 |
將 SharePoint: User.Read.All 加到索引器使用的同一應用程式註冊中 |
聯邦資格(必備) |
註
當您新增權限時,您可以在兩種 API 介面之間選擇:Microsoft Graph 和 SharePoint。 兩者都提供名稱相似的權限。 例如,
Sites.FullControl.All存在於兩者之下。 在表格中標示的 API 表面下新增每個權限。每當情境新增 SharePoint API 權限時,就使用聯邦憑證。 用戶端密碼僅適用於僅限 Microsoft Graph 的文件庫資料列。
User.Read.All清單項目與 ASPX 網站頁面是必需的,因為索引器會透過 SharePoint REST API 讀取這些權限,而 REST API 只會回傳使用者的電子郵件。 索引子接著會呼叫 Microsoft Graph,將每封電子郵件解析為其 Microsoft Entra 物件 ID,而該查閱需要User.Read.All。使用
Sites.Selected時,先明確授權應用程式對每個目標SharePoint網站的存取權限,再進行索引。
聯邦憑證是使用受信任的管理身份來驗證應用程式,而非用戶端秘密。 同一聯邦憑證同時涵蓋 SharePoint 網站群組的擷取(索引器)和查詢時的評估。 關於設定步驟,請參見 「以管理身份設定註冊應用程式」。
在啟用 ACL 攝取之前
請在您的註冊 Microsoft Entra 應用程式上完成以下步驟:
- 根據您計劃編製索引的內容 (文件庫檔案、清單項目、ASPX 網站頁面),以及是否必須遵守 SharePoint 網站群組,在前一個資料表中識別您的案例。
- 在Microsoft Entra 系統管理中心開啟你的應用程式註冊,然後到 API 權限>新增權限。
- 新增你情境中列出的 Microsoft Graph 權限。 授予管理員同意。
- 如果你的情境也需要SharePoint權限,請再次選擇 新增權限,選擇 SharePoint API,並新增
Sites.FullControl.All(或Sites.Selected)。 授予管理員同意。 - 設定憑證:
- 對於僅適用於 Microsoft Graph 的情境,您可以使用用戶端密碼(Certificates & secrets>Client secrets)或同盟憑證。
- 對於任何包含SharePoint權限的情況,請在
Certificates & secrets Federated credentials 下新增一個聯邦憑證。 詳見 「以管理身份配置註冊應用程式」。
- 授權應用程式存取目標SharePoint網站(尤其重要,當你使用
Sites.Selected作為範圍存取時),這樣它才能讀取你想要索引的內容和權限。
找到正確的 Microsoft Entra 識別碼
每個識別碼會在 Azure 入口網站的不同位置出現,並對應到特定的配置欄位。 在使用同盟認證設定 SharePoint ACL 擷取時,請將本節作為參考。 這些識別碼會在 設定 SharePoint 群組支援以及資料來源連線字串中參照。
| 識別碼 | 入口位置 | 使用位置 | 註釋 |
|---|---|---|---|
| Ingestion app 應用程式(用戶端)識別碼 |
應用程式註冊><your-app>>概覽 |
ApplicationId在資料來源 連接字串 中;applicationId在sharePointConnectorAppRegistration |
此 ID 對大多數設定欄位皆為正確。 也稱為「客戶識別碼」。 |
| 應用程式物件識別碼 |
應用程式註冊><your-app>>概覽(位於應用程式(用戶端)ID 下方) |
未用於 Foundry IQ 配置 | 不要把它和應用程式(客戶端)ID 搞混。 它出現在同一窗格中的客戶識別碼正下方。 |
| 服務主體物件識別碼 |
Microsoft Entra ID>Enterprise 應用程式><your-app>>管理>屬性 |
未在 Foundry IQ 設定中使用 | 這是該應用程式的服務主體表示形式。 這是與應用程式註冊物件 ID 不同的 GUID。 |
| 受控身份識別主體識別碼 | 管理身份資源 >屬性 或 Foundry IQ 服務 身份 窗格 | 未直接用於 Foundry IQ 資料來源或索引設定 | 當你在應用程式註冊中設定同盟身分識別認證時,會在內部使用。 你建立的憑證信任此身分。 |
| 聯邦憑證物件識別碼 |
應用程式註冊>><your-app>管理>憑證與密鑰>聯合憑證><credential-name> |
未用於 Foundry IQ 配置 | 請勿對federatedCredentialId使用同盟身分識別認證項目的 GUID。 |
| 聯邦憑證申請識別碼 | 系統指派:Microsoft Entra ID>企業應用程式><search-service>>屬性; 使用者指派:<managed-identity-resource>>屬性 |
FederatedCredentialApplicationId在資料來源 連接字串 中;federatedCredentialId在sharePointConnectorAppRegistration |
請參閱 聯邦憑證應用程式 ID 以查詢管理身份。 |
聯邦憑證申請識別碼
在資料來源連接字串中的 FederatedCredentialApplicationId 和索引定義中的 federatedCredentialId,請使用受控識別本身的應用程式(用戶端)ID,不要使用擷取應用程式的 ID。
系統指派的受控識別:
- 前往您的 Foundry IQ 服務。
- 選擇 安全 + 網路>識別碼。
- 在 系統指派 標籤中,注意物件 (主體)ID。
- 前往 Microsoft Entra ID>管理>企業應用程式。
- 搜尋您的 Foundry IQ 服務名稱,或將 物件(主體)ID 貼到搜尋框中。
- 選擇結果並開啟 屬性。 複製此處顯示的應用程式 ID,其為資料來源中的
federatedCredentialId值,以及索引中的FederatedCredentialApplicationId值。
使用者指派的受控識別:
- 前往使用者指定的管理身份資源。
- 選取 [設定]> [屬性]。
- 複製 Client ID,也就是資料來源中
federatedCredentialId的值,以及索引中FederatedCredentialApplicationId的值。
將您的 Foundry IQ 服務設定為 ACL 擷取與查詢時 ACL 強制執行
這些步驟會將您的 Foundry IQ 服務設定以進行 ACL 匯入,並在查詢時啟用 ACL 的遵循。
選擇填入 ACL 欄位的位置
ACL 元資料欄位的映射位置取決於索引器是每個來源項目寫一份文件,還是每個來源項目寫多個區塊。
| 劇本 | 透過以下方式填充 ACL 欄位 | 原因為何 |
|---|---|---|
| 無技能集或無分塊技能集;每個來源項目一份搜尋文件 |
僅索引器欄位映射(metadata_user_ids→UserIds、 metadata_group_ids → GroupIds、 及 SharePoint 群組 metadata_spo_site_url →SharePointSiteUrl)。 |
索引器會將單一文件寫入目標索引,欄位映射則將原始元資料傳送到索引欄位。 |
具備分塊的技能組(例如,整合向量化的文字分割技能),單一索引,每個區塊重複父欄位(projectionMode: skipIndexingParentDocuments) |
技能集中的索引投影(mappings來自 /document/metadata_user_ids、/document/metadata_group_ids,以及 SharePoint 群組 /document/metadata_spo_site_url)。 |
父層文件未建立索引;只有區塊會被建立索引。 ACL 值必須投影到每個區塊上,因此查詢時過濾器會套用在結果中回傳的區塊上。 此模式下,這些欄位的索引器欄位映射會被繞過。 |
| 具備分塊、雙索引模式(父索引 + 子區塊索引)的技能組 | 兩者皆是:索引器欄位對應填充父索引上的 ACL 欄位,索引投影則填充子區塊索引上的 ACL 欄位。 | 兩個索引都可以查詢,且每個索引都需要它所過濾的元資料。 |
在所有分塊情境中,每個分塊都必須攜帶 ACL 欄位。 權限過濾器會依文件套用,因此缺少 ACL 欄位的區塊無法回傳給正確的呼叫者。
1. 資料來源配置
將indexerPermissionOptions新增至基礎資料來源設定,以匯入userIds和groupIds。 此範例選取網站的預設文件庫。 使用連接器的容器與查詢設定來進行其他選擇。
{
"name": "my-sharepoint-acl-datasource",
"type": "sharepoint",
"indexerPermissionOptions": ["userIds", "groupIds"],
"credentials": {
"connectionString": "<connection-string>;"
},
"container": {
"name": "defaultSiteLibrary",
"query": null
}
}
2. 在索引定義中加入權限欄位
將下列欄位與屬性合併到您的 索引結構定義中。 此片段省略了所需的文件金鑰及內容欄位;保留它們在完整定義中。
將 SharePoint 授權中繼資料與索引鍵識別資訊分開。 以下 SharePoint 專屬需求擴充連接器的來源元資料以及金鑰對應與編碼指示。
| 來源欄位 | Purpose | 目標與對應 |
|---|---|---|
metadata_spo_item_path |
ACL 查詢及僅權限更新的來源路徑。 | 名為 Edm.String 的必填 metadata_spo_item_path 欄位。 對整份文件以及 /document/metadata_spo_item_path 每個區塊投影使用隱含的同名對應。 |
metadata_user_ids |
支援的使用者指派。 | 映射到Collection(Edm.String)一個欄位,使用 permissionFilter: "userIds",例如 UserIds。 Project /document/metadata_user_ids 到區塊上。 |
metadata_group_ids |
支援 Microsoft Entra 並已設定 SharePoint 站台群組指派。 | 對應到含有 permissionFilter: "groupIds" 的 Collection(Edm.String) 欄位,例如 GroupIds。 將 Project /document/metadata_group_ids 投影到區塊。 |
metadata_spo_site_url |
原生 SharePoint 群組 解析的原始網站。 | 映射到含有 sharepointSiteUrl: true 的 Edm.String 欄位,例如 SharePointSiteUrl。 Project /document/metadata_spo_site_url 投射到區塊上;保留每個項目的站點以供跨站點選取。 |
metadata_spo_site_library_item_id |
用於文件庫或資料夾選擇的文件庫項目識別碼。 | 使用連接器的金鑰編碼指令,對應到整份文件或父索引鍵。 投影會產生子鍵與父識別。 |
metadata_spo_site_asset_item_id |
清單、頁面或混合內容選擇的資產/項目識別碼。 | 請改用此鍵,而不要對 allSitePages、allSiteContent 和 allSiteLists 使用 library-item 鍵。 遵循相同的金鑰編碼說明;不要映射投影產生的金鑰或父識別。 |
{
"fields": [
{ "name": "metadata_spo_item_path", "type": "Edm.String", "retrievable": false },
{ "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 驗證數值。 更改 retrievable 不需要重新建立指數。
3. 在你的技能組中設定指標投影(如適用)
當啟用分區時,當 projectionMode 為 skipIndexingParentDocuments時,父文件不會寫入索引。 透過 indexProjections.selectors[].mappings 將 ACL 中繼資料傳遞到每個區塊中。
如果您的索引器使用具有資料分塊的技能集,例如在啟用整合向量化時使用文字分割技能,請利用索引投影將權限欄位與所需的來源路徑對應到每個區塊。 有關技能組架構,請參閱 2026-10-01 資料平面 REST API 參考資料。
此範例顯示目標區塊索引的技能組設定,並使用前一步的權限欄位。 目標還需要欄位 content 、文件鍵及可 parentId 篩選的字串欄位,如 定義索引投影中所述。 投影會產生文件金鑰與父 ID;不要自己對應這些欄位。
僅在設定 SharePointSiteUrl 時包含。
//以下範例中的註解僅具說明性,並非有效的 JSON。 在提交申請前先移除它。
PUT https://{service}.search.windows.net/skillsets/{skillset}?api-version=2026-10-01
{
"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",
"sourceContext": "/document/chunks/*",
"mappings": [
{ "name": "content", "source": "/document/chunks/*" },
{ "name": "metadata_spo_item_path", "source": "/document/metadata_spo_item_path" },
{ "name": "UserIds", "source": "/document/metadata_user_ids" },
{ "name": "GroupIds", "source": "/document/metadata_group_ids" },
{ "name": "SharePointSiteUrl", "source": "/document/metadata_spo_site_url" }
]
}
],
"parameters": {
"projectionMode": "skipIndexingParentDocuments"
}
}
}
UserIds、GroupIds 和 SharePointSiteUrl 映射讀取由 SharePoint 索引器(/document/metadata_*)所發出的來源層元資料,並將值寫入每個區塊。
4. 配置索引器欄位與 ACL 的映射关系
當索引器為每個來源項目寫入一份文件(不進行分塊),或同時維護獨立的父索引和區塊索引時,請使用索引器欄位對應。 對於具有 projectionMode: skipIndexingParentDocuments 的僅區塊索引,請保留前一步的投影映射。 你不需要額外的索引器 fieldMappings 來填充這些區塊欄位。
除了你必須的 indexer 配置外,還需要將來自 SharePoint 的原始元數據 ACL 欄位映射到你的索引欄位。
每個來源項目對應一個文件時,同名 metadata_spo_item_path 來源欄位與索引欄位使用隱含欄位對應。 對於區塊,請使用前一步的直接投影映射。
將這些已啟用權限的設定差異套用到 基礎連接器的索引器設定:
-
文件庫或資料夾選擇: 保留
metadata_spo_site_library_item_id金鑰對應及其base64Encode對應功能。 -
清單或頁面選擇: 對於
allSiteLists或allSitePages,將密鑰映射來源替換為metadata_spo_site_asset_item_id,並保留編碼函數。 保留 Index SharePoint lists 或 Index ASPX site pages 中描述的內容設定。 -
混合選取: 對於
allSiteContent,使用metadata_spo_site_asset_item_id作為跨選取範圍的鍵對應來源,並使用相同的編碼函數。
對每個選取項目,啟用 userIds 並 groupIds 在資料來源上保留所需路徑欄位,並新增下列 ACL 對應。 使用原生 SharePoint 群組時新增網站 URL 對應。 對於僅區塊索引,請使用前一步的五種投影映射,而非手動對應產生的鍵或父識別碼。
{
"fieldMappings": [
{ "sourceFieldName": "metadata_user_ids", "targetFieldName": "UserIds" },
{ "sourceFieldName": "metadata_group_ids", "targetFieldName": "GroupIds" }
]
}
5. 執行索引器
索引器執行時會匯入 ACL 中繼資料。 建立或更新索引器後,執行 索引器並監控其狀態 ,以便同時匯入 ACL 與內容。
關於定期權限重新整理與現有索引回填,請參閱 「重新整理索引權限」。 回填步驟取決於現有紀錄是否已包含 metadata_spo_item_path。
6. 驗證 ACL 擷取
確認 ACL 值已正確填入:
- 在你的索引定義中,暫時將
retrievable在true和UserIds上設為GroupIds。 更改retrievable不需要重新建立指數。 - 執行高權限讀取查詢,選取
UserIds和GroupIds。 將這些值與項目支援的來源指派進行比較。 當存取是透過另一個集合授權時,其中一個集合可能會是空的。 對於分塊情境,請在每個區塊上驗證預期指派。 - 驗證後,將
retrievable返回至false。
透過 查詢疑難排解檢查,比較允許與拒絕的測試使用者結果。 僅有已填入值的 ACL 欄位,無法驗證查詢時的強制執行。
設定 SharePoint 群組支援
SharePoint 索引器可以匯入 SharePoint 網站群組權限(擁有者、成員、訪客及自訂網站群組),以進行查詢時篩選。 索引器會在 spg: 欄位中輸出帶有 metadata_group_ids 前綴的 SharePoint 群組 ID,以區分其與 Microsoft Entra 群組物件 ID。
設定 ACL 擷取後,請依照以下步驟將 SharePoint 網站群組解析新增至您的索引與查詢設定中。
以下元件協同運作以啟用 SharePoint 站點群組解析:
| 組件 | 位置 | Purpose |
|---|---|---|
sharePointConnectorAppRegistration (與 applicationId, tenantId, federatedCredentialId) |
指數定義 | 提供 Foundry IQ 服務所需的驗證設定,以呼叫使用者身分呼叫 SharePoint REST API,並在查詢時解析站台群組成員資格。 |
SharePointSiteUrl 欄位(搭配 sharepointSiteUrl: true) |
來自 metadata_spo_site_url 的索引結構描述 + 索引器欄位對應 |
識別文件所屬的 SharePoint 網站,確保 SharePoint 群組解析的範圍正確。 |
spg:-前綴值 GroupIds |
文件權限元資料 | 區分 SharePoint 網站群組 ID 與 Microsoft Entra 群組物件 ID。 |
對於跨網站來源選擇,會 metadata_spo_site_url 標示每個項目的來源網站,而非整個索引的固定網站。 在每個文件或區塊上保留該值,並授予已設定的應用程式對每個所選站台所需的存取權。 請參閱 「依 ACL 情境設定的權限 」以及 「選擇填入 ACL 欄位的位置」。
具有標記為 sharepointSiteUrl: true 之欄位的索引最多支援五個不同的站台 URL 值。 在選擇網站前,請檢查 SharePoint 群組 權限的網站限制。 對於較大範圍,請評估 獨立的索引與知識來源,包括知識庫容量與應用程式路由。
1.Prerequisites
- SharePoint 索引器已經設定好可以擷取 ACL 了。 請參見「配置索引器欄位映射以支援 ACL」。
- Microsoft Entra 應用程式註冊使用聯邦身份憑證。 詳見 「以管理身份配置註冊應用程式」。
- REST API
2026-10-01。
註
FederatedCredentialApplicationId 在資料來源 連接字串 中,以及 federatedCredentialId 在 sharePointConnectorAppRegistration 中,都使用受控識別的應用程式 ID。
sharePointConnectorAppRegistration 中的 applicationId 屬性會使用擷取應用程式的用戶端 ID。 要找到正確的值,請參見「尋找正確的 Microsoft Entra 識別碼」。
2. 配置索引
將以下設定合併到完整的索引定義中,並保留其文件鍵與內容欄位。 它會把 sharePointConnectorAppRegistration 和 SharePointSiteUrl 加到 ACL 欄位旁邊。 保留 permissionFilterOption: "enabled"。
{
"name": "my-sharepoint-acl-index",
"sharePointConnectorAppRegistration": {
"applicationId": "<ingestion-app-client-id>",
"federatedCredentialId": "<managed-identity-application-id>",
"tenantId": "<sharepoint-tenant-id>"
},
"fields": [
{ "name": "metadata_spo_item_path", "type": "Edm.String", "retrievable": false },
{ "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.selectors[].mappings 投影到每個區塊。 請參閱 「選擇填入 ACL 欄位的位置」。
4. 查詢索引
用戶端不需更改。 同一個 x-ms-query-source-authorization 標記同時啟動 Microsoft Entra 和 SharePoint 站點群組強制執行。 Foundry IQ 服務會在伺服器端透過sharePointConnectorAppRegistration索引解析 SharePoint 群組 成員資格。
關於要求格式,請參閱 一般查詢範例以及 SharePoint 專屬的 含有 SharePoint 網站群組強制執行的範例。
5. 驗證
若要確認 SharePoint 群組 識別碼是否在索引中,請執行elevated-read 查詢,選取GroupIds,並在回應中尋找以 spg: 為前綴的值。
同步索引內容與來源內容之間的權限
內容與權限元資料會透過不同的處理階段複製到搜尋中。 請根據授權發生地點及應用程式如何管理更新,選擇擷取方式。
選擇一種擷取方式以考量新鮮度
當您的應用程式需要使用 SharePoint 的權限模型,而非搜尋中複寫的權限子集來在要求時擷取時,優先使用遠端 SharePoint。 此方法透過 Microsoft 365 治理控制,提供更接近 SharePoint 的新度,且無需額外的搜尋同步管線。 選擇「已編製索引的擷取」用於自訂 Search 索引,或選擇「Push」進行由應用程式控制的提交。
| 決策 | 遠端 SharePoint | 建立索引的 SharePoint | 客戶管理的推播 API |
|---|---|---|---|
| 授權機構 | 以 SharePoint 的權限模型及 Microsoft 365 治理控制,代表使用者進行 Microsoft 365 檢索。 | 查詢時篩選已複寫的SharePoint 權限的子集。 | 查詢時篩選應用程式所提供的權限值;無法自動同步 SharePoint ACL 或原生群組解析。 |
| 內容與權限新鮮度 | 沒有額外的搜尋索引同步;取決於 Microsoft 365 的處理與遠端來源限制。 | 來源通知與索引器成功處理會更新複本。 排程並不會設定嚴格的新鮮度時限。 | 您的應用程式控制提交時間,而非查詢結果會立即可見。 |
| 撤銷 | 視 Microsoft 365 的處理情況而定;並非零延遲承諾。 | 過時的索引授權可能會持續存在,直到相關更新被處理。 | 您的應用程式會偵測被撤銷的授權、更新受影響的紀錄與區塊,並驗證結果。 |
| 身分職責 | 提供 遠端來源所需的委派使用者身份。 | 設定擷取憑證、支援的群組解析,以及 查詢使用者的權杖。 | 提供支援的權限識別碼並查詢授權資訊;實作來源到索引的權限轉換。 |
| 客製化 | 使用支援的篩選器與中繼資料來限定檢索範圍;視 Retrieval API 的功能而定。 | 設定索引結構、支援的增強處理、區塊與向量。 | 在您的擷取管線中實作擷取程序、索引結構、分塊、向量及權限更新。 |
| Operations | 監控擷取與 Microsoft 365 相依性;沒有可排程的 Search 索引器。 | 監控索引器的執行、重新整理權限,並驗證文件與投影。 | 操作擷取管線並依照下一節所述 處理更新失敗 。 |
| 網路與政策邊界 | 遵循遠端來源的先決條件與限制;這不是條件存取的變通方法。 | 連接器限制適用。 SharePoint Online 使用公開端點。 | 您的應用程式擁有其來源與搜尋連線;推送不會變更 SharePoint 原則需求。 |
| API 與釋出範圍 | 遠端知識來源與 Copilot Retrieval API 目前為預覽版;請遵循遠端 API 指引。 | SharePoint ACL 的擷取與篩選功能已隨 REST 2026-10-01正式提供。
索引式知識來源指引 有獨立的 API 與預覽要求。 |
透過 Push REST API 進行權限匯入功能已普遍提供。 連結的指南說明了範例中使用的 REST API 版本及 SDK 支援考量。 關於權限篩選結構,請參閱 2026-10-01 資料平面 REST API 參考。 |
在索引檢索、來源傳播、內容與 ACL 處理中,群組成員傳遞、權杖更新、查詢時成員快取及索引更新,都可能影響可見性。 請求或排定的啟動不等於處理完成。 執行可能會超過其間隔,或遭遇節流、重試或失敗。 排程、重設、reset-docs 和權限重新同步並非即時新鮮度控制。
透過推送,您的應用程式負責 SharePoint 變更偵測、內容與權限同步、擷取、區塊與向量、刪除與過期記錄清理、重試、排序、對帳及監控等事務。 僅僅以提交時機無法確定全程新鮮度。
處理授權與更新失敗
如果您的應用程式無法取得有效的使用者授權或權限評估失敗,請停止為該請求回傳受保護內容,並顯示錯誤。 不要將下列作法作為面向使用者的備援:在沒有使用者權杖的情況下重試、停用權限篩選,或使用提升的診斷存取。 將此責任套用於應用程式快取內容及產生的回應。
針對客戶管理的推送管線:
- 檢查每份文件的索引結果,包括 HTTP
207回應中的部分失敗。 依照 載入搜尋索引,追蹤失敗的金鑰並使用 backoff 重試可重試的失敗。 - 對同一金鑰序列化更新,並使重試成為冪等。 在提交前整合變更;批次動作順序未定義。 在管線中保留來源版本或檢查點,避免舊版重試還原被撤銷的授權。
- 在替換權限欄位時,請提交完整的預期 ACL 集合。 集合更新會取代集合,而非附加個別授權。
- 將來源項目與索引鍵及其區塊進行比對。 使用 文件刪除指引移除過時文件、過時區塊及超出所選來源範圍的記錄。 更新一個鍵並不會清除其他鍵。
- 在將更新視為已核對之前,請先確認索引結果、查詢可見性,以及允許與拒絕的使用者存取。
重新整理索引權限
根據您的權限更新需求,設定短週期性索引器排程。 間隔的最小值為五分鐘。 請使用現有 的排程定義 及 排程設定指引。
這個間隔不是完成截止日期,也不是權限撤銷的服務等級協議(SLA)。 執行作業可能會被延遲,而重疊的執行作業可能會導致排定的開始被跳過。 請參閱排程行為常見問題集。 權限變更會在偵測並成功處理後才會進入索引,而非在每次排程啟動時自動進入索引。 定期排程不會要求完整權限重新同步。
啟用 ACL 匯入時,一般增量處理會重新整理偵測到的項目層級權限變更。 非根文件庫資料夾的支援權限變更通知也會讓索引器在後續成功執行時列舉範圍內子孫並刷新每個項目的來源 ACL,即使子內容尚未變更。 具有獨特權限的子項目會保留其自身的來源存取規則,而非接收資料夾 ACL 的副本。
此資料夾權限路徑與重新命名與移動傳播選項無關,且不需要另外進行完整權限重新同步。 它不會為網站、文件庫、清單或磁碟機根的變更,或錯過來源通知建立相同的傳播行為。
| 變更範圍 | 自動偵測 | 建議的動作 |
|---|---|---|
| 偵測到具有獨特權限的項目 (檔案、清單項目或頁面)的權限變更 | Yes | 執行索引器或讓其排程執行,然後驗證已重新整理的 ACL。 |
| 特定項目的內容變更 | Yes | 處理變更後的項目同時也會重新評估其有效 ACL 清單。 |
| 支援非根文件庫資料夾權限變更通知 | Yes | 後續成功執行會刷新範圍內的子孫,包括未變更的檔案。 具有獨特權限的子節點會保留其來源 ACL。 |
| 變更網站、文件庫、清單或磁碟根權限;遺漏通知 | 未被資料夾更新路徑涵蓋 | 使用 permissions resync 來重新整理現有的索引 ACL,或 reset affected documents 以重新處理其內容與 ACL。 確認結果。 |
| 在現有索引器上啟用 ACL 擷取 | 需要回填 | 如果現有記錄已包含 metadata_spo_item_path,請使用 權限重新同步。 否則,請新增所需欄位及適用的投影映射,然後重設並重新處理受影響的來源項目,以填充其路徑與 ACL。 |
這些操作同樣適用於已索引的 SharePoint 知識來源所產生的索引器。 僅新增結構欄位並不會填入現有紀錄。 對於投影索引,請確認受影響區塊的權限與來源元資料。
將來源生命週期變更與僅權限刷新分開處理:
- 內容變更: 透過正常的索引器執行或定向重設,重新處理受影響的內容及其區塊。 權限重新同步不會重執行擷取或嵌入。
- 移動與更名: 檢查連接器的 增量索引限制 ,並如有需要更新來源選擇路徑。 將目前的來源路徑與索引身份與先前的記錄及區塊進行比較;不要將權限重新同步視為金鑰遷移。
- 刪除: 連接器會在後續執行時偵測來源端的刪除。 處理成功後,請確認來源項目的索引文件與區塊已不存在。
- 陳舊紀錄或片段: 在處理後,將預期的來源項目與投影子項與實際索引鍵進行比較。 使用 刪除文件處理剩餘記錄;成功刷新現有紀錄並不代表已移除過時紀錄。
查詢不會啟動索引器。 監控執行狀態 ,包括完成、警告、失敗及項目數量,然後驗證經過權限篩選的結果。 單靠成功的執行作業,並不能確立端對端的最新狀態。
重置特定文件
使用 重設特定文件 來重新處理已知文件鍵的內容與 ACL,然後執行索引器。 此流程與僅權限刷新不同。
在整個資料來源中重新同步 ACL
使用 2026-10-01 搭配 REST API options: ["permissions"] 和 。 下一次手動或排程索引器執行會處理該請求;持續監控其進度直到完成。 申請被接受並不代表處理已經完成。 此僅需權限的操作會利用每個記錄的現有 metadata_spo_item_path 資料來刷新已索引的文件與投影區塊,而無需重執行技能集或嵌入。 對於沒有路徑的記錄,請依照 回填指引操作。 之後的正常內容執行則是獨立的操作。
權限重新同步與同步重試是分開的,後者可在正常索引器執行期間重新處理內容。 它也未新增全組織共享連結或連結過期的支援。
在相關更新處理完成之前,查詢可以使用過時的索引 ACL。 處理完成後,利用 查詢疑難排解檢查,比較已授權和遭拒的測試使用者結果。
索引完資料和 ACL 後,你可以查詢索引。
Troubleshooting
| 癥狀 | 原因和解決方案 |
|---|---|
已編製索引的文件中的 UserIds 或 GroupIds 為空 |
如果你的技能組合使用 projectionMode: skipIndexingParentDocuments,索引器會繞過 ACL 欄位的欄位映射。 改為在每個區塊上設定 ACL 欄位 indexProjections.selectors[].mappings 。 |
SharePoint 站點群組 ID 缺失,或 GroupIds 值沒有 spg: 前綴 |
確認索引具有 sharePointConnectorAppRegistration 組態、SharePointSiteUrl 欄位存在且具有 sharepointSiteUrl: true,並且 metadata_spo_site_url 對應存在於索引子欄位對應或索引投影中。 |
SharePointSiteUrl 在編製索引後仍為空白或為 null,儘管 ACL 的其他部分均已正確填入 |
索引器會在 metadata_sharepoint_site_url 之下輸出這項中繼資料,而不是在 metadata_spo_site_url 之下。 確認你的索引器欄位映射是否使用 "sourceFieldName": "metadata_spo_site_url"。 如果你的技能是用索引投影來處理分塊文件,請確認投影映射來源是 /document/metadata_spo_site_url。 |
| 索引器回傳 401 或 403 | 在你的情境中,對 Microsoft Graph 和 SharePoint API 權限都給予管理員同意。 當情境需要時,使用聯邦憑證(非客戶端秘密)。 請參見 ACL 授權情境。 |
| 在來源 ACL 變更後,權限會過時 | 檢查索引內容與來源內容之間的同步權限中的「成功處理」及變更範圍。 支援的資料夾通知採用一般的增量處理;其他範圍或錯過通知可能需要明確重新整理。 |
| ACL 擷取回報缺少來源路徑 | 新增所需的 metadata_spo_item_path 索引欄位及適用的投影映射,然後重設並重新處理受影響的來源項目。 僅新增欄位不會填滿現有記錄,且權限重新同步不會回填遺失的路徑。 請參閱 新增權限欄位 與 回填指引。 |
federatedCredentialId 在設定 sharePointConnectorAppRegistration 時遭到拒絕 |
請使用受管理身份的應用程式 ID,而非聯邦身份憑證的物件 ID 或受管理身份的主體 ID。 請參閱 聯邦憑證申請ID。 |
索引器會傳回 401 Unauthorized,並將 FederatedCredentialApplicationId 設為已設定 |
請確認您使用的是受控識別的應用程式 ID(可在 企業應用程式 中找到),而不是擷取應用程式的「應用程式(用戶端)ID」(ApplicationId) 或任何物件 ID。 對於使用者指派的管理身份,請使用該管理身份資源的屬性頁面中的客戶端 ID。 請參閱「尋找正確的 Microsoft Entra 識別碼」。 |
如需了解在 ACL 中繼資料建立索引後查詢時遺失、非預期或失敗的結果,請參閱 疑難排解 SharePoint 權限篩選。