你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

使用 Blob 索引器或知识源引入 RBAC 范围元数据（预览版）

注意

Azure AI 搜索可通过Azure门户、REST API 和Azure SDK获取。它也是 Foundry IQ 的基础；Foundry IQ 是一个托管式知识层，可将企业内容转化为供 Microsoft Foundry 门户中的智能体使用的、可复用且具备权限感知能力的知识库。

Important

标记为“预览”的特性、功能或属性不受服务级别协议 (SLA) 保障，不建议用于生产工作负载，并且在正式发布之前可能会更改或受到限制。 Azure AI 搜索预览条款适用于所有预览功能，无论是独立功能还是正式版功能的一部分。

Azure 存储允许对 blob 存储中的容器进行基于角色的访问，其中角色（如 Storage Blob 数据读取者或 Storage Blob 数据参与者确定某人是否有权访问内容。 Azure AI 搜索支持引入用户权限（预览版）以及文档引入，以便你可以使用这些权限来控制对搜索结果的访问。如果用户对 Azure 存储中的特定目录或文件没有权限，即使你个人在索引上拥有 Search Index Data Reader 的分配，用户仍无法访问 Azure AI 搜索结果中的相应文档。

从 2025-05-01-preview 版本及更高版本开始，可以使用 Blob 索引器来引入 RBAC 范围元数据。
2025-11-01-preview 及更高版本为 Azure 存储中的 Blob 知识源提供同等支持。

RBAC 作用域在容器级别设置，并通过权限继承流向所有 Blob（文档）。在索引编制过程中，RBAC 范围被捕获为权限元数据。可以使用推送 API 手动上传和索引内容和权限元数据（请参阅使用推送 REST API 的索引权限），也可以使用索引器或知识源自动执行数据引入。本文重点介绍索引自动化。

在查询时，调用方的身份通过 x-ms-query-source-authorization 参数包含在请求标头中。如果用户要查看搜索结果，则标识必须与文档的权限元数据匹配。

本文重点介绍基于以下基础构建的索引自动化方法：

使用基于角色的访问控制 (Azure RBAC) 保护的 Azure 存储 Blob。不支持基于属性的访问控制（Azure ABAC）。
Azure Blob 索引器或用于检索和引入数据和元数据（包括权限筛选器）的 Blob 知识源。若要获取权限筛选器支持，请使用支持该功能的Azure SDK的最新预览版 REST API 或预览包。
包含引入的文档和相应权限的 Azure AI 搜索中的索引。权限元数据作为字段存储在索引中。
使用权限筛选器的查询。若要设置遵循权限筛选器的查询，请使用支持该功能的Azure SDK的最新预览 REST API 或预览包。

先决条件

Microsoft Entra ID身份验证和授权。服务和应用必须位于同一租户中。只要所有租户都是 Microsoft Entra ID，用户就可以位于不同的租户中。角色分配用于每个经过身份验证的连接。
Azure AI 搜索（任何区域），但必须具有计费层（基本层和更高层）才能获得托管标识支持。搜索服务必须配置为基于角色的访问，并且必须具有托管标识（系统或用户）。
Azure 存储，标准性能（常规用途 v2），支持热、冷和寒访问层，提供受 RBAC 保护的容器或 Blob。
你应该了解索引器和知识源的工作原理以及如何创建索引。本文介绍数据源和索引器的配置设置，但不提供创建索引的步骤。有关为权限筛选器设计的索引的详细信息，请参阅 “创建具有权限筛选器字段的索引”。

局限性

Azure 门户不支持此功能。
以下索引器功能不支持源自 ADLS Gen2 的索引文档中的权限继承。如果在技能集或索引器中使用这些功能中的任何一项，则索引内容中不包含文档级权限。

配置Blob 存储

验证 Blob 容器是否使用基于角色的访问。

登录到Azure门户并找到存储帐户。
展开容器，然后选择包含要编制索引的 Blob 的容器。
选择 访问控制（IAM）以检查角色分配。对容器编制索引后，具有 存储 Blob 数据读取者 或 存储 Blob 数据参与者 的用户和组有权在索引中搜索文档。

授权

执行索引器时，搜索服务标识必须具有 Storage Blob Data Reader 权限。有关详细信息，请参阅使用托管标识连接到Azure存储。

配置Azure AI 搜索

回想一下，搜索服务必须具有：

授权

对于索引器的执行，发出 API 调用的客户端必须拥有 Search Service 贡献者权限以创建对象，Search 索引数据贡献者权限以执行数据导入，以及 Search 索引数据读取器权限以查询索引。请参阅使用角色连接到 Azure AI 搜索。

配置知识源

如果使用知识源，则知识源中的定义用于生成完整的索引管道（索引器、数据源和索引）。检测到 RBAC 范围并将其自动包含在生成的索引中。如果希望在索引内容中继承权限，则无需修改任何生成的对象。

有关使它适用于此方案的配置的要点：

isADLSGen2设置为 false，这意味着数据源是 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）

配置基于索引器的索引编制

如果要使用索引器，请配置索引器、数据源和索引，以便从 Blob 拉取权限元数据。

创建数据源

数据源类型必须是 azureblob。
数据源分析模式必须是默认值。
数据源必须具有 indexerPermissionOptions 和 rbacScope。
- 对于 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 是 false。可以在开发过程中将其设置为 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，并从索引中删除相应内容。

另请参阅

使用角色连接到Azure AI 搜索

反馈

此页面是否有帮助？

Last updated on 2026-09-17