您现在访问的是微软AZURE全睃版技术文档网站,若需覝访问由世纪互蝔违蝥的MICROSOFT AZURE中国区技术文档网站,请访问 https://docs.azure.cn.

创建索引器 (Azure 认知搜索 REST API)

索引从支持的 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-version=2020-06-30 。 有关 更多版本, 请参阅 API 版本。

请求标头

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

字段 说明
Content-Type 必需。 将其设置为 application/json
api-key 必需。 api-key 用于对搜索服务的请求进行身份验证。 它是一个字符串值,对于服务是唯一的。 创建请求必须包含设置为管理密钥的标头 (api-key 而不是查询密钥) 。 可以在 搜索服务仪表板 的搜索服务仪表板中查找 API Azure 门户。

请求正文

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

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

请求包含以下属性:

属性 说明
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 日期时间。
parameters 可选。 用于修改运行时行为的属性。

"batchSize" (整数) 。 指定可从数据源读取并可将其索引编制为单个批次以提高性能的项数。 默认值是特定于源的 (1000 Azure SQL 数据库 Azure Cosmos DB,10 表示 Azure Blob 存储) 。

"maxFailedItems" (整数) 。 指定在索引器运行被视为失败之前允许的错误数。 默认为 0。 如果不希望因任何错误而导致索引编制过程停止,请将此项设置为 -1。 使用 "获取索引器状态 "检索有关失败文档的信息。

"maxFailedItemsPerBatch" (整数) 。 指定在索引器运行被视为失败之前,每批中允许的错误数。 默认为 0。 如果不希望因任何错误而导致索引编制过程停止,请将此项设置为 -1。

"executionEnvironment" (字符串) 。 替代内部系统进程选择的执行环境。 如果索引器通过专用终结点连接访问外部资源,需要将执行环境 Private 显式设置为 。 对于数据输入,此设置仅适用于预配为"基本"或"标准" (S1、S2、S3) 。 对于 AI 扩充内容处理,此设置仅对 S2 和 S3 有效。 此设置位于 "configuration" 部分。 有效值不区分大小写,并且包含 [null 或未指定], Standard (默认值) 或 Private
fieldMappings 可选。 将源字段显式关联到搜索索引中的目标字段。 当源和目标字段具有不同的名称或类型,或者您想要指定一个函数时使用。 fieldMappings部分包含 sourceFieldName (必需、基础数据源中的字段) 、 targetFieldName (必需、索引) 中的字段和编码输出的可选项 mappingFunction 。 可在 字段映射函数中找到支持的函数和示例的列表。 有关更多常规信息,请参阅 字段映射和转换
outputFieldMappings 对于 扩充管道是必需的。 地图从技能组合到索引或投影的输出。 outputFieldMappings部分包含 sourceFieldName (必需、扩充树中的节点) 、 targetFieldName (必需、索引) 中的字段和编码输出的可选项 mappingFunction 。 可在 字段映射函数中找到支持的函数和示例的列表。 有关更多常规信息,请参阅 如何从技能组合映射输出字段
encryptionKey 可选。 用于使用你自己的密钥加密索引器定义,并在 Azure Key Vault 中进行管理。 可用于在2019-01-01 或之后创建的可计费搜索服务。

encryptionKey部分包含所需的用户定义 keyVaultKeyName () 、系统生成的 keyVaultKeyVersion (必需) ,以及 keyVaultUri 提供所需的密钥 ((也称为 DNS 名称) )。 示例 URI 可能为 " https://my-keyvault-name.vault.azure.net "。

还可以指定是否 accessCredentials 使用托管系统标识。 的属性 accessCredentials 包括 applicationId (Azure Active Directory 应用程序 ID 授予对指定的 Azure Key Vault) 的访问权限,以及 (applicationSecret 指定的 Azure AD 应用程序) 的身份验证密钥。 下一节中的示例说明了语法。
disabled 可选。 布尔值,指示是否禁用索引器。 如果希望创建索引器定义而不立即运行它,请设置此属性。 默认值为 False。

Blob 配置参数

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

参数 类型和允许的值 使用情况
"parsingMode" 字符串
"text"
"delimitedText"
"json"
"jsonArray"
"jsonLines"
对于 Azure Blob,设置为 text 可改进 Blob 存储中纯文本文件的索引编制性能。
对于 CSV Blob,请在 Blob 为纯 CSV 文件时设置为 delimitedText
对于 JSON blob,将设置为 json 以提取结构化内容,或设置为,以将 jsonArray 数组中的单个元素作为单独的文档提取到 Azure 认知搜索中。 使用 jsonLines 提取单独的 JSON 实体,以新行分隔,作为 Azure 认知搜索中的单独文档。
"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 扩充中的图像分析,当 "imageAction" 设置为之外的值时, "none" 设置会 "dataToExtract" 告知索引器要从图像内容中提取的数据。 适用于 .PDF 或其他应用程序中的嵌入图像内容,或者 Azure Blob 中的图像文件(例如 .jpg 和 .png)。
"imageAction" String
"none"
"generateNormalizedImages"
"generateNormalizedImagePerPage"
对于 Azure Blob,设置为 "none" 即可忽略数据集中的嵌入图像或图像文件。 这是默认设置。

对于 AI 扩充中的图像分析,将设置为 "generateNormalizedImages" 以从图像中提取文本 (例如,流量中的 "stop" 一词将停止符号) ,并将其嵌入内容字段。 在图像分析过程中,索引器会在文档破解过程中生成一系列规范化的图像,并将生成的信息嵌入内容字段中。 此操作需要将 "dataToExtract" 设置为 "contentAndMetadata"。 规范化的图像是指在视觉搜索结果中包含图像时,对图像进行额外的处理,使图像的输出一致,并通过调整大小和旋转方向使图像在呈现时更一致(例如,使图像控件中的照片大小一致,如 JFK 演示中所示)。 当使用此选项时,将为每个图像生成此信息。

如果设置为 "generateNormalizedImagePerPage",则将以不同的方式对待 PDF 文件,将不会提取嵌入的图像,而是将每个页面呈现为图像并相应地规范化。 对待非 PDF 文件类型的方式与设置了 "generateNormalizedImages" 时相同。

如果将 "imageAction" 配置设置为之外的任何值,则 "none" 还需要将 技能组合 附加到该索引器。
"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 SQL 配置参数

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

参数 类型和允许的值 使用情况
"queryTimeout" 字符串
"hh:mm:ss"
"00:05:00"
对于 Azure SQL 数据库,可以通过设置此参数使超时超出 5 分钟的默认值。

响应

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

示例

示例:具有 schedule 和泛型参数的索引器

创建一个索引器,该索引器将数据源引用的表中的数据复制 ordersds 到以 orders 1 月1日(UTC)开始2021、每小时运行的计划中的索引。 如果每批中索引失败的项目不超过 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 认知搜索不允许字段名称以下划线开头。 字段映射可以解析名称差异。 源和目标字段名称不区分大小写。 有关详细信息,请参阅字段映射和转换

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

示例:具有 AI 扩充的索引器

演示 AI 扩充,它由对和的引用指示 skillset outputFieldMappings技术集是高级资源,是单独定义的。 此示例是 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 Key Vault 中使用客户托管密钥的加密

{
    "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": "Azure Active Directory Application ID that was granted access permissions to your specified Azure Key Vault",
        "applicationSecret": "Authentication key of the specified Azure AD application)"}
      }
}

另请参阅