使用 blob 索引器或知識來源來載入 RBAC 範圍的元資料

註

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

Foundry IQ(Azure AI 搜尋服務)會從 Azure Blob 儲存體 擷取容器資源範圍資訊,並根據委派使用者所支援的 Blob-read 授權篩選查詢結果。 容器 RBAC 範圍擷取與查詢時篩選功能一般可在 REST API 2026-10-01 中提供。

使用 Blob 索引器 或 Blob 知識來源。 標準 Blob 擷取不會評估 ADLS 檔案或目錄 ACL。 對於這些權限,請使用 ADLS Gen2 設定。

RBAC 的範圍在容器層級設定,並透過權限繼承應用於所有的 blob(文件)。 RBAC 範圍會在索引過程中以權限元資料形式擷取。 你可以使用推播 API 手動上傳和索引內容及權限的元資料(參見 使用推播 REST API 進行權限索引),或者使用索引器或知識來源來自動化資料輸入。 本文聚焦於索引自動化。

儲存的範圍用來識別容器;它不是一份複製的職務分配或主要角色清單。 在查詢期間,x-ms-query-source-authorization 會攜帶委派使用者的權杖。 Foundry IQ 會根據已儲存的範圍評估該使用者的授權,並與應用程式的 Search 資料平面授權分開進行評估。

本文聚焦於建立在以下基礎上的索引自動化方法:

先決條件

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

  • Foundry IQ,不限任何區域,但你必須使用可計費的層級(基本版以上)才能支援受控識別身分。 Foundry IQ 服務必須設定為角色型存取,且必須具有受控識別(系統或使用者)。

  • Azure 儲存體,標準效能(通用 v2),適用於熱、冷、冷存取層級,並支援容器 RBAC 存取。

  • 你應該了解索引器和知識來源的運作方式,以及如何建立索引。 本文說明了資料來源與索引器的設定,但未提供建立索引的步驟。 欲了解更多關於權限篩選索引的資訊,請參閱 「建立帶有權限篩選欄位的索引」。

Limitations

Blob 儲存體 的配置

確認你的 blob 容器是否使用基於角色的存取。

  1. 登入 Azure 入口網站,找到你的儲存帳號。

  2. 展開 容器 ,選擇包含你想要索引的 blob 的容器。

  3. 選擇 存取控制 (IAM) 以檢查角色分配。 使用 Storage Blob Data Reader 或 Storage Blob Data Contributor 的使用者與群組,在容器索引完成後,可存取索引中的搜尋文件。

授權

若要執行索引器,您的 Foundry IQ 服務識別必須具備 Storage Blob Data Reader 權限。 欲了解更多資訊,請參閱 使用受控識別連接到 Azure 儲存體。

設定 Foundry IQ

請記得 Foundry IQ 服務必須具備:

授權

若要執行索引器,發出 API 呼叫的客戶端必須具有 搜尋服務參與者 許可權,才能建立對象、執行數據匯入的 搜尋索引數據參與者 許可權,以及 搜尋索引數據讀取器 來查詢索引。 請參閱「 使用角色連接至 Foundry IQ」。

設定知識來源

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

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

  • isADLSGen2設定為 false,表示資料來源為 Azure Blob 儲存體。
  • ingestionPermissionOptions 指定 rbacScope。
# Create / Update Azure Blob Knowledge Source
###
PUT {{url}}/knowledgesources/azure-blob-ks?api-version=2026-10-01
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": false,
        "ingestionParameters": {
            "identity": null,
            "embeddingModel": {
                "kind": "azureOpenAI",
                "azureOpenAIParameters": {
                    "deploymentId": "{{embedding-deployment}}",
                    "modelName": "{{embedding-model}}",
                    "resourceUri": "{{aoai-endpoint}}",
                    "apiKey": "{{aoai-key}}"
                }
            },
            "chatCompletionModel": null,
            "disableImageVerbalization": true,
            "ingestionSchedule": null,
            "ingestionPermissionOptions": ["rbacScope"],
            "contentExtractionMode": "minimal",
            "aiServices": {
                "uri": "{{ai-endpoint}}",
                "apiKey": "{{ai-key}}"
            }
        }
    }
}

參考:建立或更新知識來源 (REST API)

配置基於索引器的索引

如果你正在使用索引器,請設定索引器、資料來源和索引,以從 blobs 中提取權限元資料。

建立資料來源

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

  • 在索引器設定中使用預設的解析模式。

  • 資料來源必須具備 indexerPermissionOptions 和 rbacScope。

JSON 範例,包含系統管理身份及 indexerPermissionOptions:

{
    "name" : "my-blob-datasource",
    "type": "azureblob",
    "indexerPermissionOptions": ["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-query-used-for-selecting-specific-blobs>"
    }
}

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

{
    "name" : "my-blob-datasource",
    "type": "azureblob",
    "indexerPermissionOptions": ["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-query-used-for-selecting-specific-blobs>"
    },
    "identity": {
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
    }
}

在索引中建立權限欄位

在 Foundry IQ 中,請確保您的索引包含權限元資料的欄位定義。 當在資料來源定義中指定 indexerPermissionOptions 時,權限元資料可以被索引。

對於直接標準的 Blob RBAC 索引器,你不需要 metadata_storage_path 計算容器範圍。 此要求與 ADLS Gen2 權限擷取不同,後者即使僅用於 RBAC 擷取,也必須有該欄位。 生成的 Blob 知識來源管線仍包含其結構和來源上下文的來源路徑。 請參閱 來源的元資料矩陣。

請為 RBAC 範圍使用下列屬性:

  • 具有 rbacScope permissionFilter 值的 RBAC 範圍欄位。
  • 在查詢時啟用篩選的屬性 permissionFilterOption 。
  • 使用字串欄位作為權限元資料
  • 所有欄位都設 filterable 為 true。

請注意,retrievable 是錯的。 您可以在開發期間將其設為 true,以驗證權限存在,但請記得在部署到生產環境前先將其設回 false,這樣安全主體身份才不會在結果中顯示。

JSON 架構範例:

{
  "name": "my-blob-rbac-index",
  "fields": [
    { "name": "id", "type": "Edm.String", "key": true },
    { 
        "name": "RbacScope", 
        "type": "Edm.String", 
        "permissionFilter": "rbacScope", 
        "filterable": true, 
        "retrievable": false 
    }
  ],
  "permissionFilterOption": "enabled"
}

設定索引器

索引器內的欄位映射會設定索引中欄位的資料路徑。 目標欄位與目的地欄位若依名稱或資料型態不同,則需要明確的欄位映射。 以下 Azure Blob 儲存體 中的元資料欄位,若你改變欄位名稱,可能需要欄位映射:

  • metadata_rbac_scope (Edm.String) - 容器 RBAC 範圍。

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

使用此連接器衍生 metadata_rbac_scope 版本,用於此支援的匯入流程,並檢視其容器範圍如何與文件的最終鍵及內容保持關聯。 不要將來自普通內容或自訂元資料的同名值視為授予存取權限的依據。 permissionFilter 註解說明儲存值的評估方式;它並非文件所有權檢查。

檢視誰可以撰寫原始內容,以及誰可以變更鍵、對應和權限值。 遵循 Blob 身份與權限檢查清單,包括隱含的鍵對應及任何投影子項。 保留此流程所需的預設解析模式;JSON 解析範例並未建立原生 Blob 權限匯入的支援。

JSON 架構範例:

{
  "fieldMappings": [
    { "sourceFieldName": "metadata_rbac_scope", "targetFieldName": "RbacScope" }
  ]
}

執行索引器

在你的索引器、資料來源和索引都設定好後,啟動索引器啟動這個流程。 如果設定或權限有問題,這些問題就會在這個步驟中浮現。

預設情況下,索引器會在您發佈至 Foundry IQ 服務後立即執行,但若索引器設定中包含 disabled set 為 true,索引器會以停用狀態發佈,讓您能手動執行索引器。

我們建議從Azure入口網站執行索引器,以便監控狀態和訊息。

假設沒有錯誤,索引已經填滿,你可以繼續查詢 和測試。

讓範圍和授權保持最新狀態

儲存角色指派變更影響的是查詢時的授權,而非索引容器資源 ID。 允許儲存授權傳播及在授權或移除後適用的快取。 重新索引或 ACL 重新同步不會強制授權快取重新整理。 refreshAllAcls 適用於 ADLS ACL 匯入,而非標準 Blob RBAC 匯入。

如果你使用索引投影,請直接將 /document/metadata_rbac_scope 對應到每個受保護區塊中由 rbacScope 註解的欄位。 使用知識來源時保留產生的來源路徑對應。 修正結構或對應不會填入現有記錄;修正管線後重新處理受影響的內容。

先測試允許的使用者與未支援容器授權的使用者,然後將授權移除與索引變更分開測試。 在解讀意外結果前,請先檢查是否有其他支援的授權。 有關共用新鮮度與清理的考量,請參閱「同步權限」。

刪除追蹤

若要有效管理 Blob 刪除,請確定您已在索引子首次執行前啟用刪除追蹤。 此功能讓系統能偵測來源中刪除的 blob,並從索引中刪除相應內容。

參見