使用 push REST API 索引文件 ACL

註

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

透過推送 REST API 進行文件層級權限匯入功能已普遍提供。 使用 push REST API 來索引包含 Microsoft Entra 使用者與群組 ID 或儲存容器 RBAC 範圍的內容。 Foundry IQ(Azure AI 搜尋服務)會利用這些元資料在查詢時篩選文件。

主要特色包括:

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

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

先決條件

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

  • REST API 版本 2026-10-01。

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

  • 具備建立索引定義、上傳文件及查詢索引的現有權限。 關於基於角色的存取,請參閱 使用角色連線。

  • 查詢範例中,使用委派的使用者存取權杖及同一使用者的 Microsoft Entra 物件 ID。 請參閱 查詢時令牌角色與權限流程。

限制

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

  • 索引在所有文件中最多只能包含五個不同的 rbacScope 值。

  • 原生 permissionFilter 註解可以新增至或從現有的相容欄位移除。 現有註解無法直接變更為不同的權限篩選類型。

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

  • 每個 permissionFilter 欄位必須是 filterable,且位於頂層。 它不能是鍵或向量場。 權限欄位不能有分析器、正規化器或同義詞對應。

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

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

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

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

明確設定 permissionFilterOption 為 enabled。 有效值為 enabled 和 disabled。 在帶有權限欄位註解的新索引中,省略此選項會預設為 enabled。 在更新時,省略會在存在時保留現有選項。

對 userIds 和 Collection(Edm.String) 使用 groupIds,對 rbacScope 使用 Edm.String。 索引可以包含每種註解類型各一個欄位。

以下 2026-10-01 工作流程會建立一個具有 userIds 權限欄位的獨立範例索引。 可搜尋的 content 欄位也支援 moreLikeThis 範例。 請以您的端點替換 <SEARCH_ACCESS_TOKEN>,並以具備所需 <SEARCH_SERVICE_ENDPOINT> 的呼叫者權杖替換 。 僅在新索引時使用範例名稱,因為該請求會更新一個具有相同名稱的現有索引。

PUT <SEARCH_SERVICE_ENDPOINT>/indexes('secured-content-index')?api-version=2026-10-01
Authorization: Bearer <SEARCH_ACCESS_TOKEN>
Content-Type: application/json
Accept: application/json

{
  "name": "secured-content-index",
  "fields": [
    {
      "name": "id",
      "type": "Edm.String",
      "key": true,
      "searchable": false,
      "filterable": true,
      "sortable": true
    },
    {
      "name": "content",
      "type": "Edm.String",
      "searchable": true,
      "filterable": false,
      "sortable": false,
      "facetable": false
    },
    {
      "name": "category",
      "type": "Edm.String",
      "searchable": false,
      "filterable": true,
      "sortable": false,
      "facetable": false
    },
    {
      "name": "userIds",
      "type": "Collection(Edm.String)",
      "filterable": true,
      "retrievable": false,
      "searchable": false,
      "sortable": false,
      "facetable": false,
      "permissionFilter": "userIds"
    }
  ],
  "permissionFilterOption": "enabled"
}

參考:建立或更新索引。

以下 2026-10-01 結構範例說明本文後續索引範例中三種原生權限欄位類型:

{  
  "fields": [  
    { "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": "RbacScope", "type": "Edm.String", "permissionFilter": "rbacScope", "filterable": true, "retrievable": false },
    { "name": "DocumentId", "type": "Edm.String", "key": true }  
  ],
  "permissionFilterOption": "enabled"
}

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

建立受信任文件身分與權限授予

限制文件發佈僅限於有權維護目標內容與權限的身份。 發佈者必須針對同一文件識別取得權威存取政策的權限授予,而非從一般內容複製類似權限的屬性。

在提交上傳或合併前,請一併檢視文件金鑰與權限。 重複使用鍵值會指向相同的索引記錄;撰寫內容的許可本身並不代表有權更改其他紀錄的內容或權限。 當多個受信任來源有意共用同一個紀錄時,請就其所有權及最終許可政策達成共識。 合併是取代已提供的集合,而非將其條目與現有值合併。

對於客戶管理的管線,控制哪個來源值提供 DocumentId,以及哪項政策提供該身分的授權。 如果商業識別碼在各來源間不具唯一性,請將它們分開使用。 不要讓信任度較低的內容選擇其他記錄的鍵或權限值。 這些責任屬於授權出版商,而非新的所有權強制執行設定。

權限欄位註解可啟用對儲存值的查詢評估;並不表示內容作者有權提供這些權限授予。 使用 擷取設定檢查清單 ,將身份與權限選擇保留在受信任的發佈程序內。

REST API 索引範例

像填寫其他文件欄位一樣填寫權限欄位。 對於您先前建立的 2026-10-01 索引,請上傳以下四份文件。 以您在 <USER_OBJECT_ID>中提供的委派使用者 Microsoft Entra 物件 ID 取代 。 文件 21、101 和 control 授予該使用者存取權;hidden 沒有授權。

POST <SEARCH_SERVICE_ENDPOINT>/indexes('secured-content-index')/docs/search.index?api-version=2026-10-01
Authorization: Bearer <SEARCH_ACCESS_TOKEN>
Content-Type: application/json
Accept: application/json

{
  "value": [
    {
      "@search.action": "upload",
      "id": "21",
      "content": "Astronomers use telescopes to study stars and galaxies. Telescope observations reveal stellar light and distant planets. An observatory records repeated measurements of stars to compare their brightness.",
      "category": "astronomy",
      "userIds": [
        "<USER_OBJECT_ID>"
      ]
    },
    {
      "@search.action": "upload",
      "id": "101",
      "content": "Astronomers use telescopes to study stars and galaxies. Telescope observations reveal stellar light and distant planets. An observatory records repeated measurements of stars to compare their brightness.",
      "category": "astronomy",
      "userIds": [
        "<USER_OBJECT_ID>"
      ]
    },
    {
      "@search.action": "upload",
      "id": "hidden",
      "content": "Astronomers use telescopes to study stars and galaxies. Telescope observations reveal stellar light and distant planets. An observatory records repeated measurements of stars to compare their brightness.",
      "category": "astronomy",
      "userIds": [
        "none"
      ]
    },
    {
      "@search.action": "upload",
      "id": "control",
      "content": "Botanical gardens cultivate orchids and roses. Gardeners prune flowering plants and water their roots. A greenhouse protects young seedlings from cold weather.",
      "category": "gardening",
      "userIds": [
        "<USER_OBJECT_ID>"
      ]
    }
  ]
}

參考資料: 索引文件。

繼續執行 查詢範例,確認會回傳使用者的文件,而 hidden 會被排除在外。

以下 2026-10-01 範例說明其他選項。

POST https://exampleservice.search.windows.net/indexes('indexdocumentsexample')/docs/search.index?api-version=2026-10-01
{
  "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": ["none"],
      "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"
    }
  ]
}

更新在 2026 年 10 月正規化變更前推送的 ACL

當您提交文件時,Foundry IQ 會將權限 ID 值標準化為小寫。 此行為適用於標註有 permissionFilter: "userIds" 或 permissionFilter: "groupIds" 的欄位,但不適用於欄位名稱或不相關的文件欄位。

2026 年 10 月的服務更新引入了 2026-05-01-preview 與 2026-08-01-preview的正規化。 此變更在 2026-10-01 GA REST API 中持續進行。 該服務不會自動重寫先前儲存的值。 僅僅更改 API 版本並不會更新它們。

如果您在正規化變更前直接使用任一預覽版本推送 ACL,現有的大寫或混合大小寫權限 ID 可能會無法匹配查詢時的識別。 授權使用者可能會收到比預期少的結果。

此遷移僅適用於直接透過 Push API 提交的 ACL。 內建索引器或已索引的知識來源不需要它。

若要重新索引受影響的 ACL 值:

  1. 識別在變更前推送權限 ID 的文件與區塊。 已經以小寫儲存的數值不需要這次的大小寫更新。
  2. 重新提交所有受影響紀錄的當前 ACL 值。 使用帶有文件金鑰及完整權限集合的 merge 動作 ,更新 ACL 且不替換內容。 合併會取代所提供的集合;包含所有現有的補助金,而不僅限於套寫變更的條目。
  3. 檢查每個記錄的索引回應,並重試失敗的更新。 持續進行直到更新所有受影響的紀錄。 部分遷移可能導致匹配不一致。
  4. 以應有權限與不應存取權限的使用者身份測試查詢。 診斷時請使用 升高唯讀 ,而非在一般使用者結果中暴露 ACL 值。

ACL 存取解析規則

原生權限過濾會將 userIds、groupIds 和 rbacScope 評估為替代授權,並以 OR 組合。 任一欄位的匹配可授予文件存取權;另一個欄位不匹配不會推翻該授權。 這種 any-grant 行為需要成功進行權限評估。

使用者可透過匹配的使用者或群組 ID,或對索引容器範圍的儲存 blob-read 授權取得存取權限。 儲存範圍檢查使用 x-ms-query-source-authorization 中被委派的使用者,而非操作憑證。 仍需取得操作授權。 有關詳細資訊及權限評估失敗行為,請參閱 查詢時 ACL 與 RBAC 強制執行。

特殊 ACL 值「none」

ACL 欄位,例如 userIds 和 groupIds,通常包含 Microsoft Entra 物件 ID(GUID),用來識別具有文件存取權的使用者與群組。 使用特殊字串值 none 或空陣列表示 ACL 欄位不授予存取權限。

ACL 值 意義
["none"] 沒有任何使用者能透過匹配此 ACL 類型來存取該文件
[](空陣列) 沒有任何使用者能透過匹配此 ACL 類型來存取該文件

設定 userIds 為 ["none"] 或為空陣列表示不會有 使用者根據使用者 ID 存取該文件。 他們仍可能透過匹配群組 ID 或 RBAC 元資料獲得存取權限。

存取控制範例

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

文件# 使用者 ID 群組ID RBAC 範圍 允許使用者名單 註
1 ["none"] [] 空的 沒有使用者能存取 ["none"]值和[]的行為完全相同
2 ["none"] [] scope/to/container1 擁有 container1 RBAC 權限的使用者 當其他權限欄位groupIds (或 rbacScope)授予存取權時,「無」的值不會阻擋存取。
3 ["none"] ["group1", "group2"] 空的 第1組或第2組成員
4 ["user1", "user2"] ["group1"] 空的 User1、user2,或 group1 的任何成員
5 ["user1", "user2"] [] 空的 使用者1 或 使用者2