Indexers - Create Or Update

參考

服務:: Search Service

API 版本:: 2023-10-01-Preview

建立新的索引器，或在索引器已經存在時更新索引器。

PUT {endpoint}/indexers('{indexerName}')?api-version=2023-10-01-Preview

含選擇性參數:

PUT {endpoint}/indexers('{indexerName}')?api-version=2023-10-01-Preview&ignoreResetRequirements={ignoreResetRequirements}&disableCacheReprocessingChangeDetection={disableCacheReprocessingChangeDetection}

URI 參數

名稱	位於	必要	類型	Description
endpoint	path	True	string	搜尋服務的端點 URL。
indexerName	path	True	string	要建立或更新之索引器的名稱。
api-version	query	True	string	用戶端 API 版本。
disableCacheReprocessingChangeDetection	query		boolean	停用快取重新處理變更偵測。
ignoreResetRequirements	query		boolean	忽略快取重設需求。

要求標頭

名稱	必要	類型	Description
x-ms-client-request-id		string uuid	使用要求傳送的追蹤標識碼，以協助偵錯。
If-Match		string	定義 If-Match 條件。只有在伺服器上的 ETag 符合此值時，才會執行作業。
If-None-Match		string	定義 If-None-Match 條件。只有在伺服器上的 ETag 不符合此值時，才會執行作業。
Prefer	True	string	針對 HTTP PUT 要求，指示服務在成功時傳回已建立/更新的資源。

要求本文

名稱	必要	類型	Description
dataSourceName	True	string	這個索引器從中讀取數據的數據源名稱。
name	True	string	索引子的名稱。
targetIndexName	True	string	這個索引器寫入數據的索引名稱。
@odata.etag		string	索引器的 ETag。
cache		SearchIndexerCache	將快取新增至擴充管線，以允許累加修改步驟，而不需要每次重建索引。
description		string	索引器的描述。
disabled		boolean	值，指出索引器是否已停用。預設值為 false。
encryptionKey		SearchResourceEncryptionKey	您在 Azure 金鑰保存庫中建立的加密金鑰描述。此金鑰可用來為索引器定義提供額外的待用加密層級 (，以及當您想要完全保證沒有任何人甚至 Microsoft 無法解密時，索引器執行狀態) 。加密索引器定義之後，它一律會保持加密狀態。搜尋服務會忽略將此屬性設定為 Null 的嘗試。如果您想要輪替加密金鑰，您可以視需要變更此屬性;您的索引器定義 (和索引器執行狀態) 將不會受到影響。使用客戶管理的金鑰加密不適用於免費搜尋服務，而且僅適用於在 2019 年 1 月 1 日或之後建立的付費服務。
fieldMappings		FieldMapping[]	定義數據源中的欄位與索引中對應的目標欄位之間的對應。
outputFieldMappings		FieldMapping[]	輸出欄位對應會在擴充之後套用，並在編製索引之前立即套用。
parameters		IndexingParameters	索引器執行的參數。
schedule		IndexingSchedule	這個索引器的排程。
skillsetName		string	使用此索引器執行的技能集名稱。

回應

名稱	類型	Description
200 OK	SearchIndexer
201 Created	SearchIndexer
Other Status Codes	SearchError	錯誤回應。

範例

SearchServiceCreateOrUpdateIndexer

範例要求

HTTP

PUT https://myservice.search.windows.net/indexers('myindexer')?api-version=2023-10-01-Preview


{
  "name": "myindexer",
  "description": "a cool indexer",
  "dataSourceName": "mydatasource",
  "targetIndexName": "orders",
  "schedule": {
    "interval": "PT1H",
    "startTime": "2015-01-01T00:00:00Z"
  },
  "parameters": {
    "maxFailedItems": 10,
    "maxFailedItemsPerBatch": 5
  },
  "encryptionKey": {
    "keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
    "keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
    "keyVaultUri": "https://myKeyVault.vault.azure.net",
    "accessCredentials": null
  }
}

範例回覆

狀態碼:: 200

{
  "name": "myindexer",
  "description": "a cool indexer",
  "dataSourceName": "mydatasource",
  "targetIndexName": "orders",
  "schedule": {
    "interval": "PT1H",
    "startTime": "2015-01-01T00:00:00Z"
  },
  "parameters": {
    "maxFailedItems": 10,
    "maxFailedItemsPerBatch": 5
  },
  "fieldMappings": [],
  "disabled": false,
  "encryptionKey": {
    "keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
    "keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
    "keyVaultUri": "https://myKeyVault.vault.azure.net",
    "accessCredentials": null
  }
}

狀態碼:: 201

{
  "name": "myindexer",
  "description": "a cool indexer",
  "dataSourceName": "mydatasource",
  "targetIndexName": "orders",
  "schedule": {
    "interval": "PT1H",
    "startTime": "2015-01-01T00:00:00Z"
  },
  "parameters": {
    "maxFailedItems": 10,
    "maxFailedItemsPerBatch": 5
  },
  "fieldMappings": [],
  "disabled": false,
  "encryptionKey": {
    "keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
    "keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
    "keyVaultUri": "https://myKeyVault.vault.azure.net",
    "accessCredentials": null
  }
}

定義

名稱	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 檔案擷取文字的演算法。
FieldMapping	定義數據源中的欄位與索引中目標欄位之間的對應。
FieldMappingFunction	表示在編製索引之前，從數據源轉換值的函式。
IndexerExecutionEnvironment	指定索引器應該執行的環境。
IndexingParameters	表示索引子執行的參數。
IndexingParametersConfiguration	索引器特定組態屬性的字典。每個名稱都是特定屬性的名稱。每個值都必須是基本類型。
IndexingSchedule	表示索引子執行的排程。
SearchError	描述 API 的錯誤狀況。
SearchIndexer	表示索引器。
SearchIndexerCache
SearchIndexerDataNoneIdentity	清除資料源的識別屬性。
SearchIndexerDataUserAssignedIdentity	指定要使用之數據源的身分識別。
SearchResourceEncryptionKey	Azure 金鑰保存庫中客戶管理的加密密鑰。您建立和管理的金鑰可用來加密或解密待用數據，例如索引和同義字對應。

AzureActiveDirectoryApplicationCredentials

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

名稱	類型	Description
applicationId	string	AAD 應用程式識別碼，授與對待用數據加密時所要使用的 Azure 金鑰保存庫所需訪問許可權。應用程式標識碼不應與 AAD 應用程式的物件標識元混淆。
applicationSecret	string	指定 AAD 應用程式的驗證金鑰。

BlobIndexerDataToExtract

指定要從 Azure Blob 記憶體擷取的數據，並在「imageAction」設定為「none」以外的值時，告知索引器要從影像內容擷取哪些數據。這適用於 .PDF 或其他應用程式中的內嵌影像內容，或在 Azure Blob 中套用 .jpg 和 .png 等圖像檔。

名稱	類型	Description
allMetadata	string	擷取 Azure Blob 記憶體子系統所提供的元數據，以及內容類型特定的元數據 (，例如，僅 .png 檔案的元數據會編製索引) 。
contentAndMetadata	string	從每個 Blob 擷取所有元數據和文字內容。
storageMetadata	string	只編製標準 Blob 屬性和使用者指定元數據的索引。

BlobIndexerImageAction

決定如何處理 Azure Blob 記憶體中的內嵌映像和映像檔案。將「imageAction」組態設定為「none」以外的任何值，都需要將技能集附加至該索引器。

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

BlobIndexerParsingMode

表示從 Azure Blob 數據源編製索引的剖析模式。

名稱	類型	Description
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 檔案擷取文字的演算法。

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

FieldMapping

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

名稱	類型	Description
mappingFunction	FieldMappingFunction	在編製索引之前套用至每個來源域值的函式。
sourceFieldName	string	數據源中的功能變數名稱。
targetFieldName	string	索引中目標欄位的名稱。默認與來源功能變數名稱相同。

FieldMappingFunction

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

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

IndexerExecutionEnvironment

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

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

IndexingParameters

表示索引子執行的參數。

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

IndexingParametersConfiguration

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

名稱	類型	預設值	Description
allowSkillsetToReadFileData	boolean	False	如果為 true，將會建立路徑 ─document/file_data，代表從 Blob 資料源下載的原始文件數據。這可讓您將源文件數據傳遞至自定義技能，以在擴充管線內處理，或傳遞至檔擷取技能。
dataToExtract	BlobIndexerDataToExtract	contentAndMetadata	指定要從 Azure Blob 記憶體擷取的數據，並告知索引器當「imageAction」設定為「none」以外的值時，要從影像內容中擷取的數據。這適用於 Azure Blob 中 .PDF 或其他應用程式中的內嵌影像內容，或 .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://docs.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	針對以「hh：mm：ss」格式指定的 Azure SQL 資料庫數據源，增加超過 5 分鐘預設值的逾時。

IndexingSchedule

表示索引子執行的排程。

名稱	類型	Description
interval	string	索引器執行之間的時間間隔。
startTime	string	索引器應該開始執行的時間。

SearchError

描述 API 的錯誤狀況。

名稱	類型	Description
code	string	其中一組伺服器定義的錯誤碼。
details	SearchError[]	導致此錯誤之特定錯誤的詳細數據陣列。
message	string	人類看得懂的錯誤表示法。

SearchIndexer

表示索引器。

名稱	類型	預設值	Description
@odata.etag	string		索引器的 ETag。
cache	SearchIndexerCache		將快取新增至擴充管線，以允許累加修改步驟，而不需要每次重建索引。
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		這個索引器寫入數據的索引名稱。

SearchIndexerCache

名稱	類型	Description
enableReprocessing	boolean	指定是否啟用累加式重新處理。
identity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	使用者指派的受控識別，用於連線至擴充快取。如果連接字串指出 ResourceId) (身分識別，而且未指定，則會使用系統指派的受控識別。在索引器的更新時，如果未指定身分識別，該值會保持不變。如果設定為「none」則會清除此屬性的值。
storageConnectionString	string	連接字串至將保存快取數據的記憶體帳戶。

SearchIndexerDataNoneIdentity

清除資料源的識別屬性。

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

SearchIndexerDataUserAssignedIdentity

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

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

SearchResourceEncryptionKey

Azure 金鑰保存庫中客戶管理的加密密鑰。您建立和管理的金鑰可用來加密或解密待用數據，例如索引和同義字對應。

名稱	類型	Description
accessCredentials	AzureActiveDirectoryApplicationCredentials	用來存取 Azure 金鑰保存庫的選擇性 Azure Active Directory 認證。如果改為使用受控識別，則不需要。
identity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	要用於此加密金鑰的明確受控識別。如果未指定，且存取認證屬性為 Null，則會使用系統指派的受控識別。更新資源時，如果未指定明確的身分識別，則會維持不變。如果指定了「none」則會清除此屬性的值。
keyVaultKeyName	string	要用來加密待用數據的 Azure 金鑰保存庫金鑰名稱。
keyVaultKeyVersion	string	要用來加密待用數據的 Azure 金鑰保存庫金鑰版本。
keyVaultUri	string	Azure 金鑰保存庫的 URI，也稱為 DNS 名稱，其中包含用來加密待用數據的密鑰。範例 URI 可能是 `https://my-keyvault-name.vault.azure.net`。

共用方式為