Mapping dei campi e trasformazioni con gli indicizzatori di Azure AI Search

Articolo
10/16/2024

Questo articolo illustra come impostare mapping di campi espliciti che stabiliscono il percorso dati tra i campi di origine in un'origine dati supportata e i campi di destinazione in un indice di ricerca.

Quando impostare un mapping dei campi

Quando un indicizzatore di Azure AI Search carica un indice di ricerca, determina il percorso dei dati usando mapping dei campi da origine a destinazione. I mapping dei campi impliciti sono interni e si verificano quando i nomi dei campi e i tipi di dati sono compatibili tra l'origine e la destinazione. Se gli input e gli output non corrispondono, è possibile definire i mapping dei campi espliciti per configurare il percorso dati, come descritto in questo articolo.

I mapping dei campi possono essere usati anche per le conversioni di dati leggeri, ad esempio la codifica o la decodifica, tramite funzioni di mapping. Se è necessaria un'ulteriore elaborazione, prendere in considerazione Azure Data Factory per colmare il divario.

I mapping dei campi si applicano a:

Strutture di dati fisici su entrambi i lati del percorso dati. Le strutture di dati logiche create dalle competenze risiedono solo in memoria. Usare outputFieldMappings per eseguire il mapping dei nodi in memoria ai campi di output in un indice di ricerca.
Solo indici di ricerca di intelligenza artificiale padre. Per gli indici "secondari" con documenti "figlio" o "blocchi", vedere gli scenari di mapping dei campi avanzati.
Solo i campi di ricerca di primo livello, in cui il targetFieldName è un campo semplice o una raccolta. Un campo di destinazione non può essere un tipo complesso.

Scenari supportati

Assicurarsi di usare un'origine dati supportata per l’indicizzazione guidata dall'indicizzatore.

Caso d'uso	Descrizione
Discrepanza dei nomi	Si supponga che l'origine dati abbia un campo denominato `_city`. Dato che Ricerca intelligenza artificiale di Azure non consente nomi di campo che iniziano con un carattere di sottolineatura, un mapping dei campi consente di eseguire in modo efficace il mapping di "_city" a "city". Se i requisiti di indicizzazione includono il recupero di contenuto da più origini dati, in cui i nomi dei campi variano tra le origini, è possibile usare un mapping dei campi per chiarire il percorso.
Discrepanza tra i tipi	Supponendo che si desideri che un campo di tipo integer di origine sia di tipo `Edm.String` in modo che sia ricercabile nell'indice di ricerca. Poiché i tipi sono diversi, è necessario definire un mapping dei campi affinché il percorso dati abbia esito positivo. Si noti che Ricerca intelligenza artificiale di Azure include un set di tipi di dati supportati rispetto a molte origini dati. Se si importano dati SQL, un mapping dei campi consente di eseguire il mapping del tipo di dati SQL desiderato in un indice di ricerca.
Percorsi dati uno-a-molti	È possibile popolare più campi nell'indice con contenuto dello stesso campo di origine. Ad esempio, è possibile applicare analizzatori diversi a ogni campo per supportare casi d'uso diversi nell'app client.
Codifica e decodifica	È possibile applicare funzioni di mapping per supportare la codifica Base64 o la decodifica dei dati durante l'indicizzazione.
Dividere stringhe o eseguire di nuovo il casting delle matrici in raccolte	È possibile applicare funzioni di mapping per suddividere una stringa che include un delimitatore o inviare una matrice JSON a un campo di ricerca di tipo `Collection(Edm.String)`.

Nota

Se non sono presenti mapping di campi, gli indicizzatori presuppongono che i campi dell'origine dati vengano mappati ai campi di indice con lo stesso nome. L'aggiunta di un mapping dei campi sostituisce i mapping dei campi predefiniti per il campo di origine e di destinazione. Alcuni indicizzatori, ad esempio l'indicizzatore di archiviazione BLOB, aggiungono automaticamente mapping di campi predefiniti per il campo chiave di indice.

I campi complessi non sono supportati in un mapping dei campi. La struttura di origine (strutture annidate o gerarchiche) deve corrispondere esattamente al tipo complesso nell'indice in modo che i mapping predefiniti funzionino. Per altre informazioni, vedere Esercitazione: Indicizzare BLOB JSON annidati per un esempio. Se viene visualizzato un errore simile a "Field mapping specifies target field 'Address/city' that doesn't exist in the index", perché i mapping dei campi di destinazione non possono essere un tipo complesso.

Facoltativamente, è possibile che nella struttura complessa siano presenti solo alcuni nodi. Per ottenere singoli nodi, è possibile rendere flat i dati in ingresso in una raccolta di stringhe (vedere outputFieldMappings per questa soluzione alternativa).

Definire un mapping dei campi

In questa sezione vengono illustrati i passaggi per la configurazione dei mapping dei campi.

API REST
.NET SDK (C#)

Usare Crea indicizzatore o Crea o Aggiorna indicizzatore o un metodo equivalente in Azure SDK. Ecco un esempio di definizione dell'indicizzatore.

{
   "name": "myindexer",
   "description": null,
   "dataSourceName": "mydatasource",
   "targetIndexName": "myindex",
   "schedule": { },
   "parameters": { },
   "fieldMappings": [],
   "disabled": false,
   "encryptionKey": { }
 }

Compilare la matrice fieldMappings per specificare i mapping. Un mapping dei campi è costituito da tre parti.

"fieldMappings": [
  {
    "sourceFieldName": "_city",
    "targetFieldName": "city",
    "mappingFunction": null
  }
]

Proprietà	Descrizione
sourceFieldName	Obbligatorio. Rappresenta un campo nell'origine dati.
targetFieldName	Facoltativo. Rappresenta un campo nell'indice di ricerca. Se omesso, viene utilizzato il valore di `sourceFieldName` per la destinazione. I campi di destinazione devono essere campi o raccolte semplici di primo livello. Non può essere un tipo o una raccolta complessa. Se si gestisce un problema del tipo di dati, il tipo di dati di un campo viene specificato nella definizione dell'indice. Il mapping dei campi deve avere solo il nome del campo.
mappingFunction	Facoltativo. È costituito da funzioni predefinite che trasformano i dati.

Esempio: Discrepanza tra nome o tipo

Un mapping esplicito dei campi stabilisce un percorso dati per i casi in cui nome e tipo non sono identici.

Azure AI Search usa confronti senza distinzione tra maiuscole e minuscole per risolvere il campo e i nomi di funzione nei mapping dei campi. Questa caratteristica è utile perché non è necessario fare attenzione all'uso di maiuscole e minuscole, ma significa anche che l'origine dati o l'indice non può contenere campi differenziati solo in base all'uso di maiuscole e minuscole.

PUT https://[service name].search.windows.net/indexers/myindexer?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
{
    "dataSourceName" : "mydatasource",
    "targetIndexName" : "myindex",
    "fieldMappings" : [ { "sourceFieldName" : "_city", "targetFieldName" : "city" } ]
}

Esempio: percorsi dati uno-a-molti o con fork

In questo esempio viene eseguito il mapping di un singolo campo di origine a più campi di destinazione ("mapping uno-a-molti"). È possibile "creare una copia tramite fork" di un campo, copiando lo stesso contenuto del campo di origine in due campi di indice diversi che verranno analizzati o attribuiti in modo diverso nell'indice.


"fieldMappings" : [
    { "sourceFieldName" : "text", "targetFieldName" : "textStandardEnglishAnalyzer" },
    { "sourceFieldName" : "text", "targetFieldName" : "textSoundexAnalyzer" }
]

È possibile usare un approccio simile per il contenuto generato da competenze.

In Azure SDK per .NET usare la classe FieldMapping che fornisce proprietà SourceFieldName e TargetFieldName e un riferimento MappingFunction facoltativo.

Specificare i mapping dei campi quando si costruisce l'indicizzatore o versioni successive impostando direttamente SearchIndexer.FieldMappings. Nell'esempio C# seguente vengono impostati i mapping dei campi durante la costruzione di un indicizzatore.

var indexer = new SearchIndexer("hotels-sql-idxr", dataSource.Name, searchIndex.Name)
{
    Description = "SQL data indexer",
    Schedule = schedule,
    Parameters = parameters,
    FieldMappings =
    {
        new FieldMapping("_hotelId") {TargetFieldName = "HotelId", FieldMappingFunction.Base64Encode()},
        new FieldMapping("Amenities") {TargetFieldName = "Tags"}
    }
};

await indexerClient.CreateOrUpdateIndexerAsync(indexer);

Funzioni ed esempi di mapping

Una funzione di mapping dei campi trasforma il contenuto di un campo prima che venga archiviato nell'indice. Sono attualmente supportate le funzioni di mapping seguenti:

base64Encode
base64Decode
extractTokenAtPosition
jsonArrayToStringCollection
urlEncode
urlDecode

Si noti che queste funzioni sono supportate esclusivamente per gli indici padre in questo momento. Non sono compatibili con il mapping degli indici in blocchi, pertanto queste funzioni non possono essere usate per proiezioni di indici.

Funzione base64Encode

Esegue la codifica Base64 sicura per gli URL della stringa di input. Si presuppone che l'input sia con codifica UTF-8.

Esempio: Codifica di base di una chiave del documento

Solo i caratteri sicuri dell'URL possono essere visualizzati in una chiave del documento di Ricerca intelligenza artificiale di Azure, in modo da poter indirizzare il documento usando l'API Ricerca. Se il campo di origine per la chiave contiene caratteri URL-unsafe, ad esempio - e \, usare la funzione base64Encode per convertirla in fase di indicizzazione.

Nell'esempio seguente viene specificata la funzione base64Encode su metadata_storage_name per gestire i caratteri non supportati.

PUT /indexers?api-version=2024-07-01
{
  "dataSourceName" : "my-blob-datasource ",
  "targetIndexName" : "my-search-index",
  "fieldMappings" : [
    { 
        "sourceFieldName" : "metadata_storage_name", 
        "targetFieldName" : "key", 
        "mappingFunction" : { 
            "name" : "base64Encode",
            "parameters" : { "useHttpServerUtilityUrlTokenEncode" : false }
        } 
    }
  ]
}

Una chiave del documento (prima e dopo la conversione) non può superare i 1.024 caratteri. Quando si recupera la chiave codificata in fase di ricerca, usare la funzione base64Decode per ottenere il valore della chiave originale e usarla per recuperare il documento di origine.

Esempio: rendere un campo con codifica base "ricercabile"

In alcuni casi è necessario usare una versione codificata di un campo come metadata_storage_path come chiave, ma è necessaria anche una versione non codificata per la ricerca full-text. Per supportare entrambi gli scenari, è possibile eseguire il mapping di metadata_storage_path a due campi: uno per la chiave (codificata) e un secondo per un campo di percorso che è possibile presupporre sia attribuito come searchable nello schema dell'indice.

PUT /indexers/blob-indexer?api-version=2024-07-01
{
    "dataSourceName" : " blob-datasource ",
    "targetIndexName" : "my-target-index",
    "schedule" : { "interval" : "PT2H" },
    "fieldMappings" : [
        { "sourceFieldName" : "metadata_storage_path", "targetFieldName" : "key", "mappingFunction" : { "name" : "base64Encode" } },
        { "sourceFieldName" : "metadata_storage_path", "targetFieldName" : "path" }
      ]
}

Esempio: mantenere i valori originali

L'indicizzatore di archiviazione BLOB aggiunge automaticamente un mapping dei campi da metadata_storage_path, l'URI del BLOB, al campo della chiave di indice se non viene specificato alcun mapping dei campi. Questo valore è codificato in Base64, quindi è sicuro da usare come chiave del documento di Ricerca intelligenza artificiale di Azure. Nell'esempio seguente viene illustrato come eseguire contemporaneamente il mapping di una versione con codifica Base64 indipendente dall'URL di metadata_storage_path a un campo index_key e mantenere il valore originale in un campo metadata_storage_path:

"fieldMappings": [
  {
    "sourceFieldName": "metadata_storage_path",
    "targetFieldName": "metadata_storage_path"
  },
  {
    "sourceFieldName": "metadata_storage_path",
    "targetFieldName": "index_key",
    "mappingFunction": {
       "name": "base64Encode"
    }
  }
]

Se non si include una proprietà parametri per la funzione di mapping, il valore predefinito è {"useHttpServerUtilityUrlTokenEncode" : true}.

Ricerca di intelligenza artificiale di Azure supporta due diverse codifiche Base64. È consigliabile usare gli stessi parametri durante la codifica e la decodifica dello stesso campo. Per altre informazioni, vedere opzioni di codifica base64 per decidere quali parametri usare.

funzione base64Decode

Esegue la decodifica Base64 della stringa di input. Si presuppone che l'input sia una stringa con codifica Base64 sicura per gli URL.

Esempio: decodificare i metadati o gli URL del BLOB

I dati di origine possono contenere stringhe con codifica Base64, ad esempio stringhe di metadati BLOB o URL Web, che si desidera rendere ricercabile come testo normale. È possibile usare la funzione base64Decode per ripristinare i dati codificati in stringhe regolari durante il popolamento dell'indice di ricerca.

"fieldMappings" : [
  {
    "sourceFieldName" : "Base64EncodedMetadata",
    "targetFieldName" : "SearchableMetadata",
    "mappingFunction" : { 
      "name" : "base64Decode", 
      "parameters" : { "useHttpServerUtilityUrlTokenDecode" : false }
    }
  }
]

Se non si include una proprietà parametri, per impostazione predefinita il valore {"useHttpServerUtilityUrlTokenEncode" : true}.

Opzioni di codifica base64

Ricerca di intelligenza artificiale di Azure supporta la codifica base64 sicura degli URL e la normale codifica base64. Una stringa con codifica Base64 durante l'indicizzazione deve essere decodificata in un secondo momento con le stesse opzioni di codifica oppure il risultato non corrisponde all'originale.

Se i parametri useHttpServerUtilityUrlTokenEncode oppure useHttpServerUtilityUrlTokenDecode per la codifica e decodifica vengono rispettivamente impostati su true, allora base64Encode si comporta come HttpServerUtility.UrlTokenEncode e base64Decode si comporta come HttpServerUtility.UrlTokenDecode.

Avviso

Se base64Encode viene usato per produrre valori di chiave, useHttpServerUtilityUrlTokenEncode deve essere impostato su true. Per i valori delle chiavi è possibile usare solo la codifica base64 indipendente dall'URL. Vedere regole di denominazione per il set completo di restrizioni sui caratteri nei valori chiave.

Le librerie .NET in Ricerca di intelligenza artificiale di Azure presuppongono .NET Framework completo, che fornisce la codifica predefinita. Le opzioni useHttpServerUtilityUrlTokenEncode e useHttpServerUtilityUrlTokenDecode applicano questa funzionalità predefinita. Se si usa .NET Core o un altro framework, è consigliabile impostare tali opzioni su false e chiamare direttamente le funzioni di codifica e decodifica del framework.

La tabella seguente confronta diverse codifiche Base64 della stringa 00>00?00. Per determinare l'eventuale elaborazione necessaria per le funzioni Base64, applicare la funzione di codifica della libreria nella stringa 00>00?00 e confrontare l'output con l'output previsto MDA-MDA_MDA.

Codifica	Output della codifica Base64	Elaborazione aggiuntiva dopo la codifica della libreria	Elaborazione aggiuntiva prima della codifica della libreria
Base64 con spaziatura interna	`MDA+MDA/MDA=`	Usare caratteri sicuri per gli URL e rimuovere la spaziatura interna	Usare caratteri Base64 standard e aggiungere spaziatura interna
Base64 senza spaziatura interna	`MDA+MDA/MDA`	Usare caratteri sicuri per gli URL	Usare caratteri Base64 standard
Base64 sicura per gli URL con spaziatura interna	`MDA-MDA_MDA=`	Rimuovere la spaziatura interna	Aggiungere spaziatura interna
Base64 sicura per gli URL senza spaziatura interna	`MDA-MDA_MDA`	None	None

Funzione extractTokenAtPosition

Divide un campo stringa usando il delimitatore specificato e sceglie il token nella posizione specificata della divisione risultante.

Questa funzione usa i parametri seguenti:

delimiter: stringa da usare come separatore quando si divide la stringa di input.
position: posizione in base zero di tipo integer del token da scegliere dopo la divisione della stringa di input.

Ad esempio, se l'input è Jane Doe, delimiter è " " (spazio) e position è 0, il risultato è Jane; se position è 1, il risultato è Doe. Se la posizione fa riferimento a un token che non esiste, viene restituito un errore.

Esempio: estrarre un nome

L'origine dati contiene un campo PersonName e si vuole indicizzarla come due campi separati, FirstName e LastName. È possibile usare questa funzione per dividere l'input usando il carattere spazio come delimitatore.

"fieldMappings" : [
  {
    "sourceFieldName" : "PersonName",
    "targetFieldName" : "FirstName",
    "mappingFunction" : { "name" : "extractTokenAtPosition", "parameters" : { "delimiter" : " ", "position" : 0 } }
  },
  {
    "sourceFieldName" : "PersonName",
    "targetFieldName" : "LastName",
    "mappingFunction" : { "name" : "extractTokenAtPosition", "parameters" : { "delimiter" : " ", "position" : 1 } }
  }]

Funzione jsonArrayToStringCollection

Trasforma una stringa formattata come matrice di stringhe JSON in una matrice di stringhe che può essere usata per popolare un campo Collection(Edm.String) nell'indice.

Ad esempio, se la stringa di input è ["red", "white", "blue"], il campo di destinazione di tipo Collection(Edm.String) viene popolato con i tre valori red, white e blue. Per i valori di input che non possono essere analizzati come matrici di stringhe JSON, viene restituito un errore.

Esempio: popolare la raccolta da dati relazionali

Il database SQL di Azure non ha un tipo di dati predefinito che esegue normalmente il mapping ai campi Collection(Edm.String) in Azure AI Search. Per popolare i campi della raccolta di stringhe, è possibile pre-elaborare i dati di origine come matrice di stringhe JSON e quindi usare la funzione di mapping jsonArrayToStringCollection.

"fieldMappings" : [
  {
    "sourceFieldName" : "tags", 
    "mappingFunction" : { "name" : "jsonArrayToStringCollection" }
  }]

Funzione urlEncode

Questa funzione può essere usata per codificare una stringa in modo che sia "sicura per l'URL". Se usato con una stringa che contiene caratteri non consentiti in un URL, questa funzione convertirà tali caratteri "non sicuri" in equivalenti di entità carattere. Questa funzione usa il formato di codifica UTF-8.

Esempio - Ricerca chiave documento

La funzione urlEncode può essere usata come alternativa alla funzione base64Encode, se devono essere convertiti solo i caratteri url non sicuri, mantenendo così invariati gli altri caratteri.

Ad esempio, la stringa di input è <hello>, quindi il campo di destinazione di tipo (Edm.String) verrà popolato con il valore %3chello%3e

Quando si recupera la chiave codificata in fase di ricerca, è quindi possibile usare la funzione urlDecode per ottenere il valore della chiave originale e usarla per recuperare il documento di origine.

"fieldMappings" : [
  {
    "sourceFieldName" : "SourceKey",
    "targetFieldName" : "IndexKey",
    "mappingFunction" : {
      "name" : "urlEncode"
    }
  }
]

Funzione urlDecode

Questa funzione converte una stringa con codifica URL in una stringa decodificata usando il formato di codifica UTF-8.

Esempio: decodificare i metadati del BLOB

Alcuni client di archiviazione di Azure codificano automaticamente i metadati del BLOB se contengono caratteri non ASCII. Tuttavia, se si desidera rendere tali metadati ricercabili (come testo normale), è possibile usare la funzione urlDecode per trasformare i dati codificati in stringhe regolari durante il popolamento dell'indice di ricerca.

"fieldMappings" : [
  {
    "sourceFieldName" : "UrlEncodedMetadata",
    "targetFieldName" : "SearchableMetadata",
    "mappingFunction" : {
      "name" : "urlDecode"
    }
  }
]

Funzione fixedLengthEncode

Questa funzione converte una stringa di qualsiasi lunghezza in una stringa a lunghezza fissa.

Esempio: eseguire il mapping delle chiavi del documento troppo lunghe

Quando si verificano errori correlati alla lunghezza della chiave del documento superiore a 1024 caratteri, questa funzione può essere applicata per ridurre la lunghezza della chiave del documento.


"fieldMappings" : [
 {
   "sourceFieldName" : "metadata_storage_path",
   "targetFieldName" : "your key field",
   "mappingFunction" : {
     "name" : "fixedLengthEncode"
   }
 }
]

Funzione toJson

Questa funzione converte una stringa in un oggetto JSON formattato. Può essere usato per scenari in cui l'origine dati, ad esempio Azure SQL, non supporta in modo nativo i tipi di dati composti o gerarchici e quindi ne esegue il mapping a campi complessi.

Esempio: eseguire il mapping del contenuto di testo a un campo complesso

Si supponga che sia presente una riga SQL con una stringa JSON che deve essere mappata a un campo complesso (corrispondentemente definito) nell'indice, la funzione toJson può essere usata per ottenere questo risultato. Ad esempio, se un campo complesso nell'indice deve essere popolato con i dati seguenti:

{
    "id": "5",
    "info": {
        "name": "Jane",
        "surname": "Smith",
        "skills": [
            "SQL",
            "C#",
            "Azure"
        ],
        "dob": "2005-11-04T12:00:00"
    }
}

Può essere ottenuto usando la funzione di mapping toJson in una colonna stringa JSON in una riga SQL simile alla seguente: {"id": 5, "info": {"name": "Jane", "surname": "Smith", "skills": ["SQL", "C#", "Azure"]}, "dob": "2005-11-04T12:00:00"}.

Il mapping dei campi deve essere specificato come illustrato di seguito.


"fieldMappings" : [
  {
    "sourceFieldName" : "content",
    "targetFieldName" : "complexField",
    "mappingFunction" : {
      "name" : "toJson"
    }
  }
]

Scenari avanzati di mapping dei campi

Negli scenari in cui sono presenti relazioni tra documenti "uno-a-molti", come nel caso di raggruppamenti o suddivisioni di dati, seguire le seguenti linee guida per il mapping dei campi dai documenti padre ai documenti “figlio” (blocchi):

1. Ignorare l'indicizzazione dei documenti padre

Se si ignora l'indicizzazione dei documenti padre (impostando projectionMode su skipIndexingParentDocuments nei indexProjectionsdel set di competenze), usare proiezioni di indici per eseguire il mapping dei campi dai documenti padre ai documenti "figlio".

2. Indicizzazione di documenti padre e "figlio"

Se si esegue l'indicizzazione di documenti padre e documenti "figlio":

Usare i mapping dei campi per eseguire il mapping dei campi ai documenti padre.
Usare proiezioni di indici per eseguire il mapping dei campi sui documenti "figlio".

3. Mapping dei valori trasformati da funzione a documenti padre e/o "figlio"

Se un campo nel documento padre richiede una trasformazione (usando le funzioni di mapping ad esempio la codifica) e deve essere mappato ai documenti padre e/o "figlio":

Applicare la trasformazione usando le funzioni del mapping dei campi nell'indicizzatore.
Usare le proiezioni di indici nel set di competenze per eseguire il mapping del campo trasformato ai documenti "figlio".

Condividi tramite