建立 Azure AI 搜尋服務 REST API (索引器)

發行項
02/28/2024

索引器會從支援的 Azure 數據源自動編製索引，例如 Azure 記憶體、Azure SQL 資料庫和 Azure Cosmos DB，以命名幾個。索引器會使用預先定義的 數據源 和索引來建立索引管線，以擷取及串行化源數據，並將其傳遞至搜尋服務以進行數據擷取。針對影像和非結構化文字的 AI 擴充，索引器也可以接受定義 AI 處理的 技能集 。

建立索引器會將它新增至您的搜尋服務並加以執行。如果要求成功，索引會填入數據源中的可搜尋內容。

您可以在要求上使用 POST 或 PUT。針對其中一個，要求本文中的 JSON 檔會提供物件定義。

POST https://[service name].search.windows.net/indexers?api-version=[api-version]
    Content-Type: application/json  
    api-key: [admin key]

或者，您可以使用 PUT，並在 URI 上指定索引器名稱。

PUT https://[service name].search.windows.net/indexers/[indexer name]?api-version=[api-version]
    Content-Type: application/json  
    api-key: [admin key]

所有服務要求都需使用 HTTPS。如果索引器不存在，則會建立索引器。如果已經存在，則會更新為新的定義，但如果您想要執行索引器，您必須發出執行索引器要求。

索引器組態會根據數據源的類型而有所不同。如需建立索引子的資料平台特定指引，請從索引子概觀開始，其中包含相關文章的完整清單。

URI 參數

參數	Description
服務名稱	必要。將此設定為搜尋服務的唯一用戶定義名稱。
索引器名稱	如果使用 PUT，則為 URI 的必要專案。名稱必須是小寫，開頭為字母或數位、沒有斜線或點，且少於 128 個字元。名稱的開頭必須是字母或數位，但名稱的其餘部分可以包含任何字母、數位和虛線，只要虛線不是連續的。
api-version	必要。如需支援的版本清單，請參閱 API 版本。

要求標頭

下表說明必要及選用的要求標頭。

欄位	Description
Content-Type	必要。請設為 `application/json`
api-key	如果您使用 Azure 角色，而且要求會提供持有人令牌，則為選擇性，否則需要密鑰。建立要求必須包含 `api-key` 設定為系統管理員密鑰的標頭 (，而不是查詢密鑰) 。如需詳細資訊，請參閱使用密鑰驗證連線到 Azure AI 搜尋服務。

要求本文

資料來源、索引和技能集是索引子定義的一部分，但每一個都是可用於不同組合的獨立元件。例如，您可以搭配多個索引子使用相同的資料來源，或者搭配多個索引子，或多個寫入單一索引的索引子使用相同索引。

下列 JSON 是定義主要部分的高階表示法。

{   
    "name" : (optional on PUT; required on POST) "Name of the indexer",  
    "description" : (optional) "Anything you want, or nothing at all", 
    "dataSourceName" : (required) "Name of an existing data source",  
    "targetIndexName" : (required) "Name of an existing index",  
    "skillsetName" : (required for AI enrichment) "Name of an existing skillset",
    "disabled" : (optional) Boolean value indicating whether the indexer is disabled. False by default,
    "schedule" : (optional but runs once immediately if unspecified) { ... },  
    "parameters": { (optional)
       "batchSize": null,
       "maxFailedItems": 0,
       "maxFailedItemsPerBatch": 0,
       "base64EncodeKeys": null,
       "configuration": { (optional, mostly specific to the data source)
            "executionEnvironment": null
        }
      }, 
    "fieldMappings" : (optional) { ... },
    "outputFieldMappings" : (required for AI enrichment) { ... },
    "encryptionKey":(optional) { }
}

要求可包含下列屬性：

屬性	Description
NAME	必要。名稱必須是小寫，開頭為字母或數位、沒有斜線或點，且少於 128 個字元。名稱的開頭必須是字母或數位，但名稱的其餘部分可以包含任何字母、數位和虛線，只要虛線不是連續的。
dataSourceName	必要。現有數據源的名稱。它通常包含索引器可用來惡意探索來源平臺特性的屬性。因此，您傳遞給索引器的數據源會決定特定屬性和參數的可用性，例如 Azure Blob 中的內容類型篩選。或查詢 Azure SQL 資料庫的逾時。
targetIndexName	必要。現有索引架構的名稱。它會定義欄位集合，其中包含可搜尋、可篩選、可擷取和其他屬性，以決定欄位的使用方式。在建立索引期間，索引子會搜耙資料來源、選擇性地破解文件並擷取資訊、將結果序列化至 JSON，並根據針對索引定義的結構描述，為酬載編製索引。
skillsetName	AI 擴充的必要專案。現有技能集的名稱，每個索引器一個。如同數據源和索引，技能集是您附加至索引器的獨立定義。您可以使用其他索引子重新調整技能集，但每個索引子一次只能使用一個技能集。
schedule	選擇性，但如果未指定且未停用，則會立即執行一次。排程包含 `interval` (必要) 和 `startTime` (選擇性) 。如需詳細資訊，請參閱排程索引器。 `interval` 指定索引器執行的頻率。允許的最小間隔為 5 分鐘；最長間隔為一天。其必須格式化為 XSD "dayTimeDuration" 值 ( ISO 8601 持續時間值的受限子集)。此模式為：範例： `"P[nD][T[nH][nM]]".PT15M` 每隔 15 分鐘， `PT2H` 每 2 小時。 `startTime` 是索引器應該開始執行的UTC日期時間。
停用	選擇性。布爾值，指出索引器是否停用。如果您想要建立索引器定義而不立即執行索引器定義，請設定此屬性。預設為 False。
參數	選擇性。修改運行時間行為的屬性。 `"batchSize"` (整數) 。指定從資料來源讀取並以單一批次編製索引來提升效能的項目數。默認值為來源特定 (1000，適用於 Azure SQL Database 和 Azure Cosmos DB，Azure Blob 儲存體) 為 10。 `"maxFailedItems"` (整數) 。指定索引器執行視為失敗之前要容許的錯誤數目。預設值為 0。如果您不想讓任何錯誤停止編製索引程序，請設為 -1。使用取得索引器狀態來擷取失敗檔的相關信息。 `"maxFailedItemsPerBatch"` (整數) 。指定要在索引器執行視為失敗之前，在每個批次中容許的錯誤數目。預設值為 0。如果您不想讓任何錯誤停止編製索引程序，請設為 -1。 `"base64EncodeKey"` (布爾值) 。指定是否編碼包含無效字元的檔案索引鍵。 `"configuration"`. 根據數據源而有所不同的屬性。 `"executionEnvironment"` (字串) 。覆寫內部系統進程所選擇的執行環境。如果索引器透過私人端點連線存取外部資源，則需要明確將執行環境設定為 `Private` 。此設定位於底下 `"configuration"`。對於數據擷取，此設定僅適用於布建為基本或標準 (S1、S2、S3) 的服務。對於 AI 擴充內容處理，此設定僅適用於 S2 和 S3。有效值為不區分大小寫，且包含 [null 或未指定]、 `Standard` (預設) 或 `Private`。
fieldMappings	選擇性。明確地將來源欄位與搜尋索引中的目的地欄位產生關聯。當來源和目的地欄位具有不同的名稱或類型，或當您想要指定函式時使用。區 `fieldMappings` 段包含 `sourceFieldName` 必要 (、基礎數據源中的欄位) 、 `targetFieldName` 需要 (、索引) 中的欄位，以及編碼輸出的選擇性 `mappingFunction` 字段。您可以在欄位對應函式中找到支援的函式和範例清單。如需詳細資訊，請參閱欄位對應和轉換。
outputFieldMappings	擴充管線的必要專案。將技能集的輸出對應至索引或投影。區 `outputFieldMappings` 段包含 `sourceFieldName` 必要 (、擴充樹狀結構中的節點) 、 `targetFieldName` 需要 (、索引) 中的字段，以及編碼輸出的選擇性 `mappingFunction` 。您可以在欄位對應函式中找到支援的函式和範例清單。如需詳細資訊，請參閱如何對應技能集的輸出欄位。
encryptionKey	選擇性。用來使用您自己的金鑰加密待用索引器定義，並在 Azure 金鑰保存庫中管理。適用於在 2019-01-01 之後建立的可計費搜尋服務。區 `encryptionKey` 段包含使用者定義的 `keyVaultKeyName` (必要) 、系統產生的 `keyVaultKeyVersion` (必要) ，以及 `keyVaultUri` 提供所需的密鑰 (，也稱為 DNS 名稱) 。範例 URI 可能是 “https://my-keyvault-name.vault.azure.net"。您可以選擇性地指定 `accessCredentials` 是否不使用受控系統識別。 `accessCredentials`的屬性包括 `applicationId` (Microsoft Entra ID 已授與所指定 Azure 金鑰保存庫) 存取權限的應用程式識別碼，以及 `applicationSecret` (已註冊應用程式) 的驗證密鑰。下一節中的範例說明語法。

Blob 組態參數

數個參數對於特定的索引子是獨佔的，例如 Azure Blob 索引。

參數	類型和允許的值	使用方式
`"parsingMode"`	字串 `"text"` `"delimitedText"` `"json"` `"jsonArray"` `"jsonLines"`	針對 Azure Blob，設為 `text` 以改善 Blob 儲存體中純文字檔案的索引效能。針對 CSV Blob，當 Blob 是純 CSV 檔案時設為 `delimitedText`。針對 JSON Blob，請將設定為 `json` 以擷取結構化內容，或 `jsonArray` 將數位的個別元素擷取為 Azure AI 搜尋服務中的個別檔。用來 `jsonLines` 擷取個別 JSON 實體，並以新行分隔，作為 Azure AI 搜尋服務中的個別檔。
`"excludedFileNameExtensions"`	字串逗號分隔清單使用者定義	針對 Azure Blob，請略過清單中的任何檔案類型。例如，您可以排除「.png、.png、.mp4」，以在編製索引期間略過這些檔案。
`"indexedFileNameExtensions"`	字串逗號分隔清單使用者定義	針對 Azure Blob，如果副檔名位於清單中，則選取 Blob。例如，您可以專注在編製特定應用程式檔案「.docx、.pptx、.msg」的索引，以特別包含那些檔案類型。
`"failOnUnsupportedContentType"`	Boolean true False (預設值)	針對 Azure Blob，如果您想要在遇到不支援的內容類型，並且事先不知道所有內容類型 (副檔名) 時繼續編製索引，請將其設為 `false`。
`"failOnUnprocessableDocument"`	Boolean true False (預設值)	針對 Azure Blob，如果要在文件編製索引失敗時繼續編製索引，請將其設為 `false`。
`"indexStorageMetadataOnly` `ForOversizedDocuments"`	布爾值 true False (預設值)	針對 Azure Blob，請將此屬性設為 `true`，以便為太大而無法處理的 Blob 內容編製儲存體中繼資料的索引。預設會將過大的 Blob 視為錯誤。如需 Blob 大小的限制，請參閱服務限制。
`"delimitedTextHeaders"`	字串逗號分隔清單使用者定義	針對 CSV Blob，指定以逗號分隔的數據行標頭清單，適用於將來源欄位對應至索引中的目的地欄位。
`"delimitedTextDelimiter"`	字串單一字元使用者定義	針對 CSV Blob，指定 CSV 檔案的行尾分隔符，其中每一行都會啟動新的檔案 (例如， `"\|"`) 。
`"firstLineContainsHeaders"`	Boolean true (預設值) false	針對 CSV Blob，表示每個 Blob 的第一個 (非空白) 行包含標頭。
`"documentRoot"`	字串使用者定義路徑	針對 JSON 陣列，假設有結構化或半結構化檔，您可以使用這個屬性來指定數位的路徑。
`"dataToExtract"`	字串 `"storageMetadata"` `"allMetadata"` `"contentAndMetadata"` (預設)	針對 Azure Blob：設為 `"storageMetadata"` 以僅針對標準 Blob 屬性和使用者指定的中繼資料編製索引。設為 `"allMetadata"` 以擷取由 Azure Blob 儲存體子系統提供的中繼資料，而特定內容類型的中繼資料 (例如，僅限 .png 檔案的中繼資料) 會編製索引。設為 `"contentAndMetadata"` 以從每個 Blob 擷取所有中繼資料和文字內容。針對 AI 擴充中的影像分析，當設定為以外的`"none"`值時`"imageAction"`，此`"dataToExtract"`設定會告知索引器要從影像內容中擷取的數據。適用於 .PDF 或其他應用程式中的內嵌影像內容，或 Azure Blob 中的影像檔 (例如 .jpg 和 .png)。
`"imageAction"`	字串 `"none"` `"generateNormalizedImages"` `"generateNormalizedImagePerPage"`	針對 Azure Blob，設為 `"none"` 以忽略內嵌影像或資料集中的影像檔。此為預設值。如需 AI 擴充中的影像分析，請將設為`"generateNormalizedImages"` 以從影像擷取文字 (例如，從流量「停止」一詞停止符號) ，並將其內嵌為內容字段的一部分。在影像分析期間，索引子會建立標準化影像的陣列作為文件破解的一部分，並將產生的資訊嵌入到內容欄位中。這個動作需要將 `"dataToExtract"` 設為 `"contentAndMetadata"`。標準化影像指的是藉由額外的處理過程以產生統一的影像輸出。影像經過調整大小與旋轉之後，會使得視覺化搜索結果中的影像有一致的呈現 (例如，如 JFK 示範 $英文$ 中所見圖形控制項中相同尺寸的照片)。當您使用此選項時，每個映像都會產生這項資訊。如果設為 `"generateNormalizedImagePerPage"`，則會以其他方式處理 PDF 檔案，而不是擷取內嵌影像，每頁都會轉譯為影像，分別予以標準化。此每頁程式應該花費的時間遠超過 `"generateNormalizedImages"`。非 PDF 檔案類型的處理方式如同設定了 `"generateNormalizedImages"`。將組 `"imageAction"` 態設定為以外的 `"none"` 任何值，需要技能集也附加至該索引器，而且可以設計為低效能的程式。
`"normalizedImageMaxWidth"` `"normalizedImageMaxHeight"`	介於 50-10000 之間的整數	設定時 `"imageAction"` 所產生標準化影像的寬度或高度上限 (，以像素為單位) 。預設值為 2000。標準化影像的最大寬度與最大高度的預設值為 2000 像素，這是根據 OCR 技術和影像分析技術所支援的大小上限。 OCR 技能支援的非英文語言的寬度和高度上限為 4200，而英文的寬度和高度上限則為 10000。如果您增加最大限制，根據技能集定義和文件的語言，處理可能會因較大的影像而失敗。
`"allowSkillsetToReadFileData"`	Boolean true False (預設值)	將 `"allowSkillsetToReadFileData"` 參數設定為 `true` 會建立路徑 `/document/file_data` ，代表從 Blob 數據源下載的源文件數據。這可讓您將源文件數據傳遞至自定義技能，以在擴充管線內處理，或傳遞至檔擷取技能。產生的物件將定義如下： `{ "$type": "file", "data": "BASE64 encoded string of the file" }` 將 `"allowSkillsetToReadFileData"` 參數設定為 `true` ，需要將技能集附加至該索引器，並將 `"parsingMode"` 參數設定為 `"default""text"` 或 `"json"`。
`"pdfTextRotationAlgorithm"`	字串 `"none"` (預設) `"detectAngles"`	`"pdfTextRotationAlgorithm"`將參數設定為 `"detectAngles"` 有助於從具有旋轉文字的 PDF 檔案產生較佳且更容易閱讀的文字擷取。請注意，使用此參數時可能會有較小的效能負面影響。此參數僅適用於 PDF 檔案，而且僅適用於具有內嵌文字的 PDF。如果旋轉的文字出現在 PDF 中的內嵌影像內，則此參數不適用。將 `"pdfTextRotationAlgorithm"` 參數設定為 `"detectAngles"` 需要 `"parsingMode"` 將參數設定為 `"default"`。

Azure Cosmos DB 組態參數

下列參數專屬於Cosmos DB索引器。

參數	類型和允許的值	使用方式
`"assumeOrderByHighWaterMarkColumn"`	Boolean	針對具有 SQL API 的 Cosmos DB 索引器，請將此參數設定為提供提示給 Cosmos DB，指出用來傳回索引文件的查詢實際上是依 `_ts` 數據行排序。設定此參數可讓您取得累加式索引處理案例的更佳結果。

Azure SQL 組態參數

下列參數專屬於 Azure SQL Database。

參數	類型和允許的值	使用方式
`"queryTimeout"`	字串 "hh:mm:ss" "00:05:00"	針對 Azure SQL Database，設定此參數以增加超過 5 分鐘逾時的預設值。
`"convertHighWaterMarkToRowVersion"`	Boolean	將此參數設定為「true」，以針對高水位標記數據行使用 rowversion 數據類型。當此屬性設定為 true 時，索引器會在索引器執行之前，從 rowversion 值減去其中一個。這樣做是因為具有一對多聯結的檢視可能有具有重複 rowversion 值的數據列。減一可確保索引子查詢不會遺漏這些資料列。
`"disableOrderByHighWaterMarkColumn"`	Boolean	如果您想要在用於變更偵測的查詢中停用 ORDER BY 行為，請將此參數設定為「true」。如果您使用高水位標記變更偵測原則，索引器會使用WHERE和 ORDER BY 子句來追蹤哪些數據列需要編製索引 (`WHERE [High Water Mark Column] > [Current High Water Mark Value] ORDER BY [High Water Mark Column]`) 。此參數會停用 ORDER BY 行為。索引編製會更快完成，但取捨是，如果索引器因任何原因而中斷，整個索引器作業必須完整重複。

回應

「201 已建立」表示要求成功。

範例

範例：具有排程和泛型參數的索引器

建立索引器，此索引器會根據從 2021 年 1 月 1 日 UTC 開始的排程，orders將數據從數據源參考ordersds的數據表複製到索引，並每小時執行。如果每個批次中無法編製索引的項目不超過 5 個，且無法編製索引的項目總數不超過 10 個的話，每個索引子的引動都將成功。

{
    "name" : "myindexer",  
    "description" : "a cool indexer",  
    "dataSourceName" : "ordersds",  
    "targetIndexName" : "orders",  
    "schedule" : { "interval" : "PT1H", "startTime" : "2021-01-01T00:00:00Z" },  
    "parameters" : { "maxFailedItems" : 10, "maxFailedItemsPerBatch" : 5 }  
}

注意

如果索引子設定為特定排程，但在每次執行時一再地在同一份文件上失敗，則索引子會以較不頻繁的間隔開始執行 (最多每隔 24 小時至少執行一次) 直到再次順利推進為止。如果您認為您已修正任何導致索引器停滯在特定時間點的問題，您可以執行重設，後面接著索引器的隨選執行，如果成功進行，則索引器會再次回到其設定的排程間隔。

範例：具有 Blob 參數的索引器

索引子可以選擇性地採用修改執行階段行為的組態參數。組態參數是以逗號分隔的索引器要求，而且是數據源類型特有的。下列組態參數提供用來編製 Blob 索引的指示。

  {
    "name" : "my-blob-indexer-for-cognitive-search",
    ... other indexer properties
    "parameters" : 
      { 
      "maxFailedItems" : "15", 
      "batchSize" : "100", 
      "configuration" : 
          { 
          "parsingMode" : "json", 
          "indexedFileNameExtensions" : ".json, .jpg, .png",
          "imageAction" : "generateNormalizedImages",
          "dataToExtract" : "contentAndMetadata" ,
          "executionEnvironment": "Standard"
          } 
      }
  }

範例：具有欄位對應的索引器

將源數據表的欄位 _id 對應至 "id" 搜尋索引中的欄位。 Azure AI 搜尋不允許功能變數名稱以底線開頭。欄位對應可以解析名稱不一致。來源和目標欄位名稱皆有區分大小寫。如需詳細資訊，請參閱欄位對應和轉換。

"fieldMappings" : [
    { "sourceFieldName" : "_id", "targetFieldName" : "id" },
    { "sourceFieldName" : "_timestamp", "targetFieldName" : "timestamp" }
]

範例：使用 AI 擴充編製索引器

示範 AI 擴充，以和 outputFieldMappings的參考skillset表示。技能集是分開定義的高層級資源。此範例是 AI 擴充教學課程中索引器定義的縮寫。

{
  "name":"demoindexer",	
  "dataSourceName" : "demodata",
  "targetIndexName" : "demoindex",
  "skillsetName" : "demoskillset",
  "fieldMappings" : [
    {
        "sourceFieldName" : "content",
        "targetFieldName" : "content"
    }
   ],
  "outputFieldMappings" : 
  [
    {
        "sourceFieldName" : "/document/organizations", 
        "targetFieldName" : "organizations"
    },
  ],
  "parameters":
  {
  	"maxFailedItems":-1,
  	"configuration": 
    {
    "dataToExtract": "contentAndMetadata",
    "imageAction": "generateNormalizedImages"
    }
  }
}

範例：具有技能集和輸出字段對應的索引器

在技能集系結至索引器的 AI 擴充案例中，您必須新增 outputFieldMappings ，以建立擴充步驟的任何輸出，以提供內容至索引中可搜尋的欄位。 sourceFieldName是擴充樹狀結構中的節點。這可能是在從源檔中的兩個不同欄位進行擴充期間所建置的復合結構。 targetFieldName是搜尋索引中的欄位。如需詳細資訊，請參閱如何對應技能集的輸出欄位。

"outputFieldMappings" : [
      {
        "sourceFieldName" : "/document/organizations", 
        "targetFieldName" : "organizations"
      },
      {
        "sourceFieldName" : "/document/pages/*/keyPhrases/*", 
        "targetFieldName" : "keyphrases"
      },
      {
          "sourceFieldName": "/document/languageCode",
          "targetFieldName": "language",
          "mappingFunction": null
      }      
  ]

範例：加密金鑰

加密金鑰是客戶管理的金鑰，用於其他加密。如需詳細資訊，請參閱在 Azure 金鑰保存庫中使用客戶管理的密鑰進行加密。

{
    "name" : "myindexer",  
    "description" : "a cool indexer",  
    "dataSourceName" : "ordersds",  
    "targetIndexName" : "orders",  
    "schedule" : { "interval" : "PT1H", "startTime" : "2021-01-01T00:00:00Z" },  
    "parameters" : { "maxFailedItems" : 10, "maxFailedItemsPerBatch" : 5 },
    "encryptionKey": (optional) { 
      "keyVaultKeyName": "Name of the Azure Key Vault key used for encryption",
      "keyVaultKeyVersion": "Version of the Azure Key Vault key",
      "keyVaultUri": "URI of Azure Key Vault, also referred to as DNS name, that provides the key. An example URI might be https://my-keyvault-name.vault.azure.net",
      "accessCredentials": (optional, only if not using managed system identity) {
        "applicationId": "Microsoft Entra ID application ID that was granted access permissions to your specified Azure Key Vault",
        "applicationSecret": "Authentication key of the registered application)"}
      }
}