使用 ADLS Gen2 索引器來擷取權限元資料，並根據使用者存取權限篩選搜尋結果（預覽）

Azure Data Lake Storage (ADLS) Gen2 透過存取控制清單 (ACL) 和角色型存取控制 (Azure RBAC)，支援每個使用者對目錄和檔案的存取。 基於屬性的存取控制（Azure ABAC）不被支援。

Azure AI 搜尋服務 可以透過預覽 REST API 將這些權限元資料（預覽）與文件內容一併收回。 無法存取目錄或儲存檔案的使用者，在搜尋結果中看不到對應的文件。 這是Azure AI 搜尋服務中用於文件層級存取控制策略之一。

本文說明如何配置 ADLS Gen2 索引器或 ADLS Gen2 blob 知識來源，自動將權限元資料 拉 入搜尋索引。 此內容補充從 ADLS Gen2 編製資料索引和為 ADLS Gen2 建立 Blob 知識來源，並提供權限擷取專屬資訊。 若要手動 推送 權限元資料，請參考 使用 push API 的索引文件 ACL。

先決條件

• Microsoft Entra ID 認證與授權。 服務和應用程式必須在同一個租戶中。 只要所有租用戶都使用 Microsoft Entra ID，使用者就可以位於不同租用戶中。 每個已認證的連線皆使用角色指派。

• 任何區域中採計費層的 Azure AI 搜尋服務 (Basic 或更高層級)。 搜尋服務必須 啟用基於角色的存取 ，並設定 系統或使用者指定的管理身份。

• ADLS Gen2 的 blob 以階層命名空間呈現，使用者權限可透過 ACL 或角色授予。

• 索引器權限擷取的 REST API 版本為 2025-05-01-preview 或更新版本。 REST API 版本為 2025-11-01-preview 或更新版本，以支援知識來源。 使用最新的預覽版 REST API 或支援 權限篩選器的預覽 SDK 套件。

限制

• Azure 入口網站不支援這個功能。

• ADLS Gen2 對角色分配及 ACL 條目有限制 。

• 預覽階段不支援owning users、owning groups 和 Other（all）ACL 身份類別。 請改用named users和named groups進行分配。

• 以下索引器功能不支援來自 ADLS Gen2 的索引文件的權限繼承。 如果你在技能組或索引器中使用這些功能，文件層級的權限不會包含在索引內容中。

  • 自訂的 Web API 功能

  • 知識存放區，包括代理式檢索中影像服務（預覽）所需的資產存放區。 因此，對於內嵌 ACL 或 RBAC 範圍的知識來源，並不支援映像服務。

  • 索引器增益快取

  • 除錯工作階段

對許可模式的支持

本節比較 ADLS Gen2 與 Azure AI 搜尋服務 之間的文件層級存取控制功能。 它說明了 AI 搜尋支援或映射哪些 Azure Data Lake Storage（ADLS）Gen2 存取控制機制。 這有助於你了解文件層級的權限是如何被強制執行的。

在查詢時，Azure AI 搜尋服務 會先評估容器層級的 RBAC，然後檢查文件層級的 ACL 條目。 只要有任何機制允許，存取權就會被授予。

關於 ACL 階層式權限

索引器與知識來源可依照 ADLS Gen2 階層式存取評估流程，從指定的容器及所有導向每個檔案的目錄中取得 ACL 指派。 每個檔案的最終有效存取清單會被計算出來，並將不同的存取類別索引到對應的索引欄位中。

例如，在 ADLS Gen2 中，常見的權限情境 是檔案路徑 /Oregon/Portland/Data.txt。

索引器或知識來源會從每個容器和目錄收集 ACL。 接著它會判定較低層級的有效存取權限，並持續進行直到解決每個檔案的權限。

/ assigned access vs Oregon/ assigned access
  => Oregon/ effective access vs Portland/ assigned access
    => Portland/ effective access vs Data.txt assigned access
      => Data.txt effective access

設定 ADLS Gen2

索引器或知識來源於符合以下條件時可取得儲存帳戶上的存取控制清單（ACL）。 欲了解更多關於前十字韌帶（ACL）指派的資訊，請參見ADLS Gen2 ACL指派。

授權

索引時，你的搜尋服務身份必須擁有 Storage Blob Data Reader 權限。

如果你在本地測試，也應該有一個 Storage Blob Data Reader 的角色指派。 欲了解更多資訊，請參閱 使用受控識別連接到 Azure 儲存體。

根容器權限：

1. 在根容器Group中指派所有User與/安全主體，並賦予 Read 和 Execute 權限。

2. 確保 Read 和 Execute 都被加入為「預設權限」，這樣它們才能自動傳播到新建立的檔案和目錄。

將權限從檔案階層向下傳遞

雖然新的目錄和檔案會繼承權限，但現有的目錄和檔案不會自動繼承這些指派。

使用 ADLS Gen2 工具以遞迴方式套用 ACL，以便在現有內容上傳播指派。 此工具會將根容器的 ACL 指派傳播到所有底層目錄與檔案。

移除多餘權限

在遞迴套用 ACL 後，檢視每個目錄和檔案的權限。

移除任何不應該存取特定目錄或檔案的Group或User集合。 例如，將User2從資料夾Portland/中移除，並從資料夾Idaho的指派中移除Group2和User2，依此類推。

ACL 指派結構範例

以下是 ADLS Gen2 文件中 虛構目錄階層 的 ACL 指派結構示意圖。

隨時間推移持續更新 ACL 指派

隨著時間的推移，當新增或修改任何新的 ACL 分配時，重複上述步驟以確保正確的傳播和權限的對齊。 ADLS Gen2 的權限更新會在你使用索引器或知識來源重新填入內容時，在搜尋索引中更新。

設定 Azure AI 搜尋服務

請記得，搜尋服務必須具備：

• 啟用基於角色的存取
• 已設定的管理身份

授權

為了索引，發出 API 呼叫的用戶端必須擁有 Search Service Contributor 權限來建立物件，Search Index Data Contributor 權限以執行資料匯入，以及 Search Index Data Reader 權限以查詢索引。

如果你是在本地測試，角色分配應該是一樣的。 欲了解更多資訊，請參閱 使用角色連接至 Azure AI 搜尋服務。

設定知識來源

如果你使用知識來源，知識來源中的定義會用來產生完整的索引流程（索引器、資料來源和索引）。 ACL 指派會被偵測並自動包含在產生的索引中。 如果你想在索引內容中取得權限繼承，就不需要修改任何產生的物件。

關於使此設定適合此情境的關鍵點：

• isADLSGen2 設定為 true，符合此情境下資料來源的需求。
• ingestionPermissionOptions 指定使用者與群組 ID。

# Create / Update Azure Blob Knowledge Source
###
PUT {{url}}/knowledgesources/azure-blob-ks?api-version=2026-08-01-preview
api-key: {{key}}
Content-Type: application/json
 
{
    "name": "azure-blob-ks",
    "kind": "azureBlob",
    "description": "A sample azure blob knowledge source",
    "azureBlobParameters": {
        "connectionString": "{{blob-connection-string}}",
        "containerName": "blobcontainer",
        "folderPath": null,
        "isADLSGen2": true,
        "ingestionParameters": {
            "identity": null,
            "embeddingModel": {
                "kind": "azureOpenAI",
                "azureOpenAIParameters": {
                    "deploymentId": "text-embedding-3-large",
                    "modelName": "text-embedding-3-large",
                    "resourceUri": "{{aoai-endpoint}}",
                    "apiKey": "{{aoai-key}}"
                }
            },
            "chatCompletionModel": null,
            "disableImageVerbalization": true,
            "ingestionSchedule": null,
             "ingestionPermissionOptions": [
                "userIds","groupIds"
                           ],
            "contentExtractionMode": "minimal",
            "aiServices": {
                "uri": "{{ai-endpoint}}",
                "apiKey": "{{ai-key}}"
            }
        }
    }
}
###

配置基於索引器的索引

如果你正在使用索引器，請設定索引器、資料來源和索引，以便從 ADLS Gen2 Blob 抽取權限元資料。

建立資料來源

本節補充從 ADLS Gen2 編製資料索引，並提供將權限與文件內容一起擷取到 Azure AI 搜尋服務索引的專屬資訊。

• 資料來源類型必須是 adlsgen2。

• 資料來源必須具有 indexerPermissionOptionsuserIds、 groupIds和/或 rbacScope。

  • 對於 rbacScope，請設定 連線字串，並採用管理身份格式。

  • 對於使用 使用者指派的管理身份的連線字串，你也必須指定該 identity 屬性。

帶有系統管理身份的 JSON 範例：

{
    "name" : "my-adlsgen2-acl-datasource",
    "type": "adlsgen2",
    "indexerPermissionOptions": ["userIds", "groupIds", "rbacScope"],
    "credentials": {
    "connectionString": "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;"
    },
    "container": {
    "name": "<your container name>",
    "query": "<optional-virtual-directory-name>"
    }
}

JSON 架構範例，連接字串 中包含使用者管理身份：

{
    "name" : "my-adlsgen2-acl-datasource",
    "type": "adlsgen2",
    "indexerPermissionOptions": ["userIds", "groupIds", "rbacScope"],
    "credentials": {
    "connectionString": "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;"
    },
    "container": {
    "name": "<your container name>",
    "query": "<optional-virtual-directory-name>"
    },
    "identity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
    }
}

在索引中建立權限欄位

在 Azure AI 搜尋服務 中，請確保你的索引包含權限元資料的欄位定義。 當在資料來源定義中指定 indexerPermissionOptions 時，權限元資料可以被索引。

建議的 ACL（UserIds、GroupIds）架構屬性和 RBAC 範圍：

• 使用者識別碼（ID）欄位，並附有 userIds 權限篩選器值。
• 群組 ID 欄位，並帶有 groupIds permissionFilter 值。
• 具有 rbacScope permissionFilter 值的 RBAC 範圍欄位。
• 在查詢時啟用篩選的屬性 permissionFilterOption 。
• 使用字串欄位作為權限元資料
• 所有欄位都設 filterable 為 true。

請注意，retrievable 是錯的。 你可以在開發過程中設定為 true，以確認權限是否存在，但請記得在部署到生產環境前先將 back 設為 false。

JSON 架構範例：

{
  ...
  "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 }
  ],
  "permissionFilterOption": "enabled"
}

設定索引器

索引器內的欄位映射會設定索引中欄位的資料路徑。 目標欄位與目的地欄位若依名稱或資料型態不同，則需要明確的欄位映射。 ADLS Gen2 中，若更改欄位名稱，以下中繼資料欄位可能需要欄位映射：

• metadata_user_ids （Collection(Edm.String)） - ACL 使用者 ID 清單。
• metadata_group_ids （Collection(Edm.String)） - ACL 群組 ID 列表。
• metadata_rbac_scope （Edm.String） - 容器 RBAC 範圍。

在索引器中指定 fieldMappings 在索引時將權限元資料路由到目標欄位。

JSON 架構範例：

{
  ...
  "fieldMappings": [
    { "sourceFieldName": "metadata_user_ids", "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids", "targetFieldName": "GroupIds" },
    { "sourceFieldName": "metadata_rbac_scope", "targetFieldName": "RbacScope" }
  ]
}

建議與最佳實務

• 在建立任何資料夾前，請仔細規劃 ADLS Gen2 的資料夾結構。

• 將身份組織成群組，並盡可能使用群組，而非直接授權個別使用者存取權限。 持續新增個別使用者而非套用群組，會增加需要追蹤與評估的存取控制條目數量。 未遵循此最佳實務可能導致由於安全元資料的變動，需要對索引更頻繁地進行更新，從而導致更新過程的延遲和效率降低。

同步索引內容與來源內容之間的權限

在索引器啟用 ACL 或 RBAC 增強功能，僅在兩種情況下會自動運作：

• 第一次完整索引器執行/資料爬取： 當下所有文件存在的所有權限元資料都會被擷取。

• 啟用 ACL/RBAC 支援後新增的全新文件： 其 ACL/RBAC 資訊與內容一同被擷取。

如果你更改文件權限，例如將使用者加入 ACL 或更新角色指派，除非你再次告訴索引器爬取文件的權限元資料，否則該變更不會出現在搜尋索引中。

根據更換的物品數量，請選擇以下機制之一：

Resetdocs（預覽）API 範例：

POST https://{service}.search.windows.net/indexers/{indexer}/resetdocs?api-version=2026-08-01-preview
{ 
  "documentKeys": [ 
    "1001", 
    "4452" 
  ]
}

Resync（預覽）API 範例：

POST https://{service}.search.windows.net/indexers/{indexer}/resync?api-version=2026-08-01-preview
{ 
  "options": [ 
    "permissions" 
  ] 
} 

刪除追蹤

要有效管理斑點刪除，請確保索引器首次運行前已啟用 刪除追蹤 功能。 此功能讓系統能偵測來源中已刪除的斑點，並將其從索引中移除。

相關內容

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