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

创建或更新索引器（预览版 REST API）

2024-06-28

适用于：2023-07-01-Preview。此版本不再受支持。将立即升级到较新版本。

重要

2023-07-01-Preview（无更改）。

2021-04-30-Preview 添加了对扩充缓存和加密密钥的托管标识支持：

“storageConnectionString” 接受系统分配的托管标识连接到 Azure 存储的资源 ID。此属性位于 “cache”下。不支持用户分配的托管标识。
“标识” 接受用户分配的托管标识。

2020-06-30-Preview 添加：

“缓存”，用于缓存和重用技能组创建的扩充内容。

索引器通过连接到预定义的 数据源、检索和序列化数据，并将其传递给搜索服务进行数据引入，从而自动从受支持的数据源编制索引。对于图像和非结构化文本的 AI 扩充，索引器还可以接受添加图像和自然语言处理的技能集。

可以在创建请求上使用 POST 或 PUT。对于任一对象，请求正文提供对象定义。

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。如果索引器不存在，则会创建索引器。如果已存在，则会将其更新为新定义，但如果需要索引器执行，则必须发出运行索引器请求。

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

更新索引器 不会自动运行它，但根据修改和关联的数据源，可能需要重置和重新运行。更新现有索引器时，整个定义将替换为请求正文的内容。通常，用于更新的最佳模式是使用 GET 检索索引器定义，对其进行修改，然后使用 PUT 对其进行更新。

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

注意

可以创建的索引器的最大数目因定价层而异。有关详细信息，请参阅 Azure AI 搜索服务限制。

URI 参数

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

请求标头

下表描述了必需的和可选的请求标头。

领域	描述
Content-Type	必填。将此设置为 `application/json`
api-key	如果使用 Azure 角色，并且请求中提供了持有者令牌，则为可选，否则需要密钥。 api-key 是唯一的系统生成的字符串，用于对搜索服务的请求进行身份验证。创建请求必须包含设置为管理密钥的 `api-key` 标头（而不是查询密钥）。有关详细信息，请参阅使用密钥身份验证连接到 Azure AI 搜索。

请求正文

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

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

{   
    "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",
    "cache":  { ... },
    "schedule" : (optional but runs once immediately if unspecified) { ... },  
    "parameters" : (optional) {
        "batchSize": null,
        "maxFailedItems": 0,
        "maxFailedItemsPerBatch": 0,
        "base64EncodeKeys": null,
        "configuration": { }
    },
    "fieldMappings" : (optional) { ... },
    "outputFieldMappings" : (required for AI enrichment) { ... },
    "encryptionKey":(optional) { },
    "disabled" : (optional) Boolean value indicating whether the indexer is disabled. False by default.
}

请求包含以下属性：

财产	描述
名字	必填。名称必须是小写，以字母或数字开头，没有斜杠或点，并且少于 128 个字符。使用字母或数字启动名称后，只要短划线不连续，名称的其余部分可以包含任何字母、数字和短划线。
描述	自选。索引器的说明。
dataSourceName	必填。提供连接信息和其他属性的现有数据源的名称。
targetIndexName	必填。现有索引的名称。
skillsetName	AI 扩充是必需的。现有技能集的名称。
缓存	AI 扩充（可选）支持重复使用未更改的文档。
计划	可选，但如果未指定，则立即运行一次。
参数	自选。用于修改运行时行为的属性。
fieldMappings	自选。当源字段和目标字段具有不同的名称时使用。
outputFieldMappings	AI 扩充是必需的。将技能集的输出映射到索引或投影。
encryptionKey	自选。用于使用自己的密钥（在 Azure Key Vault 中管理）加密静态索引器数据。若要了解详细信息，请参阅 Azure Key Vault中使用客户管理的密钥进行 Azure AI 搜索加密。
禁用	自选。指示是否禁用索引器的布尔值。默认情况下为 False。

响应

201 为成功的请求创建。

例子

示例：具有计划和参数 的基于文本的索引器

此示例创建一个索引器，该索引器根据从 2022 年 1 月 1 日 UTC 开始并每小时运行的计划，将 order-sds 数据源引用的表中的数据复制到 orders-idx 索引。如果每个批处理中索引不超过 5 个项未能编制索引，并且总共不超过 10 个项目的索引，则每个索引器调用都将成功。字段映射在字段名称和类型不匹配时提供数据路径。

{
    "name" : "myindexer",  
    "description" : "a cool indexer",  
    "dataSourceName" : "orders-ds",  
    "targetIndexName" : "orders-idx", 
    "fieldMappings" : [
      {
          "sourceFieldName" : "content",
          "targetFieldName" : "sourceContent"
      }
    ], 
    "schedule" : { "interval" : "PT1H", "startTime" : "2022-01-01T00:00:00Z" },  
    "parameters" : { "maxFailedItems" : 10, "maxFailedItemsPerBatch" : 5 }  
}

示例：技能集索引器

此示例演示 AI 扩充，该扩充由对技能集的引用和 outputFieldMappings，用于将技能输出映射到搜索索引中的字段。技能集是单独定义的高级资源。

此预览版中的新增功能仅适用于技能组，你可以指定缓存属性重复使用技能组定义中更改不受影响的文档。

{
  "name":"demo-indexer",	
  "dataSourceName" : "demo-data",
  "targetIndexName" : "demo-index",
  "skillsetName" : "demo-skillset",
  "cache" : 
    {
      "storageConnectionString" : "DefaultEndpointsProtocol=https;AccountName=<storage-account-name>;AccountKey=<storage-account-key>;EndpointSuffix=core.windows.net",
      "enableReprocessing": true
    },
  "fieldMappings" : [ ],
  "outputFieldMappings" : 
  [
    {
        "sourceFieldName" : "/document/organizations", 
        "targetFieldName" : "organizations"
    },
  ],
  "parameters":
  {
  	"maxFailedItems":-1,
  	"configuration": 
    {
    "dataToExtract": "contentAndMetadata",
    "imageAction": "generateNormalizedImages"
    }
  }
}

示例：使用托管标识连接扩充缓存

此示例演示了使用 Azure Active Directory 进行身份验证时的连接字符串格式。搜索服务必须配置为使用托管标识。标识必须具有“存储 Blob 数据参与者”权限，以便它可以写入缓存。连接字符串是存储帐户的唯一资源 ID，它必须包含用于存储缓存扩充的容器。

{
  "name":"demo-indexer",
  "dataSourceName" : "demodata-ds",
  "targetIndexName" : "demo-index",
  "skillsetName" : "demo-skillset",
  "cache" : 
    {
      "storageConnectionString" : "ResourceId=/subscriptions/<subscription-ID>/resourceGroups/<resource-group-name>/providers/Microsoft.Storage/storageAccounts/<storage-account-name>/<container-name>;",
      "enableReprocessing": true
    },
  "fieldMappings" : [  ],
  "outputFieldMappings" :  [  ],
  "parameters": {  }
}

定义

链接	描述
缓存	为 AI 扩充和技能集执行配置缓存。
encryptionKey	配置到 Azure Key Vault 的连接，以便进行客户管理的加密。
fieldMappings	按名称和类型不匹配的字段的源到目标字段映射。
outputFieldMappings	将扩充文档中的节点映射到索引中的字段。如果使用技能集，则是必需的。
参数	配置索引器。参数包括常规参数和特定于源的参数。
计划	指定计划的索引器执行的间隔和频率。

cache （预览版）

增量索引处理技能集时，能够在缓存中重复使用扩充的文档。最常见的方案是重复使用 OCR 或图像文件的图像分析，这可能非常昂贵且耗时。

"cache" : 
  {
    "storageConnectionString" : "<YOUR-STORAGE-ACCOUNT-CONNECTION-STRING>",
    "enableReprocessing": true
  }

缓存对象具有必需属性和可选属性。

财产	描述
storageConnectionString	必填。指定用于缓存中间结果的存储帐户。使用提供的帐户，搜索服务将创建一个以 `ms-az-search-indexercache` 为前缀的 Blob 容器，并使用索引器唯一的 GUID 完成。对于使用 Azure AD 进行身份验证的请求，必须将其设置为包含密钥的完全访问连接字符串或存储帐户的唯一资源 ID。若要通过 Azure AD 进行身份验证，必须将搜索服务配置为使用托管标识，并且该标识必须具有“存储 Blob 数据参与者”权限。
enableReprocessing	自选。布尔属性（默认情况下`true`），用于控制对缓存中已表示的传入文档的处理。当 `true`（默认值）时，重新运行索引器时，缓存中已有的文档将重新处理，假设技能更新会影响该文档。`false`时，不会重新处理现有文档，从而有效地将新传入的内容优先于现有内容。仅应将 `enableReprocessing` 设置为临时 `false`。为了确保跨库的一致性，`enableReprocessing` 大部分时间都应 `true`，确保所有文档（新文档和现有文档）都根据当前技能集定义有效。
ID	只读。创建缓存后生成。 `ID` 是存储帐户中容器的标识符，该标识符将用作此索引器的缓存。此缓存将对此索引器是唯一的，如果删除索引器并使用同名重新创建索引器，则会重新生成 `ID`。无法设置 `ID`，它始终由服务生成。

附表

索引器可以选择指定计划。如果没有计划，索引器会在发送请求时立即运行：连接到、爬网和为数据源编制索引。对于某些方案（包括长时间运行的索引作业），计划用于将处理窗口扩展到超过 24 小时最大值。如果存在计划，索引器会按计划定期运行。计划程序内置;不能使用外部计划程序。 Schedule 具有以下属性：

间隔：必需。一个持续时间值，该值指定索引器运行的间隔或时间段。允许的最小间隔为 5 分钟;最长的一天。它必须格式化为 XSD“dayTimeDuration”值（ISO 8601 持续时间值的受限子集）。此模式为："P[nD][T[nH][nM]]". 示例：每 15 分钟 PT15M 一次，每 2 小时 PT2H。
startTime：可选。索引器应开始运行的 UTC 日期/时间。

注意

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

参数

索引器可以选择采用修改运行时行为的配置参数。配置参数在索引器请求上以逗号分隔。

{
  "name" : "my-blob-indexer-for-cognitive-search",
  ... other indexer properties
  "parameters" : { 
        "batchSize": null,
        "maxFailedItems": 0,
        "maxFailedItemsPerBatch": 0,
        "base64EncodeKeys": null,
        "configuration" : { 
            "parsingMode" : "json", 
            "indexedFileNameExtensions" : ".json, .jpg, .png", 
            "imageAction" : "generateNormalizedImages", 
            "dataToExtract" : "contentAndMetadata" } }
}

所有索引器的常规参数

参数	类型和允许的值	用法
`"batchSize"`	整数默认值为特定于源（适用于 Azure SQL 数据库和 Azure Cosmos DB 的 1000 个，适用于 Azure Blob 存储的 10 个）	指定从数据源读取并作为单个批处理编制索引的项数，以提高性能。
`"maxFailedItems"`	整数默认值为 0	索引器运行前要容忍的错误数被视为失败。如果不希望任何错误停止索引进程，则设置为 -1。可以使用获取索引器状态检索有关失败项的信息。
`"maxFailedItemsPerBatch"`	整数默认值为 0	在索引器运行被视为失败之前，每个批次中要容忍的错误数。如果不希望任何错误停止索引进程，则设置为 -1。
`"base64EncodeKeys"`	布尔默认值为 true	有效值为 null、true 或 false。设置为 false 时，索引器不会自动对指定为文档键的字段的值进行 base64 编码。设置此属性无需指定 base64 编码在文档键中无效的键值（如短划线）的映射函数。

Blob 配置参数

多个参数是特定索引器的独占参数，例如 Azure blob 索引。

参数	类型和允许的值	用法
`"parsingMode"`	字符串 `"text"` `"delimitedText"` `"json"` `"jsonArray"` `"jsonLines"`	对于 Azure blob，设置为 `text`，以提高 blob 存储中纯文本文件的索引性能。对于 CSV blob，设置为 `delimitedText` blob 是纯 CSV 文件时。对于 JSON blob，设置为 `json` 以提取结构化内容或 `jsonArray` 将数组的各个元素提取为 Azure AI 搜索中的单独文档。使用 `jsonLines` 提取由新行分隔的单个 JSON 实体，作为 Azure AI 搜索中的单独文档。
`"excludedFileNameExtensions"`	字符串逗号分隔列表用户定义的	对于 Azure blob，请忽略列表中的任何文件类型。例如，可以在索引期间排除“.png、.png、.mp4”以跳过这些文件。
`"indexedFileNameExtensions"`	字符串逗号分隔列表用户定义的	对于 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"`	字符串逗号分隔列表用户定义的	对于 CSV blob，指定以逗号分隔的列标题列表，可用于将源字段映射到索引中的目标字段。
`"delimitedTextDelimiter"`	字符串单个字符用户定义的	对于 CSV blob，请为 CSV 文件指定行尾分隔符，其中每行都启动一个新文档（例如，`"\|"`）。
`"firstLineContainsHeaders"`	布尔 true （默认值）假	对于 CSV blob，指示每个 blob 的第一行（非空白）行包含标头。
`"documentRoot"`	字符串用户定义的路径	对于 JSON 数组，给定结构化或半结构化文档，可以使用此属性指定数组的路径。
`"dataToExtract"`	字符串 `"storageMetadata"` `"allMetadata"` `"contentAndMetadata"` （默认值）	对于 Azure blob：设置为 `"storageMetadata"`，仅索引标准 blob 属性和用户指定的元数据。设置为 `"allMetadata"` 以提取 Azure Blob 存储子系统提供的元数据，内容类型特定的元数据（例如，仅 .png 文件特有的元数据）编制索引。设置为 `"contentAndMetadata"`，从每个 Blob 中提取所有元数据和文本内容。对于 AI 扩充中的图像分析，当设置为非的值时，设置会告知索引器要从图像内容中提取哪些数据。适用于.PDF或其他应用程序中的嵌入图像内容，或者 Azure blob 中的 .jpg 和 .png等图像文件。
`"imageAction"`	字符串 `"none"` `"generateNormalizedImages"` `"generateNormalizedImagePerPage"`	对于 Azure blob，设置为`"none"` 忽略数据集中的嵌入图像或图像文件。这是默认值。对于 AI 扩充中的图像分析，设置为从图像中提取文本（例如，流量停止符号中的“停止”一词），并将其嵌入内容字段的一部分。在图像分析期间，索引器会在文档破解过程中创建规范化图像数组，并将生成的信息嵌入内容字段中。此操作要求 `"dataToExtract"` 设置为 `"contentAndMetadata"`。规范化图像是指在视觉搜索结果中包含图像时产生统一图像输出、调整大小和旋转的其他处理，以提升一致的呈现（例如，图形控件中与 JFK 演示中所示的相同大小照片）。使用此选项时，会为每个图像生成此信息。如果设置为 `"generateNormalizedImagePerPage"`，PDF 文件将受到不同的处理，而不是提取嵌入的图像，每个页面将呈现为图像并相应地规范化。将像设置 `"generateNormalizedImages"` 一样对待非 PDF 文件类型。将 `"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"`，`"dataToExtract"` 参数设置为 `"contentAndMetadata"` 或 `"allMetadata"`。
`"pdfTextRotationAlgorithm"`	字符串 `"none"` （默认值） `"detectAngles"`	将 `"pdfTextRotationAlgorithm"` 参数设置为 `"detectAngles"` 可能有助于从已旋转文本的 PDF 文件中生成更好、更易读的文本提取。请注意，使用此参数时，性能速度可能会产生较小的影响。此参数仅适用于 PDF 文件，仅适用于具有嵌入文本的 PDF。如果旋转的文本显示在 PDF 中的嵌入图像中，则此参数不适用。将 `"pdfTextRotationAlgorithm"` 参数设置为 `"detectAngles"` 要求将 `"parsingMode"` 参数设置为 `"default"`。

Azure Cosmos DB 配置参数

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

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

Azure SQL 配置参数

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

参数	类型和允许的值	用法
`"queryTimeout"`	字符串 “hh：mm：ss” "00:05:00"	设置此参数以替代 5 分钟默认值。
`"convertHighWaterMarkToRowVersion"`	布尔	将此参数设置为“true”，以使用高水印列的 rowversion 数据类型。当此属性设置为 true 时，索引器会在索引器运行之前从 rowversion 值中减去一个。这样做是因为具有一对多联接的视图可能有具有重复行version 值的行。减去一个可确保索引器查询不会错过这些行。
`"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 行为。索引编制将更快完成，但权衡是，如果索引器因任何原因中断，则必须完全重复整个索引器作业。

fieldMappings

当源目标字段名称或类型不匹配或想要指定函数时创建这些名称。字段映射不区分大小写。请参阅定义字段映射。

属性	描述
sourceFieldName	必填。源列的名称。
targetFieldName	必填。搜索索引中相应字段的名称。
mappingFunction	自选。将处理添加到路由到搜索引擎的源值。例如，任意字符串值可以进行 base64 编码，以便可用于填充文档键字段。映射函数具有名称和参数。有效值包括： base64Encode base64Decode extractTokenAtPosition jsonArrayToStringCollection urlEncode urlDecode

outputFieldMappings

将技能输出（或扩充树中的节点）指定到搜索索引中的字段。

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

encryptionKey

配置与 Azure Key Vault 的连接，以补充客户管理的加密密钥（CMK）。使用客户管理的密钥进行加密不适用于免费服务。对于计费服务，它仅适用于在 2019-01-01 之后创建的搜索服务。

必须对与密钥保管库的连接进行身份验证。为此，可以使用“accessCredentials”或托管标识。

托管标识可以是系统或用户分配的（预览版）。如果搜索服务同时具有系统分配的托管标识和授予对密钥保管库的读取访问权限的角色分配，则可以省略“标识”和“accessCredentials”，并且请求将使用系统托管标识进行身份验证。如果搜索服务具有用户分配的标识和角色分配，请将“identity”属性设置为该标识的资源 ID。

属性	描述
keyVaultKeyName	必填。用于加密的 Azure Key Vault 密钥的名称。
keyVaultKeyVersion	必填。 Azure Key Vault 密钥的版本。
keyVaultUri	必填。提供密钥的 Azure Key Vault 的 URI（也称为 DNS 名称）。示例 URI 可能是 `https://my-keyvault-name.vault.azure.net`
accessCredentials	如果使用的是托管标识，请省略。否则，`accessCredentials` 的属性包括 `applicationId`（有权访问指定 Azure Key Vault 的 Azure Active Directory 应用程序 ID）和 `applicationSecret`（指定的 Azure AD 应用程序的身份验证密钥）。
身份	可选，除非使用用户分配的托管标识连接到 Azure Key Vault 的搜索服务。格式为 `"/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[managed identity name]"`。

通过