使用推送 REST API 索引文件存取控制清單（ACL）（預覽版）

透過推送 REST API（預覽版）進行文件層級權限擷取，允許你索引文件及其相關的 存取控制清單（ACL） 和容器 角色基礎存取控制（RBAC）角色。 當你透過推送 REST API 將內容推送到 Azure AI 搜尋服務 索引時，服務會保留這些權限，並在查詢時強制執行。

主要特色包括：

• 對資料輸入流程的彈性控制。
• 權限元資料的標準化架構。
• 支援階層式權限，例如資料夾層級的 ACL。

本文說明如何使用 push REST API 在 Azure AI 搜尋服務 中索引文件層級的權限元資料。 這個過程能讓你的索引準備好查詢並執行最終使用者對搜尋結果的權限。

先決條件

• 來自 Microsoft Entra ID 或其他 POSIX 樣式 ACL 系統，且包含 ACL 中繼資料的內容。 對於 userIds 和 groupIds ACL 欄位，請使用 Microsoft Entra 物件 ID（GUID），而非 UPN 或電子郵件地址。 穩定的物件 ID 確保查詢時的身份匹配可靠，即使目錄屬性改變。

• 最新預覽版 REST API或提供相當功能的預覽Azure SDK套件。

• 已啟用 permissionFilterOption 的索引結構描述，加上儲存文件權限的 permissionFilter 欄位屬性。

限制

• ACL 欄位中，具有權限過濾器類型userIds或groupIds時，最多可容納 1000 個值。

• 索引在所有文件的欄位 rbacScope 中最多可包含五個獨特的值。 與 的值相同 rbacScope的文件數量沒有限制。

• 可以更新現有欄位，使其包含內建 ACL 或 RBAC 中繼資料篩選的 permissionFilter 指派。 若要啟用現有索引的篩選功能，請新增欄位或更新現有欄位以加入 permissionFilter 一個值。

• 索引中只能存在每種 permissionFilter 類型的一個欄位 (groupIds、userIds 和 rbacScope 各一個)。

• 每個 permissionFilter 欄位都應該設 filterable 為 true。

• 查詢時的權限強制會反映最後寫入索引的 ACL 值。 如果來源權限改變，這些更新不會被反映，直到你重新輸入或更新受影響的文件。 安排增量重新擷取或部分更新，以使存取控制清單保持最新狀態。

• 目前 Azure 入口網站不支援此功能。

建立一個帶有權限篩選欄位的索引

使用 REST API 索引文件 ACL 與 RBAC 元資料時，需要設定一個索引結構，啟用權限篩選器並包含權限篩選欄位。

首先，加上 permissionFilterOption。 有效的值是 enabled 或 disabled，你應該設為 enabled。 如果你想在索引層關閉權限過濾功能，可以切換成 disabled 。

第二，為你的權限元資料建立字串欄位，並包含 permissionFilter。 請記住，你可以擁有每種權限篩選器類型的一個。

這裡有一個包含所有 permissionFilter 類型的基本範例範例：

{  
  "fields": [  
    { "name": "UserIds", "type": "Collection(Edm.String)", "permissionFilter": "userIds", "filterable": true },  
    { "name": "GroupIds", "type": "Collection(Edm.String)", "permissionFilter": "groupIds", "filterable": true },  
    { "name": "RbacScope", "type": "Edm.String", "permissionFilter": "rbacScope", "filterable": true },  
    { "name": "DocumentId", "type": "Edm.String", "key": true }  
  ],
  "permissionFilterOption": "enabled"
}

對於企業級倉庫，如 SharePoint Online，在擷取時，先解析文件層級或資料夾層級的 Microsoft Entra 使用者及群組物件 ID 權限，再呼叫推送 API。 接著你應該把這些 ID 存到對應的權限欄位。

REST API 索引範例

一旦你有了帶有權限篩選欄位的索引，就可以像其他文件欄位一樣，使用 push index API 來填充這些值。 這裡有一個使用指定索引結構的範例，每個文件都指定索引動作、鍵欄位（）DocumentId和權限欄位。 文件也應該包含內容，但為了簡潔起見，這個欄位在此範例中省略了。

POST https://exampleservice.search.windows.net/indexes('indexdocumentsexample')/docs/search.index?api-version=2026-08-01-preview
{
  "value": [
    {
      "@search.action": "upload",
      "DocumentId": "1",
      "UserIds": ["00aa00aa-bb11-cc22-dd33-44ee44ee44ee", "11bb11bb-cc22-dd33-ee44-55ff55ff55ff", "22cc22cc-dd33-ee44-ff55-66aa66aa66aa"],
      "GroupIds": ["none"],
      "RbacScope": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/Example-Storage-rg/providers/Microsoft.Storage/storageAccounts/azurestorage12345/blobServices/default/containers/blob-container-01"
    },
    {
      "@search.action": "merge",
      "DocumentId": "2",
      "UserIds": ["all"],
      "GroupIds": ["33dd33dd-ee44-ff55-aa66-77bb77bb77bb", "44ee44ee-ff55-aa66-bb77-88cc88cc88cc"]
    },
    {
      "@search.action": "mergeOrUpload",
      "DocumentId": "3",
      "UserIds": ["1cdd8521-38cf-49ab-b483-17ddaa48f68f"],
      "RbacScope": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/Example-Storage-rg/providers/Microsoft.Storage/storageAccounts/azurestorage12345/blobServices/default/containers/blob-container-03"
    }
  ]
}

ACL 存取解析規則

本節說明系統如何根據每份文件的權限欄位來決定使用者的文件存取權限。 這些欄位不是 ACL（userIds 和 groupIds，其中 groupIds 包含安全性群組和 Microsoft 365 群組），就是 RBAC 範圍（rbacScope）。 Azure 依照 ADLS Gen2 權限模型，依照定義順序評估 RBAC 範圍與 ACL。

使用者在滿足下列其中一項欄位後可獲得存取權：相符的 userIds 或 groupIds 項目，或 rbacScope 的合格 Azure 角色指派。 如需瞭解查詢時如何提供呼叫者身分的相關資訊，請參閱 查詢時的 ACL 與 RBAC 強制執行。

特殊 ACL 值「all」和「none」

ACL 欄位，如 userIds 和 groupIds，通常包含 GUID（全球唯一識別碼）清單，用以識別有存取文件權限的使用者與群組。 支援兩種特殊的字串值，「all」和「none」，用於這些 ACL 欄位類型。 這些數值作為廣泛過濾器，在全域層級控制存取，如下表所示。

由於使用者只需匹配一個欄位類型，特殊值「all」會允許公開存取，無論其他 ACL 欄位值如何。 相反地，設定 userIds 為「無」或陣列為空，則不會有 使用者根據使用者 ID 存取該文件。 他們仍可能透過匹配群組 ID 或 RBAC 元資料獲得存取權限。

存取控制範例

此範例說明文件存取規則如何根據 、 userIdsgroupIds、 rbacScope及 中的權限欄位值來解析。 為了可讀性，此情境使用如「user1」和「group1」等別名來取代 GUID;在生產環境中，則使用 Microsoft Entra 物件 ID（GUID）。

相關內容

• 使用角色來連接 Azure AI 搜尋服務
• 查詢時 ACL 與 RBAC 強制執行
• azure-search-python-samples/Quickstart-Document-Permissions-Push-API