Note
Azure AI 搜尋服務 可透過 Azure 入口網站、REST API 及 Azure SDK 取得。 它同時也是 Foundry IQ 的基礎，這是一個管理式知識層，能將企業內容轉化為可重複使用、權限感知的知識庫，供 Microsoft Foundry 入口網站中的代理使用。
Important
標記（預覽）的功能、能力或屬性不受服務等級協議涵蓋，也不建議用於生產工作負載，且在正式上架前可能會有所變動或受限。 Azure AI 搜尋服務 預覽條款適用於所有預覽功能，無論是獨立功能還是正式推出功能的一部分。
Azure AI 搜尋服務 支援文件層級的存取控制，使組織能在文件層級執行細緻權限，從資料擷取到查詢執行皆可執行。 這項能力對於建構安全的人工智慧代理系統（基於資料）、檢索增強生成（RAG）應用程式，以及需要文件層級授權檢查的企業搜尋解決方案至關重要。
文件層級存取控制的方法
Azure AI 搜尋服務 提供四種主要方法來強制執行文件層級的權限，每種方法都適合不同的資料來源與身份模型。
| 方法 | 描述 |
|---|---|
| 安全過濾器 | 字串比較。 你的應用程式會以字串形式傳遞使用者或群組身份，這個字串會在查詢中填入一個過濾器，排除與字串不符的文件。 安全過濾器是一種實現文件層級存取控制的技術。 這種方法不受 API 限制，所以你可以使用任何版本或套件。 |
| 類似 POSIX 的 ACL / RBAC 內窺鏡（預覽） | 系統會將查詢權杖背後的 Microsoft Entra 安全性主體，與搜尋結果中傳回文件的權限中繼資料進行比對，並排除任何權限不相符的文件。 存取控制清單（ACL）權限會套用到 Azure Data Lake Storage（ADLS）Gen2 目錄和檔案。 基於角色的存取控制（RBAC）範圍適用於 ADLS Gen2 內容及 Azure blobs。 內建於文件層級的身份存取支援，現已預覽，並可在提供此功能的 REST API 及預覽版 Azure SDK 套件中取得。 如需功能支援的證據，請參閱 SDK 版本支援細節。 |
| Microsoft Purview 敏感度標籤（預覽） | 索引器從支援的資料來源（Azure Blob 儲存體、ADLS Gen2、Microsoft 365 中的 SharePoint、OneLake）中擷取 Microsoft Purview 定義的敏感度標籤。 這些標籤會儲存為中繼資料，並在查詢時評估，以根據 Microsoft Entra 權杖和 Purview 原則指派強制執行使用者存取權。 標籤也會透過 知識來源 和 代理式擷取回應提供，讓使用知識庫的 AI 代理和聊天應用程式也能獲得相同具標籤感知能力的篩選。 此方法使Azure AI 搜尋服務授權與企業的Microsoft 資訊保護模式相符。 |
| Microsoft 365 ACL 中的 SharePoint（預覽版） | Azure AI 搜尋服務 索引器會從支援的 SharePoint 內容中擷取權限元資料，並用於查詢時的存取檢查。 關於支援的內容、主體、群組關係、同步行為及權限，請參見使用 SharePoint 索引器來導入權限元資料。 |
對於索引知識來源， ingestionPermissionOptions 無法與 assetStore合併。 因此，當啟用原生文件層級權限擷取時，映像服務 (預覽) 無法使用。
選擇一種方法
請依照以下標準找出最適合您資料來源、身份模型及合規要求的方法。
| 劇本 | 建議方法 | 原因為何 |
|---|---|---|
| 自訂身份系統、非 Microsoft 的安全框架，或任何推送模型索引。 | 安全過濾器 | API 無關性、普遍可用，且基於簡單的字串匹配。 |
| ADLS Gen2 或 Azure Blob 儲存體 中已具備 ACL 或 RBAC 指派的內容。 | 類似POSIX的ACL / RBAC內視鏡 | 原生 Microsoft Entra 整合；查詢時間強制執行會使用透過記錄同步機制寫入索引的權限中繼資料。 |
| 企業內容已受 Microsoft Purview 資訊保護政策所規範。 | Microsoft Purview 敏感度標籤 | 在 Azure AI 搜尋服務中重複使用集中式分類和原則指派。 |
| 內容來源為 Microsoft 365 中的 SharePoint（函式庫、清單、ASPX 網站頁面）。 | Microsoft 365 ACL 中的 SharePoint | 尊重原生 SharePoint 權限，包括 SharePoint 站點群組。 |
使用篩選器進行安全性修剪的模式
對於原生 ACL/RBAC 範圍整合不可行的情況，可以使用安全字串過濾器根據排除條件修剪結果。 該圖案包含以下組件：
- 若要儲存使用者或群組身份，可以在索引中建立字串欄位。
- 使用包含相關 ACL 的原始文件載入索引。
- 在查詢邏輯中加入一個篩選式，用於字串上的匹配。
- 查詢時，取得來電者的身份。
- 將呼叫者的身份傳遞為濾波字串。
- 結果會被修剪，排除未包含使用者或群組身份字串的匹配。
您可以使用推送或提取模型 API。 因為這種方法與 API 無關，你只需要確認索引和查詢在過濾步驟中是否有有效的字串（身份）。
此方法適用於擁有自訂存取模型或非 Microsoft 安全框架的系統。 欲了解更多關於此方法的信息，請參閱Azure AI 搜尋服務中的用於修剪結果的安全篩選器。
原生支援類似 POSIX 的 ACL 與 RBAC 範圍權限的模式（預覽）
原生支援是基於 Microsoft Entra 使用者以及您想要索引和查詢文件相關的群組。
Azure Data Lake Storage （ADLS） Gen2 容器支援容器及檔案上的 ACL。 對於 ADLS Gen2，當你使用 ADLS Gen2 索引器 或 Blob 知識來源（支援 ADLS Gen2） 並使用預覽 API 來匯入內容時，文件層級的 RBAC 範圍保留是原生支援的。 對於使用 Azure blob 索引器或知識來源的 Azure blob，RBAC 範圍保存則在容器層級進行。
對於 ACL 保護的內容，請使用群組存取而非個別使用者存取，以方便管理。 該圖案包含以下組件：
- 從有ACL指派的文件或檔案開始。
- 在索引中啟用權限篩選 功能。
- 在索引中的字串欄位新增權限過濾器。
- 將帶有相關 ACL 的原始文件載入索引。
- 查詢索引，並加入
x-ms-query-source-authorization請求標頭。
您的客戶端應用程式透過 搜尋索引資料閱讀 器或 搜尋索引資料貢獻 者角色，獲得索引的讀取權限。 查詢時的存取權由索引內容中的使用者或群組權限元資料決定。 包含權限過濾器的查詢會將使用者或群組的權杖以 x-ms-query-source-authorization 的形式傳入至請求標頭中。 當你在查詢時使用權限篩選器時，Azure AI 搜尋服務 會檢查兩件事：
首先，它會檢查搜尋 索引資料閱讀 器的權限，讓你的客戶端應用程式能夠存取該索引。
其次，考量到請求中的額外權杖，系統會檢查搜尋結果中所返回的文件是否符合使用者或群組權限，並排除任何不符合的文件。
要將權限元資料輸入索引，請使用 push model API，將任何 JSON 文件推送到搜尋索引，該索引中包含一個字串欄位，為每份文件提供類似 POSIX 的 ACL。 此方法與安全修剪的重要差異在於，索引與查詢中的權限過濾元資料會被識別為 Microsoft Entra ID 認證，而安全修剪的替代方案則是簡單的字串比較。 另外，你也可以用 Graph SDK 來取得這些身份。
如果資料來源是
在資料引入過程中擷取 ACL 權限的元資料（預覽）
你取得 ACL 權限的方式會依據你是傳送文件載荷還是使用 ADLS Gen2 索引器而有所不同。
從提供以下功能的預覽 API 開始：
- 2026-08-01-preview REST API
- Azure SDK 用於Python預發布套件。 請查看更新日誌，以確認支援 ACL 和 RBAC 範圍擷取的最新預覽版本。
- Azure SDK 用於.NET預發布套件。 請查看更新日誌，以確認支援 ACL 和 RBAC 範圍擷取的最新預覽版本。
- Azure SDK 用於Java預發布套件。 請查看更新日誌，以確認支援 ACL 和 RBAC 範圍擷取的最新預覽版本。
對於推送模型方法：
- 確認你的索引結構是用預覽版或預發布版 SDK 建立，且結構有權限篩選器。
- 考慮使用 Microsoft Graph SDK 來取得群組或使用者身份。
- 使用 Index Documents或等效的 Azure SDK API 將文件及其相關的權限元資料推送到搜尋索引中。
對於提取模型 ADLS Gen2 索引子方法或 Blob (ADLS Gen2) 知識來源：
- 確認目錄中的檔案是否使用 ADLS Gen2 存取控制模型受到保護。
- 使用 Indexers - Create（REST API）、Knowledge Sources - Create（REST API），或等效的 Azure SDK API 來建立索引器、索引和資料來源。
如果您的技能集會將文件分塊，例如使用 Text Split 技能進行整合式向量化，權限中繼資料欄位會從索引子欄位對應移至索引投影。 請參閱 「選擇填入 ACL 欄位的位置」。
Microsoft 365 中 SharePoint 基本 ACL 權限匯入的模式（預覽）
對於索引的 SharePoint 內容，Azure AI 搜尋服務 可以將來源權限儲存為元資料，並用來過濾查詢結果。 你可以透過 Microsoft 365 中的 SharePoint 索引器以及最新的 REST API 或等效的預覽 SDK 套件來取得此功能。
關於權限要求、支援的群組關係、權限同步及限制，請參見使用 SharePoint 索引器來擷取權限元資料。
如果你的技能組會將文件分塊（例如，使用 Text Split 技能進行整合式向量化時），ACL 欄位會從索引器欄位對應移至索引投影。 請參閱 「選擇填入 ACL 欄位的位置」。
Microsoft Purview 敏感度標籤的模式（預覽）
啟用標籤擷取後，Azure AI 搜尋服務 會從支援的資料來源擷取敏感度元資料。 這些資料來源包括 Azure Blob 儲存體、Azure Data Lake Storage Gen2（ADLS Gen2）、Microsoft 365 中的 SharePoint，以及 Microsoft OneLake。 擷取後的標籤會與文件內容一同儲存在索引中。
在查詢時，Azure AI 搜尋服務 會檢查每份文件的敏感性標籤、使用者的 Microsoft Entra 憑證，以及組織的 Purview 政策，以判斷存取權限。 系統僅在使用者身份及基於標籤的權限允許在已設定的 Purview 政策下存取時，才回傳文件。
此圖案包含以下組件：
- 使用最新的預覽版 REST API 或支援 Purview 標籤擷取的預覽 SDK 來設定您的 索引、 資料來源和 索引器 （用於排程）。
- 在您的搜尋服務中啟用 系統指派的管理身份 。 使用者指派的受管理身份不支援 Purview 標籤擷取——服務自身的身份必須持有提升的 Purview 權限。 接著，請您的租戶全域管理員或特權角色管理員授與所需的存取權限，以便讓搜尋服務通過 Microsoft Purview 驗證並擷取標籤中繼資料。
- 在建立索引之前，先對文件套用敏感度標籤，讓系統在擷取處理期間能夠辨識並保留這些標籤。
- 在查詢時，透過標頭
x-ms-query-source-authorization為每個查詢請求附加一個有效的 Microsoft Entra 標記。 Azure AI 搜尋服務 會評估憑證及相關的標籤元資料，以強制執行基於標籤的存取控制。
Purview 敏感性標籤的強制執行僅限於單一租戶情境，且需 RBAC 認證。 在預覽版期間，僅支援 REST API 和 Azure SDK。 Autocomplete 和 Suggest API 目前尚不支援已啟用 Purview 的索引。
敏感度標籤被呈現的地方
在系統能在查詢時強制標籤或在檢索回應中回傳標籤之前，你必須先將標籤的元資料同步到索引中。 本節所述的兩種消耗路徑都依賴於此同步步驟。 你可以透過設定 Azure AI 搜尋服務 索引器直接對支援的資料來源同步標籤，或在建立知識來源時啟用相應的擷取選項來同步標籤。 在這兩種情況下，你的環境都必須符合敏感標籤、元資料同步配置的前提條件（管理身份、搜尋服務上的 RBAC，以及所需的Microsoft Purview和資料來源權限）。 如需了解端對端索引器設定，請參閱 使用 Azure AI 搜尋服務 索引器擷取 Microsoft Purview 敏感度標籤。 對於知識來源驅動的擷取，請在ingestionPermissionOptions期間，將 sensitivityLabel 設定為包含 。
在同步標籤後，兩個查詢路徑會消耗相同的索引標籤元資料。 選擇符合你應用程式呼叫 Azure AI 搜尋服務 方式的路徑：
Direct query API （
/docs/search）：將使用者的Microsoft Entra令牌附加在x-ms-query-source-authorization。 管理員也可以提出提高權限的讀取請求，以進行可供稽核的調查。 如需設定與範例，請參閱 查詢時強制執行 Microsoft Purview 敏感度標籤。知識來源與代理檢索（MCP）：設定
ingestionPermissionOptions為包含sensitivityLabel在知識來源中。 擷取動作和 MCPknowledge_base_retrieve工具會傳回每個參考的sensitivityLabelInfo和回應層級metadata.responseSensitivityLabelInfo，用戶端可以將其用於顯示橫幅和原則強制執行。 關於設定，請參閱 建立知識來源 ，並在 檢索回應中檢查敏感性標籤元資料。
如果知識來源指向分塊索引，例如透過整合向量化或自訂的文字分割技能所填充的索引，技能組也必須 將敏感度標籤投射到每一分塊列。 沒有這個投影，區塊層級的參考不會被過濾。
欲了解更多資訊，請參閱 使用 Azure AI 搜尋服務 索引器來攝取 Microsoft Purview 敏感性標籤。
在查詢時強制執行文件層級權限（預覽）
基於標記的查詢強制是一種跨領域能力，適用於類似 POSIX 的 ACL 與 RBAC 範圍、Microsoft Purview 敏感性標籤，以及 Microsoft 365 ACL 模式中的 SharePoint。 透過原生基於權杖的查詢，Azure AI 搜尋服務 會在每個請求中驗證呼叫者的 Microsoft Entra 令牌，並將結果集修剪為僅根據文件 ACL 授權閱讀的文件，只要文件 ACL 元資料與索引同步即可。
當您透過 x-ms-query-source-authorization 標頭將使用者的權杖附加至查詢要求時，Azure AI 搜尋服務會：
- 從標記中擷取使用者、群組及範圍的權利要求。
- 將這些聲明與與索引文件（ACL 條目、RBAC 範圍、Purview 標籤指派或 SharePoint ACL）一同儲存的權限元資料進行比較。
- 僅回傳同步權限元資料賦予呼叫者存取的文件。
查詢時間強制執行會根據已儲存在索引中的權限中繼資料，評估呼叫端的 Microsoft Entra 宣告。 來源系統中的權限變更（Microsoft Entra 群組成員、ADLS Gen2 ACL、Purview 標籤指派或 SharePoint ACL）只有在該中繼資料透過特定來源機制同步到索引後，才會反映在搜尋結果中，例如後續的索引器執行、推送 API 更新或 Purview 驅動的刷新。 對於 SharePoint，從 2026-05-01-preview REST API 版本開始，針對設有唯一權限的項目，其 ACL 變更會在每次索引器成功執行時以增量方式擷取；而繼承自父範圍（網站、文件庫、清單或資料夾）的變更則需要明確重新整理。 欲了解更多資訊，請參閱 索引內容與來源內容間的權限同步。
關於端對端查詢實作步驟，請參見
文件層級存取控制的優點
Azure AI 搜尋服務 的原生文件層級存取控制相較於應用端過濾帶來具體優勢：
- 移除自訂權限碼： 你不需要在應用程式中實作巢狀群組解析、多層 ACL 遍歷或查詢後的修剪。 Azure AI 搜尋服務 在查詢執行時負責比較與篩選。
- 符合現有合規控管：重用Microsoft Entra、Microsoft Purview及SharePoint權限元資料有助於保持搜尋結果與來源身份系統的一致性。 檢視每個來源的權限同步模型，以了解其限制。
- 每次 ACL 同步後，尊重來源權限：對於基於標記的方法（ACL、RBAC 範圍、Purview 標籤、SharePoint ACL），查詢時強制執行使用文件中特定來源同步機制（索引器執行、推送 API 更新或 Purview 更新）已寫入索引的權限元資料。
- 相較於查詢後再裁減結果，可提升效能： 在搜尋管線中篩選，比將較大的結果集載入到應用程式中再加以裁減更快，尤其是在查詢量很高時。
- 沿用您現有的身分基礎架構： Microsoft Entra 和 SharePoint 的身分仍是存取決策的主要依據，可減少身分重複，以及維護平行權限存放區所帶來的營運負擔。
教學與範例
探索 Azure AI 搜尋服務 中的文件層級存取控制，更多文章與範例。
- 教學：使用索引器索引 ADLS Gen2 權限的元資料（預覽）
- azure-search-rest-samples/acl
- azure-search-python-samples/Quickstart-Document-Permissions-Push-API
- azure-search-python-samples/Quickstart-Document-Permissions-Pull-API
- 示範應用程式：擷取並遵循敏感度標籤