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

Indexers - Create Or Update

服务:: Search Service

API 版本:: 2025-11-01-preview

创建新的索引器或更新索引器（如果已存在）。

PUT https:///indexers('{indexerName}')?api-version=2025-11-01-preview

具有可选参数:

PUT https:///indexers('{indexerName}')?api-version=2025-11-01-preview&ignoreResetRequirements={ignoreResetRequirements}&disableCacheReprocessingChangeDetection={disableCacheReprocessingChangeDetection}

URI 参数

名称	在	必需	类型	说明
indexerName	path	True	string	索引器的名称。
api-version	query	True	string minLength: 1	要用于此操作的 API 版本。
disableCacheReprocessingChangeDetection	query		boolean	禁用缓存重新处理更改检测。
ignoreResetRequirements	query		boolean	忽略缓存重置要求。

请求头

名称	必需	类型	说明
Accept	True	Accept	接受（Accept）首部。
If-Match		string	定义 If-Match 条件。仅当服务器上的 ETag 与此值匹配时，才会执行该作。
If-None-Match		string	定义 If-None-Match 条件。仅当服务器上的 ETag 与此值不匹配时，才会执行该作。
Prefer	True	Prefer	对于 HTTP PUT 请求，指示服务在成功时返回创建/更新的资源。
x-ms-client-request-id		string (uuid)	请求的不透明、全局唯一的客户端生成的字符串标识符。

请求正文

名称	必需	类型	说明
dataSourceName	True	string	此索引器从中读取数据的数据源的名称。
name	True	string	索引器的名称。
targetIndexName	True	string	此索引器向其写入数据的索引的名称。
@odata.etag		string	索引器的 ETag。
cache		SearchIndexerCache	将缓存添加到扩充管道，以允许增量修改步骤，而无需每次重新生成索引。
description		string	索引器的说明。
disabled		boolean	一个值，该值指示是否禁用索引器。默认值为 false。
encryptionKey		SearchResourceEncryptionKey	描述在 Azure Key Vault 中创建的加密密钥。当你希望完全保证任何人（甚至 Microsoft）都无法解密索引器时，此密钥用于为索引器定义（以及索引器执行状态）提供额外的静态加密级别。加密索引器定义后，它将始终保持加密状态。搜索服务将忽略将此属性设置为 null 的尝试。如果需要轮换加密密钥，可以根据需要更改此属性;索引器定义（和索引器执行状态）将不受影响。使用客户管理的密钥加密不适用于免费搜索服务，并且仅适用于在 2019 年 1 月 1 日或之后创建的付费服务。
fieldMappings		FieldMapping[]	定义数据源中的字段与索引中相应目标字段之间的映射。
outputFieldMappings		FieldMapping[]	输出字段映射在扩充后应用，并在编制索引之前立即应用。
parameters		IndexingParameters	索引器执行的参数。
schedule		IndexingSchedule	此索引器的计划。
skillsetName		string	使用此索引器执行的技能集的名称。

响应

名称	类型	说明
200 OK	SearchIndexer	请求已成功。
201 Created	SearchIndexer	请求已成功，因此创建了一个新资源。
Other Status Codes	ErrorResponse	意外错误响应。

安全性

api-key

类型: apiKey
在: header

OAuth2Auth

类型: oauth2
流向: implicit
授权 URL: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

作用域

名称	说明
https://search.azure.com/.default

示例

SearchServiceCreateOrUpdateIndexer

示例请求

HTTP

PUT https:///indexers('myaclindexer')?api-version=2025-11-01-preview&ignoreResetRequirements=&disableCacheReprocessingChangeDetection=





{
  "name": "myaclindexer",
  "description": "Description of the indexer",
  "dataSourceName": "indexertestacldatasource",
  "targetIndexName": "indexer-test-index",
  "schedule": {
    "interval": "P1D",
    "startTime": "2025-01-07T19:30:00Z"
  },
  "parameters": {
    "batchSize": 10,
    "maxFailedItems": 10,
    "maxFailedItemsPerBatch": 5
  },
  "fieldMappings": [
    {
      "sourceFieldName": "metadata_storage_title",
      "targetFieldName": "name",
      "mappingFunction": {
        "name": "base64Encode"
      }
    },
    {
      "sourceFieldName": "metadata_user_ids",
      "targetFieldName": "permissionFilters"
    }
  ],
  "outputFieldMappings": [
    {
      "sourceFieldName": "/document",
      "targetFieldName": "name",
      "mappingFunction": {
        "name": "base64Encode"
      }
    }
  ],
  "disabled": false,
  "@odata.etag": "0x1234568AE7E58A1"
}

示例响应

状态代码:: 201

{
  "@odata.etag": "0x1234568AE7E58A1",
  "name": "myaclindexer",
  "description": "Description of the indexer",
  "dataSourceName": "indexertestacldatasource",
  "targetIndexName": "indexer-test-index",
  "disabled": false,
  "schedule": {
    "interval": "P1D",
    "startTime": "2024-06-06T00:01:50.265Z"
  },
  "parameters": {
    "batchSize": 10,
    "maxFailedItems": 10,
    "maxFailedItemsPerBatch": 5,
    "configuration": {}
  },
  "fieldMappings": [
    {
      "sourceFieldName": "metadata_storage_title",
      "targetFieldName": "name",
      "mappingFunction": {
        "name": "base64Encode"
      }
    },
    {
      "sourceFieldName": "metadata_user_ids",
      "targetFieldName": "permissionFilters"
    }
  ],
  "outputFieldMappings": [
    {
      "sourceFieldName": "/document",
      "targetFieldName": "name",
      "mappingFunction": {
        "name": "base64Encode"
      }
    }
  ]
}

状态代码:: 200

{
  "@odata.etag": "0x1234568AE7E58A1",
  "name": "myaclindexer",
  "description": "Description of the indexer",
  "dataSourceName": "indexertestacldatasource",
  "targetIndexName": "indexer-test-index",
  "disabled": false,
  "schedule": {
    "interval": "P1D",
    "startTime": "2024-06-06T00:01:50.265Z"
  },
  "parameters": {
    "batchSize": 10,
    "maxFailedItems": 10,
    "maxFailedItemsPerBatch": 5,
    "configuration": {}
  },
  "fieldMappings": [
    {
      "sourceFieldName": "metadata_storage_title",
      "targetFieldName": "name",
      "mappingFunction": {
        "name": "base64Encode"
      }
    },
    {
      "sourceFieldName": "metadata_user_ids",
      "targetFieldName": "permissionFilters"
    }
  ],
  "outputFieldMappings": [
    {
      "sourceFieldName": "/document",
      "targetFieldName": "name",
      "mappingFunction": {
        "name": "base64Encode"
      }
    }
  ]
}

定义

名称	说明
Accept	接受（Accept）首部。
BlobIndexerDataToExtract	指定要从 Azure Blob 存储中提取的数据，并告知索引器在将“imageAction”设置为“none”以外的值时要从图像内容中提取哪些数据。这适用于 .PDF 或其他应用程序中的嵌入图像内容，或 Azure blob 中的图像文件（如 .jpg 和 .png）。
BlobIndexerImageAction	确定如何处理 Azure Blob 存储中的嵌入图像和图像文件。将“imageAction”配置设置为“none”以外的任何值都需要将技能组附加到该索引器。
BlobIndexerParsingMode	表示从 Azure blob 数据源编制索引的分析模式。
BlobIndexerPDFTextRotationAlgorithm	确定从 Azure Blob 存储中的 PDF 文件提取文本的算法。
ErrorAdditionalInfo	资源管理错误附加信息。
ErrorDetail	错误详细信息。
ErrorResponse	所有 Azure 资源管理器 API 的常见错误响应，以返回失败操作的错误详细信息。（这也遵循 OData 错误响应格式）。
FieldMapping	定义数据源中的字段与索引中目标字段之间的映射。
FieldMappingFunction	表示在编制索引之前从数据源转换值的函数。
IndexerExecutionEnvironment	指定应在其中执行索引器的环境。
IndexingParameters	表示索引器执行的参数。
IndexingParametersConfiguration	特定于索引器的配置属性的字典。每个名称都是特定属性的名称。每个值都必须是基元类型。
IndexingSchedule	表示索引器执行的计划。
Prefer	对于 HTTP PUT 请求，指示服务在成功时返回创建/更新的资源。
SearchIndexer	表示索引器。
SearchIndexerCache	宝藏的类型。
SearchIndexerDataNoneIdentity	清除数据源的标识属性。
SearchIndexerDataUserAssignedIdentity	指定要使用的数据源的标识。
SearchResourceEncryptionKey	Azure Key Vault 中的客户管理的加密密钥。创建和管理的密钥可用于加密或解密静态数据，例如索引和同义词映射。

Accept

枚举

接受（Accept）首部。

值	说明
application/json;odata.metadata=minimal

BlobIndexerDataToExtract

枚举

指定要从 Azure Blob 存储中提取的数据，并告知索引器在将“imageAction”设置为“none”以外的值时要从图像内容中提取哪些数据。这适用于 .PDF 或其他应用程序中的嵌入图像内容，或 Azure blob 中的图像文件（如 .jpg 和 .png）。

值	说明
storageMetadata	仅为标准 blob 属性和用户指定的元数据编制索引。
allMetadata	提取 Azure Blob 存储子系统提供的元数据和特定于内容类型的元数据（例如，仅对 .png 文件进行索引）。
contentAndMetadata	从每个 blob 中提取所有元数据和文本内容。

BlobIndexerImageAction

枚举

确定如何处理 Azure Blob 存储中的嵌入图像和图像文件。将“imageAction”配置设置为“none”以外的任何值都需要将技能组附加到该索引器。

值	说明
none	忽略数据集中的嵌入图像或图像文件。这是默认情况。
generateNormalizedImages	从图像中提取文本（例如，交通停止标志中的单词“STOP”），并将其嵌入到内容字段中。此作要求将“dataToExtract”设置为“contentAndMetadata”。规范化图像是指在视觉搜索结果中包含图像时，产生统一的图像输出、大小和旋转的附加处理，以促进一致的呈现。使用此选项时，会为每个图像生成此信息。
generateNormalizedImagePerPage	从图像中提取文本（例如，交通停车标志中的单词“STOP”），并将其嵌入到内容字段中，但对 PDF 文件的处理方式不同，因为每个页面都将呈现为图像并相应地进行规范化，而不是提取嵌入的图像。非 PDF 文件类型的处理方式与设置了“generateNormalizedImages”相同。

BlobIndexerParsingMode

枚举

表示从 Azure blob 数据源编制索引的分析模式。

值	说明
default	设置为正常文件处理的默认值。
text	设置为文本可提高 Blob 存储中纯文本文件的索引性能。
delimitedText	当 blob 是纯 CSV 文件时，设置为 delimitedText。
json	设置为 json 以从 JSON 文件中提取结构化内容。
jsonArray	设置为 jsonArray 以将 JSON 数组的各个元素提取为单独的文档。
jsonLines	设置为 jsonLines 以提取由换行符分隔的单个 JSON 实体作为单独的文档。
markdown	设置为 markdown 以从 markdown 文件中提取内容。

BlobIndexerPDFTextRotationAlgorithm

枚举

确定从 Azure Blob 存储中的 PDF 文件提取文本的算法。

值	说明
none	利用普通文本提取。这是默认情况。
detectAngles	可以从具有旋转文本的 PDF 文件中生成更好、更易读的文本提取。请注意，使用此参数时，可能会对性能速度产生较小的影响。此参数仅适用于 PDF 文件，并且仅适用于嵌入文本的 PDF。如果旋转的文本出现在 PDF 的嵌入图像中，则此参数不适用。

ErrorAdditionalInfo

对象

资源管理错误附加信息。

名称	类型	说明
info		附加信息。
type	string	附加信息类型。

ErrorDetail

对象

错误详细信息。

名称	类型	说明
additionalInfo	ErrorAdditionalInfo[]	错误附加信息。
code	string	错误代码。
details	ErrorDetail[]	错误详细信息。
message	string	错误消息。
target	string	错误目标。

ErrorResponse

对象

所有 Azure 资源管理器 API 的常见错误响应，以返回失败操作的错误详细信息。（这也遵循 OData 错误响应格式）。

名称	类型	说明
error	ErrorDetail	错误对象。

FieldMapping

对象

定义数据源中的字段与索引中目标字段之间的映射。

名称	类型	说明
mappingFunction	FieldMappingFunction	在编制索引之前应用于每个源字段值的函数。
sourceFieldName	string	数据源中字段的名称。
targetFieldName	string	索引中目标字段的名称。默认情况下，与源字段名称相同。

FieldMappingFunction

对象

表示在编制索引之前从数据源转换值的函数。

名称	类型	说明
name	string	字段映射函数的名称。
parameters		要传递给函数的参数名称/值对的字典。每个值都必须是基元类型。

IndexerExecutionEnvironment

枚举

指定应在其中执行索引器的环境。

值	说明
standard	指示搜索服务可以确定索引器应在何处执行。这是未指定任何内容时的默认环境，并且是推荐值。
private	指示索引器应使用专门为搜索服务预配的环境运行。仅当索引器需要通过共享专用链接资源安全地访问资源时，才应将其指定为执行环境。

IndexingParameters

对象

表示索引器执行的参数。

名称	类型	默认值	说明
batchSize	integer (int32)		从数据源读取并作为单个批处理编制索引以提高性能的项数。默认值取决于数据源类型。
configuration	IndexingParametersConfiguration		特定于索引器的配置属性的字典。每个名称都是特定属性的名称。每个值都必须是基元类型。
maxFailedItems	integer (int32)	0	索引器执行可能无法编制索引的最大项数仍被视为成功。 -1 表示没有限制。默认为 0。
maxFailedItemsPerBatch	integer (int32)	0	单个批次中可能无法编制索引的最大项数，以便该批处理仍被视为成功。 -1 表示没有限制。默认为 0。

IndexingParametersConfiguration

对象

特定于索引器的配置属性的字典。每个名称都是特定属性的名称。每个值都必须是基元类型。

名称	类型	默认值	说明
allowSkillsetToReadFileData	boolean	False	如果为 true，将创建一个路径 //document//file_data，该路径是一个对象，表示从 blob 数据源下载的原始文件数据。这允许您将原始文件数据传递到自定义技能以在扩充管道中进行处理，或传递到文档提取技能。
dataToExtract	BlobIndexerDataToExtract	contentAndMetadata	指定要从 Azure Blob 存储中提取的数据，并告知索引器在将“imageAction”设置为“none”以外的值时要从图像内容中提取哪些数据。这适用于 .PDF 或其他应用程序中的嵌入图像内容，或 Azure blob 中的图像文件（如 .jpg 和 .png）。
delimitedTextDelimiter	string		对于 CSV blob，指定 CSV 文件的行尾单字符分隔符，其中每一行开始一个新文档（例如，“\|”）。
delimitedTextHeaders	string		对于 CSV blob，指定以逗号分隔的列标题列表，这对于将源字段映射到索引中的目标字段非常有用。
documentRoot	string		对于 JSON 数组，给定结构化或半结构化文档，您可以使用此属性指定数组的路径。
excludedFileNameExtensions	string		从 Azure Blob 存储处理时要忽略的文件扩展名的逗号分隔列表。例如，您可以排除“.png， .mp4”以在索引期间跳过这些文件。
executionEnvironment	IndexerExecutionEnvironment	standard	指定应在其中执行索引器的环境。
failOnUnprocessableDocument	boolean	False	对于 Azure Blob，如果要在文档编制索引失败时继续编制索引，请设置为 false。
failOnUnsupportedContentType	boolean	False	对于 Azure Blob，如果要在遇到不受支持的内容类型时继续编制索引，并且事先不知道所有内容类型（文件扩展名），请设置为 false。
firstLineContainsHeaders	boolean	True	对于 CSV blob，指示每个 blob 的第一行（非空白）包含标头。
imageAction	BlobIndexerImageAction	none	确定如何处理 Azure Blob 存储中的嵌入图像和图像文件。将“imageAction”配置设置为“none”以外的任何值都需要将技能组附加到该索引器。
indexStorageMetadataOnlyForOversizedDocuments	boolean	False	对于 Azure Blob，请将此属性设置为 true，以仍为太大而无法处理的 Blob 内容编制存储元数据索引。过大的 blob 会被默认视为错误。有关 blob 大小的限制，请参阅 https://learn.microsoft.com/azure/search/search-limits-quotas-capacity。
indexedFileNameExtensions	string		从 Azure Blob 存储进行处理时要选择的文件扩展名的逗号分隔列表。例如，您可以将索引重点放在特定的应用程序文件“.docx、 .pptx、 .msg”上，以专门包括这些文件类型。
markdownHeaderDepth	enum: h1 h2 h3 h4 h5 h6	h6	指定对 Markdown 内容进行分组时将考虑的最大标头深度。默认值为 `h6`。
markdownParsingSubmode	enum: oneToMany oneToOne	oneToMany	指定子模式，用于确定 Markdown 文件是将分析为一个搜索文档还是多个搜索文档。默认值为 `oneToMany`。
parsingMode	BlobIndexerParsingMode	default	表示从 Azure blob 数据源编制索引的分析模式。
pdfTextRotationAlgorithm	BlobIndexerPDFTextRotationAlgorithm	none	确定从 Azure Blob 存储中的 PDF 文件提取文本的算法。
queryTimeout	string	00:05:00	将超时增加到 Azure SQL 数据库数据源的默认值 5 分钟之外，以“hh：mm：ss”格式指定。

IndexingSchedule

对象

表示索引器执行的计划。

名称	类型	说明
interval	string (duration)	索引器执行之间的时间间隔。
startTime	string (date-time)	索引器应开始运行的时间。

Prefer

枚举

对于 HTTP PUT 请求，指示服务在成功时返回创建/更新的资源。

值	说明
return=representation

SearchIndexer

对象

表示索引器。

名称	类型	默认值	说明
@odata.etag	string		索引器的 ETag。
cache	SearchIndexerCache		将缓存添加到扩充管道，以允许增量修改步骤，而无需每次重新生成索引。
dataSourceName	string		此索引器从中读取数据的数据源的名称。
description	string		索引器的说明。
disabled	boolean	False	一个值，该值指示是否禁用索引器。默认值为 false。
encryptionKey	SearchResourceEncryptionKey		描述在 Azure Key Vault 中创建的加密密钥。当你希望完全保证任何人（甚至 Microsoft）都无法解密索引器时，此密钥用于为索引器定义（以及索引器执行状态）提供额外的静态加密级别。加密索引器定义后，它将始终保持加密状态。搜索服务将忽略将此属性设置为 null 的尝试。如果需要轮换加密密钥，可以根据需要更改此属性;索引器定义（和索引器执行状态）将不受影响。使用客户管理的密钥加密不适用于免费搜索服务，并且仅适用于在 2019 年 1 月 1 日或之后创建的付费服务。
fieldMappings	FieldMapping[]		定义数据源中的字段与索引中相应目标字段之间的映射。
name	string		索引器的名称。
outputFieldMappings	FieldMapping[]		输出字段映射在扩充后应用，并在编制索引之前立即应用。
parameters	IndexingParameters		索引器执行的参数。
schedule	IndexingSchedule		此索引器的计划。
skillsetName	string		使用此索引器执行的技能集的名称。
targetIndexName	string		此索引器向其写入数据的索引的名称。

SearchIndexerCache

对象

宝藏的类型。

名称	类型	说明
enableReprocessing	boolean	指定是否启用增量重新处理。
id	string	SearchIndexerCache 的 GUID。
identity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	用于连接到扩充缓存的用户分配托管标识。如果连接字符串指示标识（ResourceId），并且未指定，则使用系统分配的托管标识。对索引器的更新（如果未指定标识）时，该值保持不变。如果设置为“none”，则清除此属性的值。
storageConnectionString	string	将保留缓存数据的存储帐户的连接字符串。

SearchIndexerDataNoneIdentity

对象

清除数据源的标识属性。

名称	类型	说明
@odata.type	string: #Microsoft.Azure.Search.DataNoneIdentity	指定身份类型的 URI 片段。

SearchIndexerDataUserAssignedIdentity

对象

指定要使用的数据源的标识。

名称	类型	说明
@odata.type	string: #Microsoft.Azure.Search.DataUserAssignedIdentity	指定身份类型的 URI 片段。
userAssignedIdentity	string	用户分配的托管标识的完全限定的 Azure 资源 ID，通常采用“/subscriptions/12345678-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId”的形式，应分配给搜索服务。

SearchResourceEncryptionKey

对象

Azure Key Vault 中的客户管理的加密密钥。创建和管理的密钥可用于加密或解密静态数据，例如索引和同义词映射。

名称	类型	说明
accessCredentials.applicationId	string	向 AAD 应用程序 ID 授予对静态数据加密时要使用的 Azure Key Vault 所需的访问权限。应用程序 ID 不应与 AAD 应用程序的对象 ID 混淆。
accessCredentials.applicationSecret	string	指定的 AAD 应用程序的身份验证密钥。
identity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	用于此加密密钥的显式托管标识。如果未指定并且访问凭据属性为 null，则使用系统分配的托管标识。更新资源时，如果未指定显式标识，则保持不变。如果指定了“none”，则清除此属性的值。
keyVaultKeyName	string	用于加密静态数据的 Azure Key Vault 密钥的名称。
keyVaultKeyVersion	string	用于加密静态数据的 Azure Key Vault 密钥的版本。
keyVaultUri	string	Azure Key Vault 的 URI（也称为 DNS 名称），其中包含用于加密静态数据的密钥。示例 URI 可能是 `https://my-keyvault-name.vault.azure.net`。

通过