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

索引器會從支援的 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 參數

要求標頭

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

要求本文

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

下列 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) { }
} 

要求可包含下列屬性：

Blob 組態參數

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

Azure Cosmos DB 組態參數

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

Azure SQL 組態參數

下列參數專屬於 Azure SQL Database。

回應

「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 }  
}

範例：具有 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)"}
      }
}

另請參閱

• 索引子概觀
• 建立索引器
• AI 擴充概觀
• 快速入門：在入口網站中試用 AI 擴充
• 如何對應 AI 擴充 (欄位)