Indexers - Create

服務:

Search Service

API 版本:

2026-04-01

建立新的索引子。

POST {endpoint}/indexers?api-version=2026-04-01

URI 參數

名稱	位於	必要	類型	Description
endpoint	path	True	string (uri)	搜尋服務的端點 URL。
api-version	query	True	string minLength: 1	用於此作業的 API 版本。

要求標頭

名稱	必要	類型	Description
Accept		Accept	接受標頭。
x-ms-client-request-id		string (uuid)	一個不透明、全域唯一、由客戶端產生的請求字串識別碼。

要求本文

名稱	必要	類型	Description
dataSourceName	True	string	這個索引器從中讀取數據的數據源名稱。
name	True	string	索引子的名稱。
targetIndexName	True	string	這個索引器寫入數據的索引名稱。
@odata.etag		string	索引器 ETag。
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	使用此索引器執行的技能集名稱。

回應

名稱	類型	Description
201 Created	SearchIndexer	要求已成功，因此已建立新的資源。
Other Status Codes	ErrorResponse	未預期的錯誤回應。

安全性

api-key

類型: apiKey
位於: header

OAuth2Auth

類型: oauth2
Flow: implicit
授權 URL: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

範圍

名稱	Description
https://search.azure.com/.default

範例

SearchServiceCreateIndexer

範例要求

HTTP

POST https://exampleservice.search.windows.net/indexers?api-version=2026-04-01


{
  "name": "myindexer",
  "description": "Description of the indexer",
  "dataSourceName": "indexertestdatasource",
  "skillsetName": "myskillset",
  "targetIndexName": "example-index",
  "schedule": {
    "interval": "P1D",
    "startTime": "2025-01-07T19:30:00Z"
  },
  "parameters": {
    "batchSize": 10,
    "maxFailedItems": 10,
    "maxFailedItemsPerBatch": 5,
    "configuration": {
      "parsingMode": "markdown",
      "excludedFileNameExtensions": ".png,.mp4",
      "indexedFileNameExtensions": ".docx,.pptx",
      "failOnUnsupportedContentType": true,
      "failOnUnprocessableDocument": false,
      "indexStorageMetadataOnlyForOversizedDocuments": true,
      "delimitedTextHeaders": "Header1,Header2",
      "delimitedTextDelimiter": "|",
      "firstLineContainsHeaders": true,
      "markdownParsingSubmode": "oneToMany",
      "markdownHeaderDepth": "h6",
      "documentRoot": "/root",
      "dataToExtract": "storageMetadata",
      "imageAction": "none",
      "allowSkillsetToReadFileData": false,
      "pdfTextRotationAlgorithm": "none",
      "executionEnvironment": "standard"
    }
  },
  "fieldMappings": [
    {
      "sourceFieldName": "/document",
      "targetFieldName": "name",
      "mappingFunction": {
        "name": "base64Encode"
      }
    }
  ],
  "outputFieldMappings": [
    {
      "sourceFieldName": "/document",
      "targetFieldName": "name",
      "mappingFunction": {
        "name": "base64Encode"
      }
    }
  ],
  "disabled": false,
  "@odata.etag": "0x1234568AE7E58A1"
}

範例回覆

狀態碼:

201

{
  "@odata.etag": "0x1234568AE7E58A1",
  "name": "myindexer",
  "description": "Description of the indexer",
  "dataSourceName": "indexertestdatasource",
  "skillsetName": "myskillset",
  "targetIndexName": "example-index",
  "disabled": false,
  "schedule": {
    "interval": "P1D",
    "startTime": "2024-06-06T00:01:50.265Z"
  },
  "parameters": {
    "batchSize": 10,
    "maxFailedItems": 10,
    "maxFailedItemsPerBatch": 5,
    "configuration": {
      "parsingMode": "markdown",
      "excludedFileNameExtensions": ".png,.mp4",
      "indexedFileNameExtensions": ".docx,.pptx",
      "failOnUnsupportedContentType": true,
      "failOnUnprocessableDocument": false,
      "indexStorageMetadataOnlyForOversizedDocuments": true,
      "delimitedTextHeaders": "Header1,Header2",
      "delimitedTextDelimiter": "|",
      "firstLineContainsHeaders": true,
      "markdownParsingSubmode": "oneToMany",
      "markdownHeaderDepth": "h6",
      "documentRoot": "/root",
      "dataToExtract": "storageMetadata",
      "imageAction": "none",
      "allowSkillsetToReadFileData": false,
      "pdfTextRotationAlgorithm": "none",
      "executionEnvironment": "standard"
    }
  },
  "fieldMappings": [
    {
      "sourceFieldName": "/document",
      "targetFieldName": "name",
      "mappingFunction": {
        "name": "base64Encode"
      }
    }
  ],
  "outputFieldMappings": [
    {
      "sourceFieldName": "/document",
      "targetFieldName": "name",
      "mappingFunction": {
        "name": "base64Encode"
      }
    }
  ]
}

定義

名稱	Description
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 Resource Manager API 的常見錯誤回應，用於回傳失敗操作的錯誤細節。 （這也遵循 OData 錯誤回應格式。）。
FieldMapping	定義數據源中的欄位與索引中目標欄位之間的對應。
FieldMappingFunction	表示在編製索引之前，從數據源轉換值的函式。
IndexerExecutionEnvironment	指定索引子應該執行的環境。
IndexingParameters	表示索引器執行的參數。
IndexingParametersConfiguration	索引器特定組態屬性的字典。 每個名稱都是特定屬性的名稱。 每個值都必須是基本類型。
IndexingSchedule	表示索引器執行的排程。
SearchIndexer	表示索引器。
SearchIndexerDataNoneIdentity	清除資料源的識別屬性。
SearchIndexerDataUserAssignedIdentity	指定要使用之數據源的身分識別。
SearchResourceEncryptionKey	Azure Key Vault 中客戶管理的加密密鑰。 您建立和管理的金鑰可用來加密或解密靜態資料，例如索引和同義字對映。

Accept

列舉型別

接受標頭。

值	Description
application/json;odata.metadata=minimal

BlobIndexerDataToExtract

列舉型別

指定要從 Azure Blob 儲存體擷取的資料，並告知索引子在 “imageAction” 設定為 “none” 以外的值時要從影像內容擷取哪些資料。 這適用於 .PDF 或其他應用程式中的內嵌影像內容，或 Azure Blob 中的影像檔案，例如 .jpg 和 .png。

值	Description
storageMetadata	只編製標準 Blob 屬性和使用者指定元數據的索引。
allMetadata	擷取 Azure Blob 記憶體子系統和內容類型特定元數據所提供的元數據（例如，只編制 .png 檔案索引的唯一元數據）。
contentAndMetadata	從每個 Blob 擷取所有元數據和文字內容。

BlobIndexerImageAction

列舉型別

決定如何處理 Azure Blob 儲存體中的內嵌影像和影像檔案。 將 “imageAction” 設定設定為 “none” 以外的任何值，也需要將技能組附加至該索引子。

值	Description
none	忽略數據集中的內嵌影像或圖像檔案。 此為預設值。
generateNormalizedImages	從影像擷取文字（例如，流量停止符號中的“STOP”一詞），並將其內嵌至內容字段。 此動作要求 「dataToExtract」 設定為 「contentAndMetadata」。 標準化影像是指當您在視覺搜尋結果中包含影像時，產生統一影像輸出、大小和旋轉的額外處理，以提升一致的轉譯。 當您使用此選項時，會為每個影像產生這項資訊。
generateNormalizedImagePerPage	從影像擷取文字（例如，流量停止符號中的“STOP”一詞），並將它內嵌到內容字段中，但以不同的方式將 PDF 檔案視為影像，並據以正規化，而不是擷取內嵌影像。 如果已設定 「generateNormalizedImages」，則會將非 PDF 檔類型視為相同。

BlobIndexerParsingMode

列舉型別

代表從 Azure Blob 資料來源編製索引的剖析模式。

值	Description
default	針對一般檔案處理，設定為預設值。
text	設定為文字，以改善 Blob 記憶體中純文字檔案的索引編製效能。
delimitedText	當 Blob 是純 CSV 檔案時，設定為 delimitedText。
json	設定為 json，以從 JSON 檔案擷取結構化內容。
jsonArray	設定為 jsonArray 以將 JSON 陣列的個別專案擷取為個別檔。
jsonLines	設定為 jsonLines 以擷取個別 JSON 實體，並以新行分隔為個別檔。
markdown	設定為 markdown 以從 markdown 檔案擷取內容。

BlobIndexerPDFTextRotationAlgorithm

列舉型別

決定從 Azure Blob 儲存體中的 PDF 檔案擷取文字的演算法。

值	Description
none	利用一般文字擷取。 此為預設值。
detectAngles	可能會從已旋轉文字的 PDF 檔案產生更好且更容易閱讀的文字擷取。 請注意，使用此參數時，效能速度可能會影響很小。 此參數僅適用於 PDF 檔案，且僅適用於具有內嵌文字的 PDF。 如果旋轉的文字出現在 PDF 的內嵌影像內，則不適用此參數。

ErrorAdditionalInfo

Object

資源管理錯誤附加資訊。

名稱	類型	Description
info		附加資訊。
type	string	其他資訊類型。

ErrorDetail

Object

錯誤詳細資料。

名稱	類型	Description
additionalInfo	ErrorAdditionalInfo[]	錯誤附加資訊。
code	string	錯誤碼。
details	ErrorDetail[]	錯誤詳情
message	string	錯誤訊息。
target	string	錯誤目標。

ErrorResponse

Object

所有 Azure Resource Manager API 的常見錯誤回應，用於回傳失敗操作的錯誤細節。 （這也遵循 OData 錯誤回應格式。）。

名稱	類型	Description
error	ErrorDetail	錯誤物件。

FieldMapping

Object

定義數據源中的欄位與索引中目標欄位之間的對應。

名稱	類型	Description
mappingFunction	FieldMappingFunction	在建立索引之前套用至每個來源欄位值的函式。
sourceFieldName	string	資料來源中欄位的名稱。
targetFieldName	string	索引中目標欄位的名稱。 預設與來源欄位名稱相同。

FieldMappingFunction

Object

表示在編製索引之前，從數據源轉換值的函式。

名稱	類型	Description
name	string	欄位對應函式的名稱。
parameters		要傳遞給函數的參數名稱/值組字典。 每個值都必須是基本類型。

IndexerExecutionEnvironment

列舉型別

指定索引子應該執行的環境。

值	Description
standard	表示搜尋服務可以判斷索引器應該執行的位置。 當未指定任何專案且為建議值時，這是默認環境。
private	表示索引器應該使用專為搜尋服務布建的環境來執行。 只有當索引器需要透過共用的私人鏈接資源安全地存取資源時，才應該指定為執行環境。

IndexingParameters

Object

表示索引器執行的參數。

名稱	類型	預設值	Description
batchSize	integer (int32)		從資料來源讀取並索引為單一批次以增進效能的項目數目。 預設值取決於資料來源類型。
configuration	IndexingParametersConfiguration		索引器特定組態屬性的字典。 每個名稱都是特定屬性的名稱。 每個值都必須是基本類型。
maxFailedItems	integer (int32)	0	索引子執行可能失敗索引的專案數目上限，仍會被視為成功。 -1 表示沒有限制。 預設值為 0。
maxFailedItemsPerBatch	integer (int32)	0	單一批次中可能無法編製索引的專案數目上限，仍會將批次視為成功。 -1 表示沒有限制。 預設值為 0。

IndexingParametersConfiguration

Object

索引器特定組態屬性的字典。 每個名稱都是特定屬性的名稱。 每個值都必須是基本類型。

名稱	類型	預設值	Description
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 大小的限制，請參閱 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	針對以 「hh：mm：ss」 格式指定的 Azure SQL 資料庫數據源，增加超過 5 分鐘預設值的逾時。

IndexingSchedule

Object

表示索引器執行的排程。

名稱	類型	Description
interval	string (duration)	索引子執行之間的時間間隔。
startTime	string (date-time)	索引子應該開始執行的時間。

SearchIndexer

Object

表示索引器。

名稱	類型	預設值	Description
@odata.etag	string		索引器 ETag。
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		這個索引器寫入數據的索引名稱。

SearchIndexerDataNoneIdentity

Object

清除資料源的識別屬性。

名稱	類型	Description
@odata.type	string: #Microsoft.Azure.Search.DataNoneIdentity	指定身分類型的 URI 片段。

SearchIndexerDataUserAssignedIdentity

Object

指定要使用之數據源的身分識別。

名稱	類型	Description
@odata.type	string: #Microsoft.Azure.Search.DataUserAssignedIdentity	指定身分類型的 URI 片段。
userAssignedIdentity	string	使用者指派受控識別的完整 Azure 資源標識符，通常格式為 “/subscriptions/12345678-1234-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId”。

SearchResourceEncryptionKey

Object

Azure Key Vault 中客戶管理的加密密鑰。 您建立和管理的金鑰可用來加密或解密靜態資料，例如索引和同義字對映。

名稱	類型	Description
accessCredentials.applicationId	string	AAD 應用程式識別碼，已將待用數據加密時要使用的 Azure Key Vault 所需訪問許可權授與。 應用程式標識碼不應與 AAD 應用程式的物件標識元混淆。
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。