共用方式為

Indexers - Create

服務:
Search Service
API 版本:
2025-09-01

建立新的索引子。

POST {endpoint}/indexers?api-version=2025-09-01

URI 參數

名稱 位於 必要 類型 Description
endpoint
 path True

string

搜尋服務的端點 URL。
api-version
 query True

string

用戶端 API 版本。

要求標頭

名稱 必要 類型 Description
x-ms-client-request-id

string (uuid)

隨請求一起傳送的追蹤 ID，以協助偵錯。

要求本文

名稱 必要 類型 Description
dataSourceName True

string

此索引子從中讀取資料的資料來源名稱。
name True

string

索引子的名稱。
targetIndexName True

string

此索引子寫入資料的索引名稱。
@odata.etag

string

索引子的 ETag。
description

string

索引子的描述。
disabled

boolean

指出索引子是否已停用的值。 預設值為 false。
encryptionKey

SearchResourceEncryptionKey

您在 Azure 金鑰保存庫中建立的加密金鑰描述。 當您想要完全保證沒有人 （甚至 Microsoft） 無法解密它們時，此金鑰可用來為您的索引子定義 （以及索引子執行狀態） 提供額外的待用加密層級。 加密索引子定義之後，它一律會保持加密狀態。 搜尋服務會忽略嘗試將此屬性設定為 Null。 如果您想要輪替加密金鑰，您可以視需要變更此屬性;您的索引子定義 （和索引子執行狀態） 不會受到影響。 使用客戶管理的金鑰進行加密不適用於免費搜尋服務，且僅適用於 2019 年 1 月 1 日或之後建立的付費服務。
fieldMappings

FieldMapping[]

定義資料來源中欄位與索引中對應目標欄位之間的對應。
outputFieldMappings

FieldMapping[]

輸出欄位對應會在擴充之後和索引之前立即套用。
parameters

IndexingParameters

索引子執行的參數。
schedule

IndexingSchedule

此索引子的排程。
skillsetName

string

使用此索引子執行的技能集名稱。

回應

名稱 類型 Description
201 Created

SearchIndexer

Other Status Codes

ErrorResponse

錯誤回應。

範例

SearchServiceCreateIndexer

範例要求

POST https://stableexampleservice.search.windows.net/indexers?api-version=2025-09-01


{
  "name": "myindexer",
  "description": "Description of the indexer",
  "dataSourceName": "mydocdbdatasource",
  "skillsetName": "myskillset",
  "targetIndexName": "stable-test",
  "schedule": {
    "interval": "P1D",
    "startTime": "2025-01-07T19:30:00Z"
  },
  "parameters": {
    "batchSize": 10,
    "maxFailedItems": 10,
    "maxFailedItemsPerBatch": 5,
    "configuration": {
      "excludedFileNameExtensions": ".png,.mp4",
      "indexedFileNameExtensions": ".docx,.pptx",
      "failOnUnsupportedContentType": true,
      "failOnUnprocessableDocument": false,
      "indexStorageMetadataOnlyForOversizedDocuments": true,
      "delimitedTextHeaders": "Header1,Header2",
      "delimitedTextDelimiter": "|",
      "firstLineContainsHeaders": true,
      "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": "mydocdbdatasource",
  "skillsetName": "myskillset",
  "targetIndexName": "stable-test",
  "disabled": false,
  "schedule": {
    "interval": "P1D",
    "startTime": "2024-06-06T00:01:50.265Z"
  },
  "parameters": {
    "batchSize": 10,
    "maxFailedItems": 10,
    "maxFailedItemsPerBatch": 5,
    "configuration": {
      "excludedFileNameExtensions": ".png,.mp4",
      "indexedFileNameExtensions": ".docx,.pptx",
      "failOnUnsupportedContentType": true,
      "failOnUnprocessableDocument": false,
      "indexStorageMetadataOnlyForOversizedDocuments": true,
      "delimitedTextHeaders": "Header1,Header2",
      "delimitedTextDelimiter": "|",
      "firstLineContainsHeaders": true,
      "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
AzureActiveDirectoryApplicationCredentials

針對搜尋服務建立之已註冊應用程式認證，用於對儲存在 Azure 金鑰保存庫中的加密金鑰進行驗證存取。
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

代表索引子。
SearchResourceEncryptionKey

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

AzureActiveDirectoryApplicationCredentials

Object

針對搜尋服務建立之已註冊應用程式認證，用於對儲存在 Azure 金鑰保存庫中的加密金鑰進行驗證存取。

名稱 類型 Description
applicationId

string

已授與 Azure 金鑰保存庫所需存取權限的 AAD 應用程式識別碼，可在加密待用資料時使用。 應用程式識別碼不應與 AAD 應用程式的物件識別碼混淆。
applicationSecret

string

指定 AAD 應用程式的驗證金鑰。

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 檔案的處理方式不同，因為每個頁面都會呈現為影像並據此正規化，而不是擷取內嵌影像。 非 PDF 檔案類型的處理方式與設定「generateNormalizedImages」相同。

BlobIndexerParsingMode

列舉型別

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

值 Description
default

設定為一般檔案處理的預設值。
text

設定為文字，以改善 Blob 儲存體中純文字檔案的索引效能。
delimitedText

當 Blob 是純 CSV 檔案時，設定為 delimitedText。
json

設定為 json 以從 JSON 檔案擷取結構化內容。
jsonArray

設定為 jsonArray ，以擷取 JSON 陣列的個別元素為個別文件。
jsonLines

設定為 jsonLines 以擷取個別 JSON 實體 （以換行分隔） 作為個別文件。

BlobIndexerPDFTextRotationAlgorithm

列舉型別

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

值 Description
none

利用正常的文字擷取。 這是預設值。
detectAngles

可以從具有旋轉文本的 PDF 文件中產生更好、更易讀的文本提取。 請注意，使用此參數時，可能會對效能速度產生較小的影響。 此參數僅適用於 PDF 檔案，且僅適用於內嵌文字的 PDF。 如果旋轉的文字出現在 PDF 的內嵌影像中，則此參數不適用。

ErrorAdditionalInfo

Object

資源管理錯誤其他資訊。

名稱 類型 Description
info

object

其他資訊。
type

string

其他信息類型。

ErrorDetail

Object

錯誤詳細數據。

名稱 類型 Description
additionalInfo

ErrorAdditionalInfo[]

錯誤其他資訊。
code

string

錯誤碼。
details

ErrorDetail[]

錯誤詳細數據。
message

string

錯誤訊息。
target

string

錯誤目標。

ErrorResponse

Object

錯誤回應

名稱 類型 Description
error

ErrorDetail

error 物件。

FieldMapping

Object

定義資料來源中欄位與索引中目標欄位之間的對應。

名稱 類型 Description
mappingFunction

FieldMappingFunction

在建立索引之前套用至每個來源欄位值的函式。
sourceFieldName

string

資料來源中欄位的名稱。
targetFieldName

string

索引中目標欄位的名稱。 預設與來源欄位名稱相同。

FieldMappingFunction

Object

代表在編製索引之前從資料來源轉換值的函數。

名稱 類型 Description
name

string

欄位對應函式的名稱。
parameters

object

要傳遞給函數的參數名稱/值組字典。 每個值都必須是基本類型。

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 視為錯誤。 如需 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

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 金鑰保存庫中建立的加密金鑰描述。 當您想要完全保證沒有人 （甚至 Microsoft） 無法解密它們時，此金鑰可用來為您的索引子定義 （以及索引子執行狀態） 提供額外的待用加密層級。 加密索引子定義之後，它一律會保持加密狀態。 搜尋服務會忽略嘗試將此屬性設定為 Null。 如果您想要輪替加密金鑰，您可以視需要變更此屬性;您的索引子定義 （和索引子執行狀態） 不會受到影響。 使用客戶管理的金鑰進行加密不適用於免費搜尋服務，且僅適用於 2019 年 1 月 1 日或之後建立的付費服務。
fieldMappings

FieldMapping[]

定義資料來源中欄位與索引中對應目標欄位之間的對應。
name

string

索引子的名稱。
outputFieldMappings

FieldMapping[]

輸出欄位對應會在擴充之後和索引之前立即套用。
parameters

IndexingParameters

索引子執行的參數。
schedule

IndexingSchedule

此索引子的排程。
skillsetName

string

使用此索引子執行的技能集名稱。
targetIndexName

string

此索引子寫入資料的索引名稱。

SearchResourceEncryptionKey

Object

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

名稱 類型 Description
accessCredentials

AzureActiveDirectoryApplicationCredentials

用來存取 Azure 金鑰保存庫的選擇性 Azure Active Directory 認證。 如果改用受控識別，則不需要。
keyVaultKeyName

string

要用來加密待用資料的 Azure 金鑰保存庫名稱。
keyVaultKeyVersion

string

要用來加密待用資料的 Azure 金鑰版本。
keyVaultUri

string

Azure 金鑰保存庫的 URI，也稱為 DNS 名稱，其中包含要用來加密待用資料的金鑰。 範例 URI 可能是 https://my-keyvault-name.vault.azure.net。