Note
Foundry IQ(Azure AI 搜尋服務)提供直接的索引與查詢 API,並搭配高階知識來源與知識庫 API 用於受控檢索。 使用 Azure 入口網站、REST API 或 Azure SDK 來設定這些功能,或將代理連線到 Microsoft Foundry 入口網站 中的知識庫。
本教學示範 Azure Data Lake Storage (ADLS) Gen2 權限元資料擷取,其中 Foundry IQ(Azure AI 搜尋服務)索引器會將存取控制清單(ACL)及基於角色的存取控制(RBAC)範圍新增至搜尋索引。 此功能已正式在 REST API 2026-10-01中使用。
它也會示範如何以允許和拒絕的使用者身分進行查詢,以及在索引後驗證權限變更。
欲了解更多關於索引 ACL 的資訊,請參閱 使用 ADLS Gen2 索引器來擷取權限元資料。
在這個教學中,你會學到如何:
- 在資料來源
adlsgen2上設定 RBAC 範圍與 ACL - 建立包含權限資訊欄位的 Foundry IQ 索引
- 建立並執行索引器,從資料來源將權限資訊匯入索引
- 搜尋你剛建立的索引
使用 REST 用戶端與 REST API 2026-10-01。 目前 Azure 入口網站不支援 ACL 索引。
先決條件
一個有有效訂閱的 Azure 帳號。 免費建立帳戶。
Microsoft Entra ID 認證與授權。 服務和應用程式必須在同一個租戶中。 每個已認證的連線皆使用角色指派。 使用者與群組必須在同一租戶中。 你應該有使用者和群組可以合作。 建立租用戶和安全性主體不在本教學課程範圍內。
帶有階層命名空間的 ADLS Gen2。
檔案位於階層式資料夾結構中。 本教學課程假設 ADLS Gen2 示範了檔案
/Oregon/Portland/Data.txt的資料夾結構。 這個教學會引導你完成資料夾和檔案的 ACL 指派,讓你能順利完成這個練習。Foundry IQ,任何區域。 管理身份支援則需基本層級或以上。
準備樣本資料
在 ADLS Gen2 中建立一個名為 parks 的容器。 上傳兩個內容不同的純文字檔案:
Oregon/Portland/Data.txtWashington/Seattle/Data.txt
本教學使用預設的解析模式,為每個檔案建立一份搜尋文件。 索引儲存檔案名稱及擷取的文字。 這些 .txt 檔案不需要專門的 text 解析模式,因為在使用文件層級權限時,不支援這種解析模式。 請參閱 支援權限匯入的解析與內容擷取。
檢查 Foundry IQ 服務設定
為您的 Foundry IQ 服務設定 Microsoft Entra ID 驗證與授權。 請檢視這份檢查清單,確保你做好準備。
取得個人身份憑證用於本地測試
本教學假設一個 REST 用戶端在本地系統上,透過公共網路連線連接到 Azure。
請依照下列步驟取得個人識別權杖,並設定 Visual Studio Code,以便從本機連線到您的 Azure 資源。
在 ADLS Gen2 中設定權限
最佳做法是使用 Group 集合 ,而非直接指派 User 集合。
授予 Foundry IQ 服務識別對容器的讀取權限。 索引器會以 Foundry IQ 服務身分連線至 Azure 儲存體。 Foundry IQ 服務必須具備 Storage Blob Data Reader 權限才能擷取資料。
在檔案階層中授予每個群組或使用者權限。 在檔案階層中,識別所有分配給容器、目錄和檔案的
GroupUser集合。你可以用 Azure 入口網站來管理 ACL。 在儲存瀏覽器中,選擇俄勒岡目錄,然後從右鍵選單中選擇 管理 ACL 。
為使用者和群組新增安全原則。
使用命名使用者與命名群組作為測試授權。 擁有使用者、擁有群組及其他項目不支援 ACL 索引;不要依賴它們作為測試身分。
在建立索引前,請檢查來源 ACL 是否有 不受支援的隱含項目 blocklists,並以受支援的 allowlists 進行修正。
建立權限元資料的搜尋索引
請使用 REST API 2026-10-01 來執行索引、資料來源及索引器請求。
為了示範,權限欄位已 retrievable 啟用,讓你可以從索引中查看數值。 在生產環境中,你應該關閉 retrievable 以避免敏感資訊外洩。
{
"name" : "my-adlsgen2-acl-index",
"fields": [
{
"name": "metadata_storage_path", "type": "Edm.String",
"searchable": false, "filterable": true, "retrievable": true
},
{
"name": "name", "type": "Edm.String",
"searchable": true, "filterable": false, "retrievable": true
},
{
"name": "content", "type": "Edm.String",
"searchable": true, "retrievable": true, "filterable": false
},
{
"name": "id", "type": "Edm.String",
"searchable": true, "filterable": false, "retrievable": true, "stored": true,
"key": true
},
{
"name": "UserIds", "type": "Collection(Edm.String)",
"permissionFilter": "userIds",
"searchable": false, "filterable": true, "retrievable": true
},
{
"name": "GroupIds", "type": "Collection(Edm.String)",
"permissionFilter": "groupIds",
"searchable": false, "filterable": true, "retrievable": true
},
{
"name": "RbacScope", "type": "Edm.String",
"permissionFilter": "rbacScope",
"searchable": false, "filterable": true, "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定義頂層。
metadata_storage_path 即使您只匯入 RBAC 範圍,仍是必需的。 不要編碼這個欄位。
{
"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": "default",
"refreshAllAcls": true
}
},
"fieldMappings": [
{ "sourceFieldName": "metadata_storage_path", "targetFieldName": "id", "mappingFunction": { "name": "base64Encode" } },
{ "sourceFieldName": "metadata_storage_name", "targetFieldName": "name" },
{ "sourceFieldName": "metadata_storage_path", "targetFieldName": "metadata_storage_path" },
{ "sourceFieldName": "metadata_user_ids", "targetFieldName": "UserIds" },
{ "sourceFieldName": "metadata_group_ids", "targetFieldName": "GroupIds" },
{ "sourceFieldName": "metadata_rbac_scope", "targetFieldName": "RbacScope" }
]
}
建立索引器會開始其第一次執行。 查詢前,請使用 「取得索引器狀態 」確認執行是否成功完成。 檢查錯誤與警告,並確認兩個檔案均已被索引。
如果您計畫使用自動 ACL 重新整理來驗證權限變更,請 設定索引器排程。
執行查詢以檢查結果
現在文件已載入,你可以透過使用 Documents - Search Post(REST)對它們發出查詢。
URI 被擴充為包含查詢輸入,該輸入由操作 /docs/search 符指定。 查詢標記會透過請求標頭傳遞。 如需詳細資訊,請參閱查詢時間 ACL 和 RBAC 強制執行。
POST {{endpoint}}/indexes/my-adlsgen2-acl-index/docs/search?api-version=2026-10-01
Authorization: Bearer {{search-token}}
x-ms-query-source-authorization: {{query-user-token}}
Content-Type: application/json
{
"search": "*",
"select": "name,content,metadata_storage_path,GroupIds"
}
Authorization 標頭授權您的應用程式查詢 Search。
query-user-token 是被委派使用者用於權限評估的權杖;它可以代表另一種身份認同。
驗證權限變更
- 以具名使用者身分進行查詢,擁有檔案讀取權,並可透過祖先目錄執行/遍歷存取。 確認預期文件是否出現。
- 以沒有相符的使用者或群組 ACL,且沒有受支援的容器 RBAC 授權的使用者身分查詢。 確認該文件不存在。
- 移除第一位使用者的 ACL 授權,但不更改檔案內容。 請確保沒有任何其他 ACL 或支援的 RBAC 授權授權該使用者。 要求重新同步權限並執行索引器,或等待適用的自動 ACL 重新整理。
- 完成後,重複兩個查詢。 被撤銷的使用者不得再取回該文件,而另一位明確授權的使用者仍可。
- 重複執行此步驟,並進行具名群組的授權或移除授權,以及祖先目錄周遊權限變更。 分別測試 RBAC 授權或移除,並考量到 Storage 傳播和查詢授權快取。
對於分塊管線,也請驗證每個受影響父節點的代表性區塊。 部分失敗後,檢查錯誤與警告並重試,然後再將所有結果視為已完成調和。 使用 正規投影對應;僅有一個受保護的父資料,無法保護缺少權限中繼資料的區塊。