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

(Azure AI 搜索 REST API) 创建索引器

项目
03/05/2024

索引器自动从受支持的 Azure 数据源（例如 Azure 存储、Azure SQL 数据库和 Azure Cosmos DB）编制索引，仅举几例。索引器使用预定义的 数据源 和索引来建立一个索引管道，该管道提取和序列化源数据，并将其传递给搜索服务进行数据引入。对于图像和非结构化文本的 AI 扩充，索引器还可以接受定义 AI 处理的 技能组 。

创建索引器会将其添加到搜索服务并运行它。如果请求成功，将使用数据源中的可搜索内容填充索引。

可以对请求使用 POST 或 PUT。对于任一对象，请求正文中的 JSON 文档都提供对象定义。

POST https://[service name].search.windows.net/indexers?api-version=[api-version]
    Content-Type: application/json  
    api-key: [admin key]

或者，可以使用 PUT 并在 URI 上指定索引器名称。

PUT https://[service name].search.windows.net/indexers/[indexer name]?api-version=[api-version]
    Content-Type: application/json  
    api-key: [admin key]

所有服务请求都需要 HTTPS。如果索引器不存在，则创建它。如果已存在，则会将其更新为新定义，但如果想要执行索引器，则必须发出运行索引器请求。

索引器配置因数据源类型而异。有关创建索引器的特定于数据平台的指南，请从索引器概述入门，其中包含相关文章的完整列表。

URI 参数

参数	说明
服务名称	必需。将其设置为搜索服务的唯一用户定义名称。
索引器名称	如果使用 PUT，则为 URI 上的必需项。名称必须为小写，以字母或数字开头，没有斜杠或点，并且少于 128 个字符。名称必须以字母或数字开头，但名称的其余部分可以包含任何字母、数字和短划线，只要短划线不是连续的。
api-version	必需。有关支持的版本列表，请参阅 API 版本。

请求标头

下表介绍必需和可选的请求标头。

字段	说明
Content-Type	必需。将其设置为 `application/json`
api-key	如果使用的是 Azure 角色，并且请求中提供了持有者令牌，则为可选，否则需要密钥。创建请求必须包含 `api-key` 设置为管理密钥 (而不是查询密钥) 的标头。有关详细信息，请参阅使用密钥身份验证连接到 Azure AI 搜索。

请求正文

数据源、索引和技术集是索引器定义的一部分，但每个都是独立的组件，可以按不同组合进行使用。例如，可以将同一数据源与多个索引器配合使用、将同一索引与多个索引器配合使用，或者让多个索引器写入单个索引。

以下 JSON 是定义main部分的高级表示形式。

{   
    "name" : (optional on PUT; required on POST) "Name of the indexer",  
    "description" : (optional) "Anything you want, or nothing at all", 
    "dataSourceName" : (required) "Name of an existing data source",  
    "targetIndexName" : (required) "Name of an existing index",  
    "skillsetName" : (required for AI enrichment) "Name of an existing skillset",
    "disabled" : (optional) Boolean value indicating whether the indexer is disabled. False by default,
    "schedule" : (optional but runs once immediately if unspecified) { ... },  
    "parameters": { (optional)
       "batchSize": null,
       "maxFailedItems": 0,
       "maxFailedItemsPerBatch": 0,
       "base64EncodeKeys": null,
       "configuration": { (optional, mostly specific to the data source)
            "executionEnvironment": null
        }
      }, 
    "fieldMappings" : (optional) { ... },
    "outputFieldMappings" : (required for AI enrichment) { ... },
    "encryptionKey":(optional) { }
}

请求包含以下属性：

属性	说明
name	必需。名称必须为小写，以字母或数字开头，没有斜杠或点，并且少于 128 个字符。名称必须以字母或数字开头，但名称的其余部分可以包含任何字母、数字和短划线，只要短划线不是连续的。
dataSourceName	必需。现有数据源的名称。它通常包括索引器可用于利用源平台特征的属性。因此，传递给索引器的数据源决定了某些属性和参数的可用性，例如 Azure Blob 中的内容类型筛选。或 Azure SQL 数据库的查询超时。
targetIndexName	必需。现有索引架构的名称。它定义包含可搜索、可筛选、可检索以及确定字段使用方式的其他属性的字段集合。在编制索引期间，索引器会对数据源进行爬网，并可选择破解文档和提取信息，将结果序列化为 JSON 格式，然后根据为索引定义的架构为有效负载编制索引。
skillsetName	AI 扩充所必需的。现有技能集的名称，每个索引器一个。与数据源和索引一样，技能集是附加到索引器的独立定义。可以通过其他索引器重新调整技术集的用途，但每个索引器一次只能使用一个技术集。
schedule	可选，但如果未指定且未禁用，则立即运行一次。计划包含 `interval` (必需的) 和 `startTime` (可选) 。有关详细信息，请参阅计划索引器。 `interval` 指定索引器的运行频率。允许的最小间隔为五分钟；最长为一天。必须将其格式化为 XSD“dayTimeDuration”值（ISO 8601 持续时间值的受限子集）。此模式为： `"P[nD][T[nH][nM]]".` 示例： `PT15M` 每 15 分钟， `PT2H` 每 2 小时一次。 `startTime` 是索引器应开始运行的 UTC 日期时间。
disabled	可选。指示是否禁用索引器的布尔值。如果要创建索引器定义而不立即运行索引器定义，请设置此属性。默认值为 False。
parameters	可选。用于修改运行时行为的属性。 `"batchSize"` (整数) 。指定可从数据源读取并可将其索引编制为单个批次以提高性能的项数。对于 Azure SQL Database 和 Azure Cosmos DB，默认值为特定于源的 (1000，Azure Blob 存储) 为 10。 `"maxFailedItems"` (整数) 。指定在索引器运行被视为失败之前要容忍的错误数。默认为 0。如果不希望因任何错误而导致索引编制过程停止，请将此项设置为 -1。使用 “获取索引器状态” 检索有关失败文档的信息。 `"maxFailedItemsPerBatch"` (整数) 。指定在索引器运行被视为失败之前，每个批次中要容忍的错误数。默认为 0。如果不希望因任何错误而导致索引编制过程停止，请将此项设置为 -1。 `"base64EncodeKey"` (布尔) 。指定是否对包含无效字符的文档键进行编码。 `"configuration"`. 根据数据源而变化的属性。 `"executionEnvironment"` (字符串) 。重写内部系统进程选择的执行环境。如果索引器通过专用终结点连接访问外部资源，则需要将执行环境 `Private` 显式设置为。此设置位于下 `"configuration"`。对于数据引入，此设置仅适用于预配为基本或标准 (S1、S2、S3) 的服务。对于 AI 扩充内容处理，此设置仅适用于 S2 和 S3。有效值不区分大小写，由 [null 或未指定]、 `Standard` (默认) 或 `Private`组成。
fieldMappings	可选。将源字段显式关联到搜索索引中的目标字段。当源字段和目标字段具有不同名称或类型时，或者要指定函数时使用。节 `fieldMappings` 包括 `sourceFieldName` 必需 (、基础数据源) 字段、 `targetFieldName` 必需 (字段、索引) 中的字段以及编码输出的可选 `mappingFunction` 字段。可以在字段映射函数中找到支持函数和示例的列表。有关更多常规信息，请参阅字段映射和转换。
outputFieldMappings	扩充管道所必需的。将技能组的输出映射到索引或投影。节 `outputFieldMappings` 包括 `sourceFieldName` 必需 (、扩充树) 节点、 `targetFieldName` 必需 (、索引) 中的字段以及编码输出的可选 `mappingFunction` 字段。可以在字段映射函数中找到支持函数和示例的列表。有关更多常规信息，请参阅如何映射技能组中的输出字段。
encryptionKey	可选。用于使用自己的密钥对静态索引器定义进行加密，该密钥在 Azure 密钥保管库中管理。适用于在 2019-01-01 或之后创建的可计费搜索服务。节 `encryptionKey` 包含用户定义的 `keyVaultKeyName` (所需的) 、系统生成的 `keyVaultKeyVersion` (所需的) ，以及提供 `keyVaultUri` 所需的密钥 (，也称为 DNS 名称) 。示例 URI 可能是“https://my-keyvault-name.vault.azure.net"”。（可选）可以指定 `accessCredentials` 是否不使用托管系统标识。 `accessCredentials`的属性包括 `applicationId` (Microsoft Entra ID 已授予对指定 Azure 密钥保管库) 的访问权限的应用程序 ID，以及`applicationSecret`已注册应用程序) (身份验证密钥。下一部分中的示例演示了语法。

Blob 配置参数

多个参数专用于特定的索引器，例如 Azure Blob 索引编制。

参数	类型和允许的值	使用情况
`"parsingMode"`	字符串 `"text"` `"delimitedText"` `"json"` `"jsonArray"` `"jsonLines"`	对于 Azure Blob，设置为 `text` 可改进 Blob 存储中纯文本文件的索引编制性能。对于 CSV Blob，请在 Blob 为纯 CSV 文件时设置为 `delimitedText`。对于 JSON Blob，设置为 `json` 以提取结构化内容，或设置为 `jsonArray` 以在 Azure AI 搜索中将数组的各个元素提取为单独的文档。使用 `jsonLines` 提取单个 JSON 实体（用新行分隔）作为 Azure AI 搜索中的单独文档。
`"excludedFileNameExtensions"`	String 逗号分隔的列表用户定义	对于 Azure Blob，请忽略列表中的任何文件类型。例如，可以排除“.png、.png、.mp4”，在索引编制过程中遇到这些文件时直接跳过。
`"indexedFileNameExtensions"`	String 逗号分隔的列表用户定义	对于 Azure Blob，如果文件扩展名在列表中，请选择 Blob。例如，可以让索引编制侧重于特定的应用程序文件“.docx、.pptx、.msg”，以便专门包括这些文件类型。
`"failOnUnsupportedContentType"`	布尔是 false（默认值）	对于 Azure Blob，如果希望在遇到不受支持的内容类型时继续进行索引编制，并且无法提前知道所有内容类型（文件扩展名），则请设置为 `false`。
`"failOnUnprocessableDocument"`	布尔是 false（默认值）	对于 Azure Blob，如果希望在文档的索引编制失败的情况下继续进行索引编制，则请设置为 `false`。
`"indexStorageMetadataOnly` `ForOversizedDocuments"`	布尔值 true false（默认值）	对于 Azure Blob，请将此属性设置为 `true`，这样就仍可为因太大而无法处理的 Blob 内容编制存储元数据的索引。过大的 blob 会被默认视为错误。有关 Blob 大小的限制，请参阅服务限制。
`"delimitedTextHeaders"`	String 逗号分隔的列表用户定义	对于 CSV Blob，指定以逗号分隔的列标题列表，用于将源字段映射到索引中的目标字段。
`"delimitedTextDelimiter"`	String 单个字符用户定义	对于 CSV Blob，指定 CSV 文件的行尾分隔符，其中每行启动一个新文档 (例如 `"\|"` ，) 。
`"firstLineContainsHeaders"`	布尔 true（默认值） false	对于 CSV blob，指示每个 blob 的第一个 (非空) 行包含标头。
`"documentRoot"`	String 用户定义的路径	对于 JSON 数组，给定结构化或半结构化文档，可以使用此属性指定数组的路径。
`"dataToExtract"`	String `"storageMetadata"` `"allMetadata"` `"contentAndMetadata"`（默认值）	对于 Azure Blob：设置为 `"storageMetadata"`，仅对标准 Blob 属性和用户指定的元数据编制索引。设置为 `"allMetadata"` 可提取 Azure Blob 存储子系统提供的元数据，对特定于内容类型的元数据（例如，只特定于 .png 文件的元数据）编制索引。设置为 `"contentAndMetadata"` 可提取每个 Blob 的所有元数据和文本内容。对于 AI 扩充中的图像分析，当设置为以外的`"none"`值时`"imageAction"`，设置`"dataToExtract"`会告知索引器要从图像内容中提取哪些数据。适用于 .PDF 或其他应用程序中的嵌入图像内容，或者 Azure Blob 中的图像文件（例如 .jpg 和 .png）。
`"imageAction"`	String `"none"` `"generateNormalizedImages"` `"generateNormalizedImagePerPage"`	对于 Azure Blob，设置为 `"none"` 即可忽略数据集中的嵌入图像或图像文件。这是默认值。对于 AI 扩充中的图像分析，设置为`"generateNormalizedImages"` 以从图像中提取文本 (例如，从交通停止标志) “停止”一词，并将其嵌入内容字段。在图像分析过程中，索引器会在文档破解过程中生成一系列规范化的图像，并将生成的信息嵌入内容字段中。此操作需要将 `"dataToExtract"` 设置为 `"contentAndMetadata"`。规范化的图像是指在视觉搜索结果中包含图像时，对图像进行额外的处理，使图像的输出一致，并通过调整大小和旋转方向使图像在呈现时更一致（例如，使图像控件中的照片大小一致，如 JFK 演示中所示）。当使用此选项时，将为每个图像生成此信息。如果设置为 `"generateNormalizedImagePerPage"`，则将以不同的方式对待 PDF 文件，将不会提取嵌入的图像，而是将每个页面呈现为图像并相应地规范化。此每页进程预计花费的时间比 `"generateNormalizedImages"`要长得多。对待非 PDF 文件类型的方式与设置了 `"generateNormalizedImages"` 时相同。将 `"imageAction"` 配置设置为除其他任何值之外 `"none"` ，都需要将技能组附加到该索引器，并且根据设计，可能是一个性能较低的过程。
`"normalizedImageMaxWidth"` `"normalizedImageMaxHeight"`	一个介于 50 和 10000 之间的整数	设置时 `"imageAction"` 生成的规范化图像) 最大宽度或高度 (像素。默认为 2000。将规范化图像的最大宽度和高度默认设置为 2000 像素是考虑到 OCR 技术所能够支持的最大大小以及图像分析技术。 OCR 技能支持非英语语言的最大宽度和高度为 4200，支持英语语言的最大宽度和高度为 10000。如果增加最大限制，则根据技能组定义和文档语言，对较大的图像进行处理可能会失败。
`"allowSkillsetToReadFileData"`	布尔是 false（默认值）	将 `"allowSkillsetToReadFileData"` 参数设置为 `true` 将创建一个路径，该路径 `/document/file_data` 是表示从 Blob 数据源下载的原始文件数据的对象。这使你可以将原始文件数据传递给自定义技能，以便在扩充管道中进行处理，或传递到文档提取技能。生成的对象定义如下： `{ "$type": "file", "data": "BASE64 encoded string of the file" }` 将 `"allowSkillsetToReadFileData"` 参数设置为 `true` 需要将技能集附加到该索引器，并将参数 `"parsingMode"` 设置为 `"default"`、 `"text"` 或 `"json"`。
`"pdfTextRotationAlgorithm"`	String `"none"`（默认值） `"detectAngles"`	将 `"pdfTextRotationAlgorithm"` 参数设置为 `"detectAngles"` 可能有助于从其中包含旋转文本的 PDF 文件生成更好、更易读的文本提取。请注意，使用此参数时可能会产生较小的性能损失。此参数仅适用于 PDF 文件，并且仅适用于包含嵌入文本的 PDF。如果旋转后的文本显示在 PDF 中的嵌入图像中，则此参数不适用。将 `"pdfTextRotationAlgorithm"` 参数设置为 `"detectAngles"` 需要将 `"parsingMode"` 参数设置为 `"default"`。

Azure Cosmos DB 配置参数

以下参数特定于 Cosmos DB 索引器。

参数	类型和允许的值	使用情况
`"assumeOrderByHighWaterMarkColumn"`	布尔	对于具有 SQL API 的 Cosmos DB 索引器，设置此参数可向 Cosmos DB 提供一个提示，指出用于返回索引的文档的查询实际上按 `_ts` 列排序。设置此参数可针对增量索引方案提供更好的结果。

Azure SQL配置参数

以下参数特定于 Azure SQL 数据库。

参数	类型和允许的值	使用情况
`"queryTimeout"`	字符串 "hh:mm:ss" "00:05:00"	对于 Azure SQL 数据库，可以通过设置此参数使超时超出 5 分钟的默认值。
`"convertHighWaterMarkToRowVersion"`	布尔	将此参数设置为“true”，以对高使用标记列使用 rowversion 数据类型。当此属性设置为 true 时，索引器会在索引器运行之前从 rowversion 值中减去一个值。这样做是因为具有一对多联接的视图可能包含具有重复 rowversion 值的行。减一可确保索引器查询不会错过这些行。
`"disableOrderByHighWaterMarkColumn"`	布尔	如果要在用于更改检测的查询中禁用 ORDER BY 行为，请将此参数设置为“true”。如果使用高水位线更改检测策略，索引器将使用 WHERE 和 ORDER BY 子句来跟踪哪些行需要索引 (`WHERE [High Water Mark Column] > [Current High Water Mark Value] ORDER BY [High Water Mark Column]`) 。此参数禁用 ORDER BY 行为。索引编制将更快完成，但权衡是，如果索引器因任何原因中断，则必须完全重复整个索引器作业。

响应

对于成功的请求，返回“201 已创建”。

示例

示例：具有计划和泛型参数的索引器

创建一个索引器，该索引器按从 2021 年 1 月 1 日 UTC 开始并每小时运行的计划将数据从数据源orders引用ordersds的表复制到索引。如果每批中索引失败的项目不超过 5 个并且索引失败的项目总计不超过 10 个，则每个索引器都将成功调用。

{
    "name" : "myindexer",  
    "description" : "a cool indexer",  
    "dataSourceName" : "ordersds",  
    "targetIndexName" : "orders",  
    "schedule" : { "interval" : "PT1H", "startTime" : "2021-01-01T00:00:00Z" },  
    "parameters" : { "maxFailedItems" : 10, "maxFailedItemsPerBatch" : 5 }  
}

注意

如果将索引器设置为某个计划，但每次运行时一次又一次地在同一文档上反复失败，则索引器将以不那么频繁的时间间隔开始运行（最多每 24 小时至少一次），直到它成功地再次取得进展。如果你认为已修复导致索引器停滞在某个点的任何问题，则可以执行索引器的重置，然后执行按需运行，如果成功取得进展，索引器将再次返回到其设置的计划间隔。

示例：具有 Blob 参数的索引器

索引器可以选择使用配置参数来修改运行时行为。配置参数在索引器请求中以逗号分隔，特定于数据源类型。以下配置参数提供了用于为 Blob 编制索引的说明。

  {
    "name" : "my-blob-indexer-for-cognitive-search",
    ... other indexer properties
    "parameters" : 
      { 
      "maxFailedItems" : "15", 
      "batchSize" : "100", 
      "configuration" : 
          { 
          "parsingMode" : "json", 
          "indexedFileNameExtensions" : ".json, .jpg, .png",
          "imageAction" : "generateNormalizedImages",
          "dataToExtract" : "contentAndMetadata" ,
          "executionEnvironment": "Standard"
          } 
      }
  }

示例：具有字段映射的索引器

将源表的字段 _id 映射到 "id" 搜索索引中的字段。 Azure AI 搜索不允许字段名称以下划线开头。字段映射可以解决名称差异。源和目标字段名称不区分大小写。有关详细信息，请参阅字段映射和转换。

"fieldMappings" : [
    { "sourceFieldName" : "_id", "targetFieldName" : "id" },
    { "sourceFieldName" : "_timestamp", "targetFieldName" : "timestamp" }
]

示例：使用 AI 扩充的索引器

演示由对和 outputFieldMappings的引用skillset指示的 AI 扩充。技术集是高级资源，是单独定义的。此示例是 AI 扩充教程中索引器定义的缩写。

{
  "name":"demoindexer",	
  "dataSourceName" : "demodata",
  "targetIndexName" : "demoindex",
  "skillsetName" : "demoskillset",
  "fieldMappings" : [
    {
        "sourceFieldName" : "content",
        "targetFieldName" : "content"
    }
   ],
  "outputFieldMappings" : 
  [
    {
        "sourceFieldName" : "/document/organizations", 
        "targetFieldName" : "organizations"
    },
  ],
  "parameters":
  {
  	"maxFailedItems":-1,
  	"configuration": 
    {
    "dataToExtract": "contentAndMetadata",
    "imageAction": "generateNormalizedImages"
    }
  }
}

示例：具有技能组和输出字段映射的索引器

在技能组绑定到索引器的 AI 扩充方案中，必须添加 outputFieldMappings 以关联向索引中的可搜索字段提供内容的扩充步骤的任何输出。是 sourceFieldName 扩充树中的节点。它可能是在从源文档中的两个单独的字段扩充期间生成的复合结构。 targetFieldName是搜索索引中的字段。有关详细信息，请参阅如何映射技能组中的输出字段。

"outputFieldMappings" : [
      {
        "sourceFieldName" : "/document/organizations", 
        "targetFieldName" : "organizations"
      },
      {
        "sourceFieldName" : "/document/pages/*/keyPhrases/*", 
        "targetFieldName" : "keyphrases"
      },
      {
          "sourceFieldName": "/document/languageCode",
          "targetFieldName": "language",
          "mappingFunction": null
      }      
  ]

示例：加密密钥

加密密钥是用于其他加密的客户管理的密钥。有关详细信息，请参阅在 Azure 密钥保管库中使用客户管理的密钥进行加密。

{
    "name" : "myindexer",  
    "description" : "a cool indexer",  
    "dataSourceName" : "ordersds",  
    "targetIndexName" : "orders",  
    "schedule" : { "interval" : "PT1H", "startTime" : "2021-01-01T00:00:00Z" },  
    "parameters" : { "maxFailedItems" : 10, "maxFailedItemsPerBatch" : 5 },
    "encryptionKey": (optional) { 
      "keyVaultKeyName": "Name of the Azure Key Vault key used for encryption",
      "keyVaultKeyVersion": "Version of the Azure Key Vault key",
      "keyVaultUri": "URI of Azure Key Vault, also referred to as DNS name, that provides the key. An example URI might be https://my-keyvault-name.vault.azure.net",
      "accessCredentials": (optional, only if not using managed system identity) {
        "applicationId": "Microsoft Entra ID application ID that was granted access permissions to your specified Azure Key Vault",
        "applicationSecret": "Authentication key of the registered application)"}
      }
}

通过