Foundry IQ(Azure AI 搜尋服務)中的文件層級存取控制

Note

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

Important

本文中標示為(預覽)的功能或特性目前處於公開預覽狀態,並受 Microsoft Azure 預覽版補充使用條款的約束。

有關 Foundry IQ(Azure AI 搜尋服務)專屬的預覽條款,請參閱預覽功能。

SharePoint ACL 擷取與查詢時權限篩選、ADLS Gen2 ACL/RBAC,以及標準 Blob 容器 RBAC,皆已隨 2026-10-01 資料平面 REST API 正式推出。 推送 ACL 擷取功能也普遍可用。 Microsoft Purview 敏感度標籤強制執行仍處於預覽階段。

Foundry IQ(Azure AI 搜尋服務)支援文件層級的存取控制,讓組織能在文件層級強制執行細緻權限,從資料擷取到查詢執行皆然。 這項能力對於建構安全的人工智慧代理系統(基於資料)、檢索增強生成(RAG)應用程式,以及需要文件層級授權檢查的企業搜尋解決方案至關重要。

文件層級存取控制的方法

Foundry IQ 提供五種主要方法來強制執行文件層級權限,每種方法都適用於不同的資料來源與身份模型。

方法 描述
安全過濾器 字串比較。 你的應用程式會以字串形式傳遞使用者或群組身份,這個字串會在查詢中填入一個過濾器,排除與字串不符的文件。

安全過濾器是一種實現文件層級存取控制的技術。 這種方法不受 API 限制,所以你可以使用任何版本或套件。
類似POSIX的ACL / RBAC內視鏡 被委派使用者的 Microsoft Entra 身份會根據支援的權限元資料進行評估。 ADLS Gen2 的 ACL 與容器 RBAC 範圍擷取、標準 Blob 容器 RBAC 範圍擷取,以及其查詢權限篩選,已在 REST API 2026-10-01 中正式推出。 客戶管理的推送 ACL 匯入功能也普遍提供。 其他功能則保留其已記錄的可用性;並非所有儲存授權政策都受到支援。 有關 API 與 SDK 的指引,請參閱 「擷取 ACL 權限中繼資料」。
Microsoft Purview 敏感度標籤(預覽) 索引器從支援的資料來源(Azure Blob 儲存體、ADLS Gen2、Microsoft 365 中的 SharePoint、OneLake)中擷取 Microsoft Purview 定義的敏感度標籤。 這些標籤會儲存為中繼資料,並在查詢時評估,以根據 Microsoft Entra 權杖和 Purview 原則指派強制執行使用者存取權。 標籤也會透過 知識來源 和 代理式擷取回應提供,讓使用知識庫的 AI 代理和聊天應用程式也能獲得相同具標籤感知能力的篩選。 此方法讓 Foundry IQ 授權與您企業的 Microsoft 資訊保護 模型保持一致。
Microsoft 365 ACL 中的 SharePoint Foundry IQ 索引器會擷取支援的權限元資料,並利用 REST API 2026-10-01進行查詢時的存取檢查。 關於索引權限子集、群組限制、同步行為及設定,請參閱使用 SharePoint 索引器匯入權限中繼資料。
OneLake 來源權限(預覽) 使用索引來源位置及查詢時的 OneLake 授權,而非複製的使用者及群組 ACL。 請參閱 保留 OneLake 權限。

對於索引知識來源, ingestionPermissionOptions 無法與 assetStore合併。 因此,當啟用原生文件層級權限擷取時,映像服務 (預覽) 無法使用。

支援用於權限擷取的解析與內容擷取

當您為 SharePoint、ADLS Gen2 或 Blob 儲存體 啟用原生文件層級權限時,請使用標準或預設的文件解析與內容擷取。 在擷取過程中保留每個來源項目的權限元資料與來源上下文。

您也可以使用 以內容理解為基礎的擷取,前提是您的資料來源和 API 支援此功能。 設定每個產生的區塊以保留所需的權限元資料與來源上下文。 支援的下游分塊並不等同於選擇專用的來源解析模式。

對於 REST API 2026-10-01,請使用您所設定的資源的設定:

Resource REST 屬性 Configuration
SharePoint、ADLS Gen2 或 Blob 索引器 parameters.configuration.parsingMode 使用 default 進行標準文件剖析。
Blob 知識來源,包括 ADLS Gen2 azureBlobParameters.ingestionParameters.contentExtractionMode minimal 是預設的擷取選項; standard 選擇基於內容理解的擷取。 保留產生的權限與來源內容脈絡對應。
索引化的 SharePoint 知識來源 indexedSharePointParameters.ingestionParameters.contentExtractionMode minimal 是預設的擷取選項;在支援的情況下,使用 standard 進行基於內容理解的擷取。 透過知識來源 API 設定擷取,而非透過變更產生的解析器設定。

知識來源 contentExtractionMode 與索引器 parsingMode 是不同的設定。 特別是,minimal 並不是專門的純文字解析模式。 如需了解 REST 定義,請參閱 索引器 - 建立 和 知識來源 - 建立或更新。

目前,其他客戶選取的剖析模式尚不支援文件層級的權限。 請勿選擇:

  • JSON 解析 (json)。
  • JSON 陣列解析(jsonArray)或將多個 JSON 文件解析成獨立記錄。
  • JSON 行解析 (jsonLines)。
  • CSV 或分隔文字解析(delimitedText)。
  • 純文字專屬解析(text)。
  • Markdown 專用的解析 (markdown)。
  • 任何其他模式,能從單一來源項目建立、分割、重塑或映射多個邏輯記錄,且不支援權限傳播合約。

這些限制涉及解析模式,而非檔案副檔名或擷取內容的格式。 例如,以 default 解析的純文字檔案不會使用專門的 text 模式。 Content Understanding 的 Markdown 輸出並非 markdown 來源解析模式。

有關區塊映射及必需的來源元資料,請參閱 SharePoint 權限指引、ADLS Gen2 權限指引及 Blob RBAC 範圍指引。

信任已編製索引的權限來源

查詢階段的權限篩選會檢查與已索引記錄相關聯的權限中繼資料。 另外,你的擷取設計必須確定誰有權選擇該紀錄的身份並授權存取其內容。 文件金鑰用於選取要更新或合併的記錄;它不是授權邊界。

對於原生連接器擷取,請遵循來源專屬設定,並保留來源內容、身份與連接器衍生權限之間的關聯。 對於 客戶管理的推播擷取,授權發佈者會提供金鑰與權限值。 由應用程式管理的字串篩選也取決於該應用程式的驗證和篩選器的建構。

不要僅因為欄位名稱相符,就將一般的低信任度內容視為已授權的權限中繼資料。 檢視來源撰寫者、擷取管理員、隱含與明確對應、擴充輸出,以及投影子項目。 對於 Blob 擷取,請使用 身份與權限設定檢查清單。 此審查與 權限時效性 是不同的概念。

選擇一種方法

請依照以下標準找出最適合您資料來源、身份模型及合規要求的方法。

劇本 建議方法 原因為何
自訂身分系統或非 Microsoft 安全架構。 安全過濾器 API 無關性、普遍可用,且基於簡單的字串匹配。
Microsoft Entra 使用者及群組權限推送至索引、索引的 ADLS Gen2 ACL 或索引容器 RBAC 範圍,來自 ADLS Gen2 與 Azure Blob 儲存體。 類似POSIX的ACL / RBAC內視鏡 使用原生權限中繼資料在查詢時強制執行。 結構描述、推送索引和查詢強制執行功能在 REST API 2026-10-01中已正式推出;而針對特定來源的擷取則有各自的可用性需求。
企業內容已受 Microsoft Purview 資訊保護政策所規範。 Microsoft Purview 敏感度標籤 在 Foundry IQ 中沿用集中管理的分類與原則指派。
內容來源為 Microsoft 365 中的 SharePoint(函式庫、清單、ASPX 網站頁面)。 Microsoft 365 ACL 中的 SharePoint 評估同步至搜尋的受支援權限子集。 對於來源端在要求時擷取或客戶控制的更新提交,請比較 SharePoint 擷取方式與新近性。

使用篩選器進行安全性修剪的模式

對於原生 ACL/RBAC 範圍整合不可行的情況,可以使用安全字串過濾器根據排除條件修剪結果。 該圖案包含以下組件:

  • 若要儲存使用者或群組身份,可以在索引中建立字串欄位。
  • 使用包含相關 ACL 的原始文件載入索引。
  • 在查詢邏輯中加入一個篩選式,用於字串上的匹配。
  • 查詢時,取得來電者的身份。
  • 將呼叫者的身份傳遞為濾波字串。
  • 結果會被修剪,排除未包含使用者或群組身份字串的匹配。

您可以使用推送或提取模型 API。 因為這種方法與 API 無關,你只需要確認索引和查詢在過濾步驟中是否有有效的字串(身份)。

此方法適用於擁有自訂存取模型或非 Microsoft 安全框架的系統。 如需此方法的更多資訊,請參閱 Foundry IQ 中用於修剪結果的安全性篩選器。

原生支援類似 POSIX 的 ACL 與 RBAC 權限的模式

原生權限篩選使用索引化的 Microsoft Entra 使用者與群組物件 ID,以及儲存容器 RBAC 範圍。

Azure Data Lake Storage (ADLS) Gen2 支援目錄與檔案上的 ACL。 使用 ADLS Gen2 索引器 或 為 ADLS Gen2 設定的 Blob 知識來源 ,以匯入支援的 ACL 與容器 RBAC 範圍,並搭配 REST API 2026-10-01。 對於標準 Blob 儲存體,Blob 索引器或知識來源會匯入容器的 RBAC 範圍,而非每個檔案的 ACL。

對於 ACL 保護的內容,請使用群組存取而非個別使用者存取,以方便管理。 該圖案包含以下組件:

原生權限篩選查詢會區分呼叫者與被評估其文件權限的使用者:

  • Authorization 攜帶呼叫者用於搜尋 RBAC 的權杖。 應用程式服務主體或受控識別可以使用適當的角色呼叫 Search,例如 Search Index Data Reader 或 Search Index Data Contributor。
  • x-ms-query-source-authorization 攜帶受委派使用者用於文件權限評估的權杖。 群組是權限的中繼資料,而非帶有權杖的身份。

能呼叫搜尋的應用程式不一定被支援作為文件權限主體。 例如,授權應用程式可以在非 Purview 索引上使用提升讀取,但該管理繞過不會評估應用程式的 ACL 成員資格。 有關支援的令牌流與操作特定限制,請參閱 應用程式令牌邊界。

使用 push API 工作流程 載入內容及原生權限元資料。

使用 ADLS Gen2 ACL 與容器範圍,或標準 Blob 容器範圍的拉取模型(索引器)API,搭配 REST API 2026-10-01。

在擷取過程中擷取 ACL 權限的元資料

你取得 ACL 權限的方式會依據你是傳送文件載荷還是使用 ADLS Gen2 索引器而有所不同。

對於 ADLS Gen2 及標準 Blob 權限匯入,請使用 REST API 2026-10-01。 請查看 SDK 變更記錄,確認是否支援該 API 及所需屬性。 GA REST 可用性並不代表 SDK 套件的準備程度。

推送 ACL 匯入功能普遍可用。 推送指南包含 2026-10-01 REST 工作流程。 查看 SDK 變更記錄,以確認是否支援權限篩選器及 ACL/RBAC 匯入:

對於推送模型方法:

  1. 使用 REST API 或支援所需屬性的 Azure SDK 套件,建立帶有權限篩選器的索引結構。
  2. 考慮使用 Microsoft Graph SDK 來取得群組或使用者身份。
  3. 使用 Index Documents或等效的 Azure SDK API 將文件及其相關的權限元資料推送到搜尋索引中。

對於提取模型 ADLS Gen2 索引子方法或 Blob (ADLS Gen2) 知識來源:

  1. 確認目錄中的檔案是否使用 ADLS Gen2 存取控制模型受到保護。
  2. 使用 Indexers - Create(REST API)、Knowledge Sources - Create(REST API),或等效的 Azure SDK API 來建立索引器、索引和資料來源。

如果你的技能組合將 ADLS 或 Blob 文件分塊,請透過 索引投影為每個受保護區塊設定權限,而非僅限索引器欄位映射。

權限匯入的來源中繼資料

來源脈絡與權限授權的用途不同。 保留來源路徑為原始值,而非編碼的鍵、引用 URL 或產生的父 ID。

來源與案例 來源中繼資料與用途 對應與可用性
ADLS 具名使用者/群組 ACLs 必要 metadata_storage_path(Edm.String)用來識別來源。 metadata_user_ids 和 metadata_group_ids 包含有效的 ACL。 將 ACL 對應到以 userIds 和 groupIds 註解的 Collection(Edm.String) 欄位。 保留記錄與區塊上的路徑。 GA 於 2026-10-01。
僅限 ADLS RBAC metadata_storage_path 即使沒有 ACL 欄位,也必須用於擷取 ADLS 權限。 metadata_rbac_scope 識別容器。 將範圍對應至以 rbacScope 註解的 Edm.String 欄位。 所需路徑未用於複製角色指派。 GA 於 2026-10-01。
ADLS 混合 ACL/RBAC 來源路徑、有效使用者/群組 ACL 以及容器範圍。 保留記錄與投影區塊上所有已設定欄位。 任何獨立支援的授權都可以授權存取。 GA 於 2026-10-01。
標準 Blob RBAC metadata_rbac_scope 識別容器;計算此範圍不需要每個文件的路徑。 產生的知識來源管線仍包含 metadata_storage_path。 將純量範圍對應到文件與區塊上帶有 rbacScope 註解的欄位。 沒有 ADLS 檔案 ACL 推論。 GA 於 2026-10-01。
SharePoint ACLs metadata_spo_item_path 提供項目脈絡;metadata_spo_site_url 提供網站脈絡。 清單與頁面也會使用 metadata_spo_site_asset_item_id。 使用來源專屬的 SharePoint 架構與投影指引。 SharePoint 的可用性與需求與 Storage GA 範圍無關。

關於直接架構定義、權威映射、產生的管線以及既有記錄修復,請參閱 ADLS 權限導入 與 Blob RBAC 範圍導入。

關於允許廣泛存取但排除命名身份的 ADLS 來源 ACL,請參閱 不支援的隱含 blocklists式 。

Microsoft 365 中 SharePoint 基本 ACL 權限匯入的模式

對於已索引的 SharePoint 內容,Foundry IQ 可以將支援的來源權限儲存為元資料,並用來篩選查詢結果。 使用此權限設定,請使用 Microsoft 365 索引器中的 SharePoint 搭配 REST API2026-10-01,或使用支援此功能的 SDK 套件。

關於權限要求、支援的群組關係、權限同步及限制,請參見使用 SharePoint 索引器來擷取權限元資料。

如果你的技能組會將文件分塊(例如,使用 Text Split 技能進行整合式向量化時),ACL 欄位會從索引器欄位對應移至索引投影。 請參閱 「選擇填入 ACL 欄位的位置」。

Microsoft Purview 敏感度標籤的模式(預覽)

啟用標籤匯入時,Foundry IQ 會從支援的資料來源擷取敏感度元資料。 這些資料來源包括 Azure Blob 儲存體、Azure Data Lake Storage Gen2(ADLS Gen2)、Microsoft 365 中的 SharePoint,以及 Microsoft OneLake。 擷取後的標籤會與文件內容一同儲存在索引中。

在查詢時,Foundry IQ 會檢查每份文件的敏感度標籤、使用者的 Microsoft Entra 令牌,以及組織的 Purview 政策,以判斷存取權限。 系統僅在使用者身份及基於標籤的權限允許在已設定的 Purview 政策下存取時,才回傳文件。

此圖案包含以下組件:

  • 使用 REST API 或支援 Purview 標籤擷取的預覽 SDK 來設定您的2026-11-01-preview、資料來源與索引器(用於排程目的)。
  • 在您的 Foundry IQ 服務上啟用 系統指派的管理身份 。 使用者指派的受管理身份不支援 Purview 標籤擷取——服務自身的身份必須持有提升的 Purview 權限。 接著請您的租戶全域管理員或特權角色管理員授權所需存取權限,讓 Foundry IQ 服務能透過 Microsoft Purview 進行驗證並擷取標籤中繼資料。
  • 在建立索引之前,先對文件套用敏感度標籤,讓系統在擷取處理期間能夠辨識並保留這些標籤。
  • 在查詢時,透過標頭 x-ms-query-source-authorization 為每個查詢請求附加一個有效的 Microsoft Entra 標記。 Foundry IQ 會評估該令牌及相關標籤的元資料,以強制執行基於標籤的存取控制。

Purview 敏感性標籤的強制執行僅限於單一租戶情境,且需 RBAC 認證。 在預覽版期間,僅支援 REST API 和 Azure SDK。 Autocomplete 和 Suggest API 目前尚不支援已啟用 Purview 的索引。

敏感度標籤被呈現的地方

在系統能在查詢時強制標籤或在檢索回應中回傳標籤之前,你必須先將標籤的元資料同步到索引中。 本節所述的兩種消耗路徑都依賴於此同步步驟。 您可以透過直接設定 Foundry IQ 索引器對支援的資料來源進行同步,或在建立知識來源時啟用等效的匯入選項來同步標籤。 在這兩種情況下,您的環境都必須符合敏感度標籤的元資料同步設定先決條件(管理身份、Foundry IQ 服務上的 RBAC,以及所需的 Microsoft Purview 與資料來源權限)。 關於端對端索引器的設定,請參閱使用 Foundry IQ 索引器匯入 Microsoft Purview 敏感度標籤。 對於知識來源驅動的擷取,請在ingestionPermissionOptions期間,將 sensitivityLabel 設定為包含 。

在同步標籤後,兩個查詢路徑會消耗相同的索引標籤元資料。 選擇符合您應用程式呼叫 Foundry IQ 方式的路徑:

  • 直接查詢 API(/docs/search):將使用者的 Microsoft Entra 令牌附加於 x-ms-query-source-authorization。 管理員也可以提出提高權限的讀取請求,以進行可供稽核的調查。 如需設定與範例,請參閱 查詢時強制執行 Microsoft Purview 敏感度標籤。

  • 知識來源與代理式擷取(MCP):將 ingestionPermissionOptions 設定為在知識來源中包含 sensitivityLabel。 擷取動作和 MCP knowledge_base_retrieve 工具會傳回每個參考的 sensitivityLabelInfo 和回應層級 metadata.responseSensitivityLabelInfo,用戶端可以將其用於顯示橫幅和原則強制執行。 關於設定,請參閱 建立知識來源 ,並在 檢索回應中檢查敏感性標籤元資料。

如果知識來源指向分塊索引,例如透過整合向量化或自訂的文字分割技能所填充的索引,技能組也必須 將敏感度標籤投射到每一分塊列。 沒有這個投影,區塊層級的參考不會被過濾。

如需更多資訊,請參閱使用 Foundry IQ 索引器匯入 Microsoft Purview 敏感度標籤。

在查詢時強制執行文件層級的權限

基於標記的查詢強制是一種跨領域能力,適用於類似 POSIX 的 ACL 與 RBAC 範圍、Microsoft Purview 敏感性標籤,以及 Microsoft 365 ACL 模式中的 SharePoint。 透過原生權杖查詢,Foundry IQ 會在每個請求中驗證呼叫者的 Microsoft Entra 權杖,並將結果集裁剪為僅依文件 ACL 授權讀取的文件,只要文件 ACL 的中繼資料與索引同步即可。

當您透過 x-ms-query-source-authorization 標頭將使用者的令牌附加到查詢請求時,Foundry IQ:

  1. 從標記中擷取使用者、群組及範圍的權利要求。
  2. 將這些聲明與與索引文件(ACL 條目、RBAC 範圍、Purview 標籤指派或 SharePoint ACL)一同儲存的權限元資料進行比較。
  3. 僅回傳同步權限元資料賦予呼叫者存取的文件。

權限更新時效

查詢時強制執行使用已儲存的權限元資料,但新度取決於權限的類型。 ADLS 使用者與群組 ACL 是索引快照:僅 ACL 的變更會透過預設啟用、約每日一次且適用於符合條件之正常執行的自動重新整理,或明確的權限重新同步來更新。 容器 RBAC 範圍用於識別資源,而非角色指派;委託使用者授權會在查詢時另行評估,並考量傳播與快取。 群組成員關係解析也有其自身的傳播與快取行為。

對 SharePoint 而言,增量處理涵蓋偵測到的項目層級變更及支援的非根資料夾權限變更,包括未變更的子孫。 其他範圍或遺漏的通知可能需要明確重新整理。 請參閱「 同步索引內容與來源內容之間的權限 」以了解情境表與時間限制。

權限刷新不會立即撤銷權限或提供全文庫的新鮮度 SLA。 有關操作步驟、失敗、區塊一致性及清理,請參閱 ADLS 同步、Blob 範圍新鮮度及 SharePoint 同步。 自訂推播擷取仍負責同步自身的元資料。

關於端對端查詢實作步驟,請參閱 Foundry IQ 中的查詢時 ACL 與 RBAC 強制執行。

文件層級存取控制的優點

Foundry IQ 的原生文件層級存取控制相較於應用端過濾帶來具體優勢:

  • 減少自訂權限代碼: Foundry IQ 在查詢執行時處理支援的群組解析與權限篩選。
  • 與現有合規控管保持一致:重複使用 Microsoft Entra、Microsoft Purview 和 SharePoint 權限的元資料,有助於保持搜尋結果與來源身份系統的一致性。 檢視每個來源的權限同步模型,以了解其限制。
  • 每次 ACL 同步後尊重來源權限:對於基於權杖的方法(ACL、RBAC 範圍、Purview 標籤、SharePoint ACL),查詢時強制執行使用已記錄的來源特定同步機制(索引器執行、推送 API 更新或 Purview 更新)已寫入索引的權限元資料。
  • 相較於查詢後修剪,提升效能: 在搜尋管線內進行篩選,比起將較大的結果集載入應用程式並在那裡修剪,尤其是在查詢量大時,要快得多。
  • 重複使用您現有的身份基礎架構:Microsoft Entra 與 SharePoint 身份仍然是存取決策的真實來源,這減少了身份重複以及維護平行權限存放區的營運負擔。

教學與範例

透過更多文章與範例,探索 Foundry IQ 中的文件層級存取控制。