使用 blob 索引器或知識來源來擷取 RBAC 範圍的元資料（預覽）

註

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

Important

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

Azure 儲存體 允許基於角色的方式存取 blob 儲存中的容器，像是 Storage Blob Data Reader 或 Storage Blob Data Contributor 這類角色可以判斷某人是否有內容存取權。 Azure AI 搜尋服務 支援在文件擷取的同時，還會收錄使用者權限（預覽），讓你能利用這些權限來控制搜尋結果的存取權。 如果使用者在 Azure 儲存體 中沒有特定目錄或檔案的權限，該使用者無法存取 Azure AI 搜尋結果中對應的文件，即使你個人在索引上有搜尋索引資料讀取者指派。

  • 在 2025-05-01-預覽版及更新版本中，RBAC 範圍的中繼資料可透過 Blob 索引子擷取。
  • 2025-11-01-preview 及更新版本在 Azure 儲存體 中對 Blob knowledge sources 提供相同的支援。

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

在查詢時，呼叫者的身份會透過參數包含在請求標頭 x-ms-query-source-authorization 中。 若使用者想看到搜尋結果，身份必須與文件上的權限元資料相符。

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

先決條件

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

  • Azure AI 搜尋服務 支援任何地區，但若需支援管理識別，必須使用可計費的層級（基本層級或以上）。 搜尋服務必須設定為基於角色的存取，且必須擁有受管理身份（系統或使用者）。

  • Azure 儲存體、標準效能 (一般用途 v2)、在經常性、非經常性和極非經常性存取層上，具有 RBAC 保護的容器或 Blob。

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

Limitations

Blob 儲存體 的配置

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

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

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

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

授權

在執行索引器時，你的搜尋服務身份必須擁有 Storage Blob Data Reader 權限。 欲了解更多資訊，請參閱 使用受控識別連接到 Azure 儲存體。

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

授權

為了執行索引器，發出 API 呼叫的用戶端必須擁有 Search Service Contributor 權限以建立物件，Search 索引資料貢獻者權限可執行資料匯入，Search 索引資料閱讀器查詢索引，詳見 Connect to Azure AI 搜尋服務 using roles。

設定知識來源

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

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

  • isADLSGen2 設為假，表示資料來源為 Azure Blob 儲存體。
  • ingestionPermissionOptions 指定 rbacScope。
# 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": false,
        "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": ["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}"
    }
}

在索引中建立權限欄位

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

建議的架構屬性 RBAC 範圍：

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

請注意，retrievable 是錯的。 你可以在開發過程中設定為 true 來驗證權限存在，但請記得在部署到生產環境前先設為 false，這樣安全主體身份就不會在結果中被看見。

JSON 架構範例：

{
  ...
  "fields": [
    ...
    { 
        "name": "RbacScope", 
        "type": "Edm.String", 
        "permissionFilter": "rbacScope", 
        "filterable": true, 
        "retrievable": false 
    }
  ],
  "permissionFilterOption": "enabled"
}

設定索引器

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

  • metadata_rbac_scope （Edm.String） - 容器 RBAC 範圍。

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

JSON 架構範例：

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

執行索引器

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

預設情況下，索引器會在你發佈到搜尋服務後立即執行，但如果索引器設定中設定為 disabled true，索引器會以停用狀態發布，讓你可以手動執行索引器。

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

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

刪除追蹤

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

參見

  • Last updated on