从 Azure Blob 存储索引数据

本文介绍如何配置从 Azure Blob 存储导入内容的索引器，并使它在 Azure AI 搜索中可搜索。索引器接收单个容器中的 Blob 作为输入。输出是一个搜索索引，用于在单个字段中存储可搜索的内容和元数据。

本文使用搜索服务 REST API 来演示如何配置和运行索引器。但是，也可以使用：

Azure SDK 包（任何版本）
在 Azure 门户中导入数据（新建）向导

注释

Azure AI 搜索可以在索引编制期间引入基于角色的访问控制（RBAC）范围，并将这些权限传输到搜索索引中的索引内容。有关详细信息，请参阅使用 Blob 索引器或知识源引入 RBAC 范围元数据。

先决条件

Azure Blob 存储，标准性能（常规用途 v2）。
访问层包括热访问层、冷访问层、寒访问层和存档访问层。索引器可以检索热访问层、冷访问层和寒访问层上的 Blob。
提供文本内容和元数据的 blob。如果 blob 包含二进制内容或非结构化文本，请考虑为映像和自然语言处理添加 AI 扩充。 Blob 内容不得超出搜索服务层级的索引器限制。
支持的网络配置和数据访问。至少需要在 Azure 存储中拥有读取权限。包含访问密钥的存储连接字符串提供对存储内容的读取访问。如果使用 Microsoft Entra 登录名和角色，请确保搜索服务的托管标识具有“存储 Blob 数据读取者”权限。

默认情况下，搜索和存储都接受来自公共 IP 地址的请求。如果网络安全不是当务之急，只需使用连接字符串和读取权限即可为 Blob 数据编制索引。准备好添加网络保护后，请查看索引器访问受 Azure 网络安全功能保护的内容，获取有关数据访问的指导。
若要构建与本文所示调用类似的 REST 调用，请使用 REST 客户端。

支持的任务

可以将此索引器用于以下任务：

数据索引和增量索引：索引器可以从 Blob 容器和文件夹为文件和关联的元数据编制索引。它透过内置的更改检测来检测新的和更新的文件及元数据。可以按计划或按需配置数据刷新。
删除检测：索引器可以通过本机软删除或自定义元数据检测删除。
通过技能集应用 AI： 索引器完全支持技能集。此支持包括集成矢量化等关键功能，这些功能添加了数据分块和嵌入。
解析模式：如果想将 JSON 数组或行分析为单独的搜索文档，则索引器支持 JSON 分析模式。它还支持 Markdown 分析模式。
与其他功能的兼容性： 索引器与其他索引器功能（例如调试会话、用于增量扩充的索引器缓存和知识存储）无缝配合工作。

支持的文档格式

Blob 索引器可从以下文档格式提取文本：

CSV（请参阅为 CSV Blob 编制索引）
EML
EPUB
广州
HTML
JSON（请参阅为 JSON blob 编制索引）
KML（用于地理表示形式的 XML）
Markdown
Microsoft Office 格式：DOCX/DOC/DOCM、XLSX/XLS/XLSM、PPTX/PPT/PPTM、MSG（Outlook 电子邮件）、XML（2003 和 2006 Word XML）
公开文档格式：ODT、ODS、ODP
PDF
纯文本文件（另请参阅为纯文本编制索引）
RTF
XML
ZIP

确定要为哪些 blob 编制索引

在设置索引之前，请查看源数据，以确定是否需要进行任何更改。索引器一次可以为一个容器中的内容编制索引。默认情况下，索引器处理容器中的所有 Blob。有多个选项来进行更有选择性的处理：

将 blob 放置在虚拟文件夹中。索引器数据源定义包括一个参数，该参数可以使用虚拟文件夹。如果指定虚拟文件夹，索引器只为文件夹中的 Blob 编制索引。
按文件类型包含或排除 blob。支持的文档格式列表可帮助你确定要排除的 blob。例如，你可能希望排除不提供可搜索文本的图像或音频文件。可以通过索引器中的配置设置来控制此功能。

包含或排除任意 blob。若要跳过特定 Blob，请将以下元数据属性和值添加到 Azure Blob 存储中的 Blob。当索引器遇到此属性时，它会在索引编制运行中跳过相应 blob 或其内容。

属性名称	属性值	Explanation
`AzureSearch_Skip`	`true`	指示 Blob 索引器完全跳过该 Blob，索引器不会尝试提取元数据或内容。当特定 Blob 重复失败并中断索引过程时，此属性非常有用。
`AzureSearch_SkipContent`	`true`	索引器跳过内容并仅提取元数据。此属性等效于`"dataToExtract": "allMetadata"`配置设置中所述的设置，但它的范围限定为特定的 Blob。

如果未设置包含或排除条件，索引器会将不符合条件的 Blob 报告为错误，然后继续。如果出现足够多的错误，处理可能会停止。可在索引器配置设置中指定错误容错。

索引器通常会为每个 blob 创建一个搜索文档，其中的文本内容和元数据作为索引中的可搜索字段来捕获。如果 blob 是整个文件，则可以将其解析为多个搜索文档。例如，可以解析 CSV 文件中的行，以便为每行创建一个搜索文档。

复合或嵌入式文档（例如 ZIP 存档、嵌入了带附件 Outlook 电子邮件的 Word 文档或带附件的 .MSG 文件）也以单一文档的形式编制索引。例如，从 .MSG 文件的附件中提取的所有图像都会返回到 normalized_images 字段中。如果有图像，请考虑添加 AI 扩充，以从该内容中获取更多搜索实用工具。

索引器将文档的文本内容提取到名为 content 的字符串字段中。还可以提取标准和用户定义的元数据。

为 Blob 元数据编制索引

还可以为 Blob 元数据编制索引。如果你认为任何标准或自定义元数据属性在筛选器和查询中都很有用，此功能非常有用。

索引器逐字提取用户指定的元数据属性。若要接收值，必须在类型的 Edm.String 搜索索引中定义一个字段，其名称与 blob 的元数据键相同。例如，如果 blob 具有具有 Sensitivity 值的 High元数据键，请定义搜索索引中命名 Sensitivity 的字段。索引字段用值 High填充。

可以将标准 Blob 元数据属性提取到名字和数据类型相似的字段，如下所示。 Blob 索引器会自动为这些 Blob 元数据属性创建内部字段映射，将原始连字符名称（metadata-storage-name）转换为下划线等效名称（metadata_storage_name）。

仍需将下划线字段添加到索引定义，但可以省略字段映射，因为索引器会自动关联。

metadata_storage_name （Edm.String）是 blob 的文件名。例如，如果有 blob /my-container/my-folder/subfolder/resume.pdf，则此字段的值为 resume.pdf。
metadata_storage_path （Edm.String）是 blob 的完整 URI，包括存储帐户。例如，https://myaccount.blob.core.chinacloudapi.cn/my-container/my-folder/subfolder/resume.pdf。
metadata_storage_content_type （Edm.String）是由用于上传 blob 的代码定义的内容类型。例如，application/octet-stream。
metadata_storage_last_modified （Edm.DateTimeOffset）是 blob 的上次修改时间戳。 Azure AI 搜索使用此时间戳来识别已更改的 blob，避免在初次编制索引之后再次为所有内容编制索引。
metadata_storage_size （Edm.Int64）是 blob 大小（以字节为单位）。
metadata_storage_content_md5 （Edm.String）是 blob 内容的 MD5 哈希（如果可用）。
metadata_storage_sas_token （Edm.String）是一个临时 SAS 令牌，自定义技能可用于访问 Blob。不要存储此令牌供以后使用，因为它可能会过期。

最后，您可以在索引架构中表示与您正在索引的 blob 文档格式相关的元数据属性。有关特定于内容的元数据的详细信息，请参阅内容元数据属性。

必须指出，无需为搜索索引中的所有上述属性定义字段。只需捕获应用程序所需的属性即可。

目前，此索引器不支持为 blob 索引标记编制索引。

定义数据源

数据源定义指定要编制索引的数据、凭据和用于标识数据更改的策略。数据源定义为独立的资源，以便它可以被多个索引器使用。

创建或更新数据源以设置其定义：

{
    "name" : "my-blob-datasource",
    "type" : "azureblob",
    "credentials" : { "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<account name>;AccountKey=<account key>;" },
    "container" : { "name" : "my-container", "query" : "<optional-virtual-directory-name>" }
}

将 type 设置为 azureblob（必需）。
将 credentials 设置为 Azure 存储连接字符串。下一部分介绍受支持的格式。
将 container 设置为 Blob 容器，并使用 query 指定任何子文件夹。

如果希望索引器在标记要删除源文档时删除搜索文档，还可以在数据源定义中包含软删除策略。

受支持的凭据和连接字符串

索引器可以使用以下连接连接到 Blob 容器。

完全访问存储帐户连接字符串
`{ "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>;" }`
可以通过在左窗格中选择 “访问密钥 ”，从 Azure 门户中的“存储帐户”页获取连接字符串。请确保选择完整的连接字符串，而不只是一个密钥。

托管标识连接字符串
`{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;" }`
此连接字符串不需要帐户密钥，但先前必须已将搜索服务配置为使用托管标识进行连接。

存储帐户共享访问签名（SAS）连接字符串
`{ "connectionString" : "BlobEndpoint=https://<your account>.blob.core.chinacloudapi.cn/;SharedAccessSignature=?sv=2016-05-31&sig=<the signature>&spr=https&se=<the validity end time>&srt=co&ss=b&sp=rl;" }`
SAS 应具有容器和对象（本例中为 blob）的列表和读取权限。

容器共享访问签名
`{ "connectionString" : "ContainerSharedAccessUri=https://<your storage account>.blob.core.chinacloudapi.cn/<container name>?sv=2016-05-31&sr=c&sig=<the signature>&se=<the validity end time>&sp=rl;" }`
SAS 应具有容器的列表和读取权限。有关详细信息，请参阅使用共享访问签名 (SAS) 授予对 Azure 存储资源的有限访问权限。

注释

如果使用 SAS 凭据，则需要使用续订的签名定期更新数据源凭据，以防止其过期。如果 SAS 凭据过期，索引器将失败，并显示类似于“连接字符串中提供的凭据无效或已过期”的错误消息。

将搜索字段添加到索引

在搜索索引中，添加字段以接受 Azure Blob 的内容和元数据。

创建或更新索引以定义存储 Blob 内容和元数据的搜索字段：

POST https://[service name].search.azure.cn/indexes?api-version=2025-09-01
{
    "name" : "my-search-index",
    "fields": [
        { "name": "ID", "type": "Edm.String", "key": true, "searchable": false },
        { "name": "content", "type": "Edm.String", "searchable": true, "filterable": false },
        { "name": "metadata_storage_name", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true  },
        { "name": "metadata_storage_size", "type": "Edm.Int64", "searchable": false, "filterable": true, "sortable": true  },
        { "name": "metadata_storage_content_type", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true },        
    ]
}

创建文档键字段（"key": true）。对于 Blob 内容，最佳候选项是元数据属性。
- metadata_storage_path （默认值）是对象或文件的完整路径。键字段（ID 在此示例中）使用来自metadata_storage_path的值填充，因为它是默认值。
- metadata_storage_name 仅当名称唯一时，才可用。如果希望此字段作为键，请将 "key": true 移动到此字段定义。
- 要添加到 Blob 中的自定义元数据属性。这种做法需要 Blob 上传过程将该元数据属性添加到所有 Blob。由于密钥是必需属性，因此缺少值的任何 Blob 都无法编制索引。如果使用自定义元数据属性作为键，请避免更改该属性。如果键属性发生更改，索引器将为同一 Blob 添加重复的文档。
元数据属性通常包括对文档键无效的字符，例如 / 和 -。但是，索引器会自动将关键元数据属性编码，而无需进行配置或字段映射。
添加一个 content 字段，用于通过 Blob content 的属性存储每个文件中提取的文本。你不需要使用此名称，但通过使用它，可以利用隐式字段映射。
为标准元数据属性添加字段。索引器可以读取自定义元数据属性、标准元数据属性和内容特定的元数据属性。

配置和运行 blob 索引器

创建索引和数据源后，创建索引器。索引器配置指定控制运行时行为的输入、参数和属性。还可指定要为 blob 的哪些部分编制索引。

通过为索引器命名并引用数据源和目标索引来创建或更新索引器：

POST https://[service name].search.azure.cn/indexers?api-version=2025-09-01
{
  "name" : "my-blob-indexer",
  "dataSourceName" : "my-blob-datasource",
  "targetIndexName" : "my-search-index",
  "parameters": {
      "batchSize": null,
      "maxFailedItems": null,
      "maxFailedItemsPerBatch": null,
      "configuration": {
          "indexedFileNameExtensions" : ".pdf,.docx",
          "excludedFileNameExtensions" : ".png,.jpeg",
          "dataToExtract": "contentAndMetadata",
          "parsingMode": "default"
      }
  },
  "schedule" : { },
  "fieldMappings" : [ ]
}

如果默认文档（10 个文档）未充分利用或占用可用资源，则设置 batchSize 。默认批大小特定于数据源。当平均文档大小较大时，Blob 索引编制会将批大小设置为 10 个文档。
在 configuration 下，根据文件类型选择要编制索引的 blob，或者保持未指定状态以检索所有 blob。

对于 indexedFileNameExtensions，请提供文件扩展名的逗号分隔列表（带前导点）。对 excludedFileNameExtensions 做同样的操作，以指示索引器应跳过哪些扩展。如果这两个列表中都有相同的扩展，索引器将从索引中排除它。
在configuration下，设置dataToExtract以控制Blob的哪些部分被编制索引：
- contentAndMetadata 指定索引器为从 Blob 中提取的所有元数据和文本内容编制索引。这是默认值。
- storageMetadata 指定索引器仅对标准 Blob 属性和用户指定的元数据编制索引。
- 指定索引器从 Blob 内容中提取，并索引标准 Blob 属性以及< c1>找到的内容类型的任何元数据。
在 configuration 中，设置 parsingMode。默认分析模式是每个 Blob 的一个搜索文档。如果 Blob 是纯文本，则可以通过切换到纯文本解析来获得更好的性能。如果您需要更高细粒度的解析，也就是将 Blob 映射到多个搜索文档，请指定不同的模式。 Blob 支持一对多分析，其中包括：
- JSON 文档
- CSV 文件
如果字段名称或类型存在差异，或者需要在搜索索引中使用多个版本的源字段，请指定字段映射。

在 Blob 索引编制中，通常可以省略字段映射，因为索引器内置支持将 content 元数据属性映射到索引中类似命名和类型化的字段。对于元数据属性，索引器会自动将搜索索引中的连字符 - 替换为下划线。
有关其他属性的详细信息，请参阅创建索引器。有关参数说明的完整列表，请参阅 REST API。

创建索引器后，它会自动运行。可以通过将 disabled 设置为 true 来阻止此操作。若要控制索引器执行，请按需运行索引器或按计划运行索引器。

将数据从多个 Azure Blob 容器索引到单个索引

请记住，索引器只能从单个容器为数据编制索引。如果需要为多个容器中的数据编制索引并将其合并到单个 AI 搜索索引中，请配置多个指向同一索引的索引器。请注意每个 SKU 可用的索引器的最大数目。

例如，可以使用两个索引器从两个命名 my-blob-datasource1 和 my-blob-datasource2不同的数据源中提取数据。每个数据源指向一个单独的 Azure Blob 容器，但两者都定向到名为 my-search-index 的同一索引。

第一个索引器定义示例：

POST https://[service name].search.azure.cn/indexers?api-version=2025-09-01
{
  "name" : "my-blob-indexer1",
  "dataSourceName" : "my-blob-datasource1",
  "targetIndexName" : "my-search-index",
  "parameters": {
      "batchSize": null,
      "maxFailedItems": null,
      "maxFailedItemsPerBatch": null,
      "configuration": {
          "indexedFileNameExtensions" : ".pdf,.docx",
          "excludedFileNameExtensions" : ".png,.jpeg",
          "dataToExtract": "contentAndMetadata",
          "parsingMode": "default"
      }
  },
  "schedule" : { },
  "fieldMappings" : [ ]
}

并行运行的第二个索引器定义示例：

POST https://[service name].search.azure.cn/indexers?api-version=2025-09-01
{
  "name" : "my-blob-indexer2",
  "dataSourceName" : "my-blob-datasource2",
  "targetIndexName" : "my-search-index",
  "parameters": {
      "batchSize": null,
      "maxFailedItems": null,
      "maxFailedItemsPerBatch": null,
      "configuration": {
          "indexedFileNameExtensions" : ".pdf,.docx",
          "excludedFileNameExtensions" : ".png,.jpeg",
          "dataToExtract": "contentAndMetadata",
          "parsingMode": "default"
      }
  },
  "schedule" : { },
  "fieldMappings" : [ ]
}

检查索引器状态

若要监视索引器状态和执行历史记录，请发送获取索引器状态请求：

GET https://myservice.search.azure.cn/indexers/myindexer/status?api-version=2025-09-01
  Content-Type: application/json  
  api-key: [admin key]

响应包括状态和已处理的项数。它应如下例所示：

    {
        "status":"running",
        "lastResult": {
            "status":"success",
            "errorMessage":null,
            "startTime":"2022-02-21T00:23:24.957Z",
            "endTime":"2022-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2022-02-21T00:23:24.957Z",
                "endTime":"2022-02-21T00:36:47.752Z",
                "errors":[],
                "itemsProcessed":1599501,
                "itemsFailed":0,
                "initialTrackingState":null,
                "finalTrackingState":null
            },
            ... earlier history items
        ]
    }

执行历史记录最多包含 50 个最近完成的执行。条目按逆序顺序排序，因此最新的执行先行。

处理错误

在索引过程中经常发生的错误包括：内容类型不受支持、内容缺失或 blob 过大。

默认情况下，Blob 索引器一旦遇到包含不受支持内容类型（例如音频文件）的 Blob 时，就会立即停止。可以使用 excludedFileNameExtensions 参数跳过某些内容类型。但是，你可能会希望，即使发生错误索引编制也继续执行，你稍后再调试各个文档。若要详细了解索引器错误，请参阅索引器故障排除指南和索引器错误和警告。

发生错误时，五个索引器参数控制索引器的响应：

PUT /indexers/[indexer name]?api-version=2025-09-01
{
  "parameters" : { 
    "maxFailedItems" : 10, 
    "maxFailedItemsPerBatch" : 10,
    "configuration" : { 
        "failOnUnsupportedContentType" : false, 
        "failOnUnprocessableDocument" : false,
        "indexStorageMetadataOnlyForOversizedDocuments": false
      }
    }
}

参数	有效值	Description
`maxFailedItems`	-1、null 或 0，正整数	如果在任意处理点（无论是在解析 blob 时，还是在将文档添加到索引时）发生错误，继续进行索引。将此属性设置为可接受的失败数。如果值为 `-1`，则不管发生多少错误，都可以进行处理。否则，该值为正整数。
`maxFailedItemsPerBatch`	-1、null 或 0，正整数	与上面相同，但用于批处理索引编制。
`failOnUnsupportedContentType`	真或假	如果索引器无法确定内容类型，请指定是继续还是失败作业。
`failOnUnprocessableDocument`	真或假	如果索引器无法处理其他受支持的内容类型的文档，请指定是继续还是失败作业。
`indexStorageMetadataOnlyForOversizedDocuments`	真或假	过大的 blob 会被默认视为错误。如果将此参数设置为 true，则即使无法对内容编制索引，索引器也会尝试对其元数据进行索引。有关 blob 大小的限制，请参阅服务限制。

Last updated on 2026-02-10

Condividi tramite