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

Indexers - Create Or Update

服务:

Search Service

API 版本:

2024-09-01-preview

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

PUT {endpoint}/indexers('{indexerName}')?api-version=2024-09-01-preview

具有可选参数:

PUT {endpoint}/indexers('{indexerName}')?api-version=2024-09-01-preview&ignoreResetRequirements={ignoreResetRequirements}&disableCacheReprocessingChangeDetection={disableCacheReprocessingChangeDetection}

URI 参数

名称	在	必需	类型	说明
endpoint	path	True	string	搜索服务的终结点 URL。
indexerName	path	True	string	要创建或更新的索引器的名称。
api-version	query	True	string	客户端 API 版本。
disableCacheReprocessingChangeDetection	query		boolean	禁用缓存重新处理更改检测。
ignoreResetRequirements	query		boolean	忽略缓存重置要求。

请求头

名称	必需	类型	说明
x-ms-client-request-id		string uuid	随请求一起发送的跟踪 ID，以帮助进行调试。
If-Match		string	定义 If-Match 条件。 仅当服务器上的 ETag 与此值匹配时，才会执行该操作。
If-None-Match		string	定义 If-None-Match 条件。 仅当服务器上的 ETag 与此值不匹配时，才会执行该操作。
Prefer	True	string	对于 HTTP PUT 请求，指示服务在成功时返回已创建/更新的资源。

请求正文

名称	必需	类型	说明
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	错误响应。

示例

SearchServiceCreateOrUpdateIndexer

示例请求

HTTP

PUT https://previewexampleservice.search.windows.net/indexers('myindexer')?api-version=2024-09-01-preview&ignoreResetRequirements=&disableCacheReprocessingChangeDetection=





{
  "name": "myindexer",
  "description": "Description of the indexer",
  "dataSourceName": "mydocdbdatasource",
  "skillsetName": "myskillset",
  "targetIndexName": "preview-test",
  "schedule": {
    "interval": "P1D"
  },
  "parameters": {
    "maxFailedItems": 10,
    "maxFailedItemsPerBatch": 5
  },
  "fieldMappings": [],
  "outputFieldMappings": [],
  "disabled": false,
  "encryptionKey": {
    "keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
    "keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
    "keyVaultUri": "https://myKeyVault.vault.azure.net",
    "accessCredentials": {
      "applicationId": "00000000-0000-0000-0000-000000000000",
      "applicationSecret": "<applicationSecret>"
    }
  }
}

示例响应

状态代码:

201

{
  "@odata.etag": "0x1234568AE7E58A1",
  "name": "myindexer",
  "description": "Description of the indexer",
  "dataSourceName": "mydocdbdatasource",
  "skillsetName": "myskillset",
  "targetIndexName": "preview-test",
  "disabled": false,
  "schedule": {
    "interval": "P1D",
    "startTime": "2024-06-06T00:01:50.265Z"
  },
  "parameters": {
    "maxFailedItems": 10,
    "maxFailedItemsPerBatch": 5,
    "configuration": {}
  },
  "fieldMappings": [],
  "outputFieldMappings": [],
  "encryptionKey": {
    "keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
    "keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
    "keyVaultUri": "https://myKeyVault.vault.azure.net",
    "accessCredentials": {
      "applicationId": "00000000-0000-0000-0000-000000000000",
      "applicationSecret": "<applicationSecret>"
    }
  }
}

状态代码:

200

{
  "@odata.etag": "0x1234568AE7E58A1",
  "name": "myindexer",
  "description": "Description of the indexer",
  "dataSourceName": "mydocdbdatasource",
  "skillsetName": "myskillset",
  "targetIndexName": "preview-test",
  "disabled": false,
  "schedule": {
    "interval": "P1D",
    "startTime": "2024-06-06T00:01:50.265Z"
  },
  "parameters": {
    "maxFailedItems": 10,
    "maxFailedItemsPerBatch": 5,
    "configuration": {}
  },
  "fieldMappings": [],
  "outputFieldMappings": [],
  "encryptionKey": {
    "keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
    "keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
    "keyVaultUri": "https://myKeyVault.vault.azure.net",
    "accessCredentials": {
      "applicationId": "00000000-0000-0000-0000-000000000000",
      "applicationSecret": "<applicationSecret>"
    }
  }
}

定义

名称	说明
AzureActiveDirectoryApplicationCredentials	为搜索服务创建的已注册应用程序的凭据，用于对 Azure Key Vault 中存储的加密密钥进行身份验证的访问权限。
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	错误响应
FieldMapping	定义数据源中的字段与索引中目标字段之间的映射。
FieldMappingFunction	表示在编制索引之前从数据源转换值的函数。
IndexerExecutionEnvironment	指定索引器应在其中执行的环境。
IndexingParameters	表示索引器执行的参数。
IndexingParametersConfiguration	特定于索引器的配置属性的字典。 每个名称都是特定属性的名称。 每个值都必须是基元类型。
IndexingSchedule	表示索引器执行的计划。
SearchIndexer	表示索引器。
SearchIndexerCache
SearchIndexerDataNoneIdentity	清除数据源的标识属性。
SearchIndexerDataUserAssignedIdentity	指定要使用的数据源的标识。
SearchResourceEncryptionKey	Azure Key Vault 中的客户管理的加密密钥。 创建和管理的密钥可用于加密或解密静态数据，例如索引和同义词映射。

AzureActiveDirectoryApplicationCredentials

为搜索服务创建的已注册应用程序的凭据，用于对 Azure Key Vault 中存储的加密密钥进行身份验证的访问权限。

名称	类型	说明
applicationId	string	向 AAD 应用程序 ID 授予对静态数据加密时要使用的 Azure Key Vault 所需的访问权限。 应用程序 ID 不应与 AAD 应用程序的对象 ID 混淆。
applicationSecret	string	指定的 AAD 应用程序的身份验证密钥。

BlobIndexerDataToExtract

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

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

BlobIndexerImageAction

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

名称	类型	说明
generateNormalizedImagePerPage	string	从图像中提取文本（例如，从流量停止标志中提取“STOP”一词），并将其嵌入内容字段中，但以不同的方式将 PDF 文件呈现为图像并相应地规范化，而不是提取嵌入的图像。 将像设置“generateNormalizedImages”一样对待非 PDF 文件类型。
generateNormalizedImages	string	从图像中提取文本（例如，从流量停止标志中提取“STOP”一词），并将其嵌入内容字段中。 此操作要求“dataToExtract”设置为“contentAndMetadata”。 规范化图像是指在视觉搜索结果中包含图像时生成统一图像输出、调整大小和旋转的其他处理，以提升一致的呈现。 使用此选项时，会为每个图像生成此信息。
none	string	忽略数据集中的嵌入图像或图像文件。 这是默认值。

BlobIndexerParsingMode

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

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

BlobIndexerPDFTextRotationAlgorithm

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

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

ErrorAdditionalInfo

资源管理错误附加信息。

名称	类型	说明
info	object	其他信息。
type	string	其他信息类型。

ErrorDetail

错误详细信息。

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

ErrorResponse

错误响应

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

FieldMapping

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

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

FieldMappingFunction

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

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

IndexerExecutionEnvironment

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

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

IndexingParameters

表示索引器执行的参数。

名称	类型	默认值	说明
batchSize	integer		从数据源读取并作为单个批处理编制索引的项数，以提高性能。 默认值取决于数据源类型。
configuration	IndexingParametersConfiguration		特定于索引器的配置属性的字典。 每个名称都是特定属性的名称。 每个值都必须是基元类型。
maxFailedItems	integer	0	索引器执行索引失败的最大项数仍被视为成功。 -1 表示没有限制。 默认值为 0。
maxFailedItemsPerBatch	integer	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”上，以专门包括这些文件类型。
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	索引器执行之间的时间间隔。
startTime	string	索引器应开始运行的时间。

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	指定是否启用增量重新处理。
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-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentity/myId”的形式分配给搜索服务。

SearchResourceEncryptionKey

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

名称	类型	说明
accessCredentials	AzureActiveDirectoryApplicationCredentials	用于访问 Azure Key Vault 的可选 Azure Active Directory 凭据。 如果改用托管标识，则不需要。
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。