Creare un indicizzatore (API REST di Ricerca intelligenza artificiale di Azure)

Un indicizzatore automatizza l'indicizzazione da origini dati di Azure supportate, ad esempio Archiviazione di Azure, database Azure SQL e Azure Cosmos DB per citarne alcuni. Gli indicizzatori usano un'origine dati e un indice predefiniti per stabilire una pipeline di indicizzazione che estrae e serializza i dati di origine, passandoli a un servizio di ricerca per l'inserimento dei dati. Per l'arricchimento tramite intelligenza artificiale di immagini e testo non strutturato, gli indicizzatori possono anche accettare un set di competenze che definisce l'elaborazione dell'intelligenza artificiale.

La creazione di un indicizzatore lo aggiunge al servizio di ricerca e lo esegue. Se la richiesta ha esito positivo, l'indice viene popolato con contenuto ricercabile dall'origine dati.

È possibile usare POST o PUT nella richiesta. Per entrambi, il documento JSON nel corpo della richiesta fornisce la definizione dell'oggetto.

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

In alternativa, è possibile usare PUT e specificare il nome dell'indicizzatore nell'URI.

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

Per tutte le richieste del servizio, è necessario usare il protocollo HTTPS. Se l'indicizzatore non esiste, viene creato. Se esiste già, viene aggiornato alla nuova definizione, ma è necessario eseguire una richiesta Esegui indicizzatore se si vuole eseguire l'esecuzione dell'indicizzatore.

La configurazione dell'indicizzatore varia in base al tipo di origine dati. Per indicazioni specifiche della piattaforma sulla creazione di indicizzatori, iniziare dall'articolo Indicizzatori in Ricerca di Azure, che include l'elenco completo degli articoli correlati.

Parametri dell'URI

Intestazioni richiesta

La tabella seguente descrive le intestazioni della richiesta obbligatorie e facoltative.

Corpo della richiesta

Un'origine dati, un indice e un set di competenze fanno parte della definizione di indicizzatore, ma ogni elemento è un componente indipendente che può essere usato in combinazioni diverse. Si potrebbe ad esempio usare la stessa origine dati o lo stesso indice con più indicizzatori oppure più indicizzatori per scrivere in un solo indice.

Il codice JSON seguente è una rappresentazione generale delle parti principali della definizione.

{   
    "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) { }
} 

La richiesta contiene le proprietà seguenti:

Parametri di configurazione dei BLOB

Diversi parametri sono esclusivi di un determinato indicizzatore, come nel caso dell'indicizzazione del BLOB di Azure.

Parametri di configurazione di Azure Cosmos DB

I parametri seguenti sono specifici degli indicizzatori cosmos DB.

parametri di configurazione Azure SQL

I parametri seguenti sono specifici del database SQL di Azure.

Risposta

Se la richiesta ha esito positivo, viene restituito il codice di stato 201 - Creato.

Esempio

Esempio: Indicizzatore con parametri pianificati e generici

Crea un indicizzatore che copia i dati dalla tabella a cui fa riferimento l'origine dati all'indice ordersdsorders in base a una pianificazione che inizia il 1° gennaio 2021 UTC ed esegue ora. Ogni chiamata all'indicizzatore avrà esito positivo se l'indicizzazione non ha esito negativo per più di 5 elementi in ogni batch e per più di 10 elementi in totale.

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

Esempio: Indicizzatore con parametri BLOB

Facoltativamente, un indicizzatore può accettare parametri di configurazione che modificano i comportamenti di runtime. I parametri di configurazione sono delimitati da virgole nella richiesta dell'indicizzatore e sono specifici di un tipo di origine dati. I parametri di configurazione seguenti forniscono istruzioni usate per indicizzare i 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"
          } 
      }
  }

Esempio: Indicizzatore con mapping di campi

Eseguire il mapping del campo di una tabella di origine a un campo _id in un "id" indice di ricerca. Ricerca intelligenza artificiale di Azure non consente a un nome di campo di iniziare con un carattere di sottolineatura. Un mapping dei campi può risolvere le discrepanze dei nomi. Per i nomi dei campi di origine e destinazione non viene fatta distinzione tra maiuscole e minuscole. Per altre informazioni, vedere Mapping dei campi e trasformazioni.

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

Esempio: Indicizzatore con arricchimento di intelligenza artificiale

Illustra un arricchimento di intelligenza artificiale, indicato dal riferimento a e skillsetoutputFieldMappings. I set di competenze sono risorse di livello generale, definite separatamente. Questo esempio è un'abbreviazione della definizione dell'indicizzatore nell'esercitazione sull'arricchimento dell'intelligenza artificiale.

{
  "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"
    }
  }
}

Esempio: Indicizzatore con set di competenze e mapping dei campi di output

Negli scenari di arricchimento di intelligenza artificiale in cui un set di competenze è associato a un indicizzatore, è necessario aggiungere outputFieldMappings per associare qualsiasi output di un passaggio di arricchimento che fornisce contenuto a un campo ricercabile nell'indice. È sourceFieldName un nodo in un albero di arricchimento. Potrebbe essere una struttura composta compilata durante l'arricchimento da due campi separati nel documento di origine. È targetFieldName un campo in un indice di ricerca. Per altre informazioni, vedere Come eseguire il mapping dei campi di output da un set di competenze.

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

Esempio: Chiavi di crittografia

Le chiavi di crittografia sono chiavi gestite dal cliente usate per una crittografia aggiuntiva. Per altre informazioni, vedere Crittografia con chiavi gestite dal cliente in Azure Key Vault.

{
    "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)"}
      }
}

Vedi anche

• Panoramica degli indicizzatori
• Creazione di indicizzatori
• Panoramica dell'arricchimento dell'intelligenza artificiale
• Guida introduttiva: Provare l'arricchimento dell'intelligenza artificiale nel portale
• Come mappare i campi (arricchimento di intelligenza artificiale)