教學：索引 ADLS Gen2 權限的元資料，並以權限篩選結果查詢（預覽）

Note

Azure AI 搜尋服務可透過 Azure 入口網站、REST API 及 Azure SDK 取得。它同時也是 Foundry IQ 的基礎，這是一個管理式知識層，能將企業內容轉化為可重複使用、權限感知的知識庫，供 Microsoft Foundry 入口網站中的代理使用。

Important

標記（預覽）的功能、能力或屬性不受服務等級協議涵蓋，也不建議用於生產工作負載，且在正式上架前可能會有所變動或受限。 Azure AI 搜尋服務預覽條款適用於所有預覽功能，無論是獨立功能還是正式推出功能的一部分。

本教學示範Azure Data Lake Storage（ADLS）Gen2 權限元資料擷取（預覽），其中Azure AI 搜尋服務索引器會在搜尋索引中加入存取控制清單（ACL）及基於角色的存取控制範圍（RBAC）。

它也會教你如何結構化一個尊重使用者存取權限的查詢。查詢結果成功後，確認索引過程中發生的權限轉移。

欲了解更多關於索引 ACL 的資訊，請參閱使用 ADLS Gen2 索引器來擷取權限元資料。

在這個教學中，你會學到如何：

在資料來源 adlsgen2 上設定 RBAC 範圍與 ACL
建立包含權限資訊欄位的 Azure AI 搜尋服務索引
建立並執行索引器，從資料來源將權限資訊匯入索引
搜尋你剛建立的索引

使用 REST 用戶端完成此教學及最新的預覽版 REST API。目前 Azure 入口網站不支援 ACL 索引。

先決條件

一個有有效訂閱的 Azure 帳號。免費註冊帳號。
Microsoft Entra ID 認證與授權。服務和應用程式必須在同一個租戶中。每個已認證的連線皆使用角色指派。使用者與群組必須在同一租戶中。你應該有使用者和群組可以合作。建立租用戶和安全性主體不在本教學課程範圍內。
ADLS Gen2 採用階層式命名空間。
檔案位於階層式資料夾結構中。本教學課程假設 ADLS Gen2 示範了檔案 /Oregon/Portland/Data.txt 的資料夾結構。這個教學會引導你完成資料夾和檔案的 ACL 指派，讓你能順利完成這個練習。
Azure AI 搜尋服務，任何區域。管理身份支援則需基本層級或以上。
Visual Studio Code搭配 REST Client 擴充功能。

準備樣本資料

將州立公園樣本資料上傳到ADLS Gen2的容器中。容器名稱應該是「parks」，並且應該有兩個資料夾：「Oregon」和「Washington」。

檢查搜尋服務設定

你的搜尋服務必須設定為 Microsoft Entra ID 認證與授權。請檢視這份清單，確保你已經做好準備。

取得個人身份憑證用於本地測試

本教學假設一個 REST 用戶端在本地系統上，透過公共網路連線連接到 Azure。

請依照以下步驟取得個人身份令牌，並設定 Visual Studio Code，以便與 Azure 資源本地連線。

在 ADLS Gen2 中設定權限

最佳做法是使用 Group 集合，而非直接指派 User 集合。

授予搜尋服務識別對容器的讀取權限。索引器會以搜索服務身分連接到 Azure 儲存體。搜尋服務必須擁有 儲存區資料讀取器（Storage Blob Data Reader） 權限才能取得資料。
在檔案階層中授予每個群組或使用者權限。在檔案階層中，識別所有分配給容器、目錄和檔案的GroupUser集合。
你可以用 Azure 入口網站來管理 ACL。在儲存瀏覽器中，選擇俄勒岡目錄，然後從右鍵選單中選擇 管理 ACL 。
為使用者和群組新增安全原則。
移除擁有群組、擁有使用者和其他項目的現有主體。這些原則在預覽時不支援 ACL 索引。

建立權限元資料的搜尋索引

建立包含內容與權限元資料欄位的索引。

務必使用 latest preview REST API或提供同等功能的預覽 Azure SDK 套件。權限篩選屬性僅在預覽 API 中提供。

為了示範，權限欄位已 retrievable 啟用，讓你可以從索引中查看數值。在生產環境中，你應該關閉 retrievable 以避免敏感資訊外洩。

{
  "name" : "my-adlsgen2-acl-index",
  "fields": [
    {
      "name": "name", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true
    },
    {
      "name": "description", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true    
    },
    {
      "name": "location", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true
    },
    {
      "name": "state", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true
    },
    {
      "name": "AzureSearch_DocumentKey", "type": "Edm.String",
      "searchable": true, "filterable": false, "retrievable": true, "stored": true,
      "key": true
    },
    { 
      "name": "UserIds", "type": "Collection(Edm.String)", 
      "permissionFilter": "userIds", 
      "searchable": true, "filterable": false, "retrievable": true
    },
    { 
      "name": "GroupIds", "type": "Collection(Edm.String)", 
      "permissionFilter": "groupIds", 
      "searchable": true, "filterable": false, "retrievable": true
    },
    { 
      "name": "RbacScope", "type": "Edm.String", 
      "permissionFilter": "rbacScope", 
      "searchable": true, "filterable": false, "retrievable": true
    }
  ],
  "permissionFilterOption": "enabled"
}

建立資料來源

修改資料來源設定，指定索引器權限擷取及你想要索引的權限元資料類型。

資料來源需要 indexerPermissionOptions。

在本教學中，請使用系統指派的管理身份來進行認證連線。

{
    "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": "parks",
    "query": null
    }
}

建立並執行索引器

權限擷取的索引子組態主要是定義從fieldMappings而來的。

{
  "name" : "my-adlsgen2-acl-indexer",
  "dataSourceName" : "my-adlsgen2-acl-datasource",
  "targetIndexName" : "my-adlsgen2-acl-index",
  "parameters": {
    "batchSize": null,
    "maxFailedItems": 0,
    "maxFailedItemsPerBatch": 0,
    "configuration": {
      "dataToExtract": "contentAndMetadata",
      "parsingMode": "delimitedText",
      "firstLineContainsHeaders": true,
      "delimitedTextDelimiter": ",",
      "delimitedTextHeaders": ""
      },
  "fieldMappings": [
    { "sourceFieldName": "metadata_user_ids", "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids", "targetFieldName": "GroupIds" },
    { "sourceFieldName": "metadata_rbac_scope", "targetFieldName": "RbacScope" }
    ]
  }
}

建立索引器並立即執行後，檔案內容及權限元資料會被索引到索引中。

執行查詢以檢查結果

現在文件已載入，你可以透過使用 Documents - Search Post（REST）對它們發出查詢。

URI 被擴充為包含查詢輸入，該輸入由操作 /docs/search 符指定。查詢標記會透過請求標頭傳遞。如需詳細資訊，請參閱查詢時間 ACL 和 RBAC 強制執行。

POST  {{endpoint}}/indexes/stateparks/docs/search?api-version=2026-08-01-preview
Authorization: Bearer {{search-token}}
x-ms-query-source-authorization: {{search-token}}
Content-Type: application/json

{
    "search": "*",
    "select": "name,description,location,GroupIds",
    "orderby": "name asc"
}

https://github.com/Azure-Samples/azure-search-rest-samples/tree/main/acl

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-09-17