Mapping dei campi negli indicizzatori di Ricerca di AzureField mappings in Azure Search indexers

Quando si usano gli indicizzatori di Ricerca di Azure, a volte è possibile che i dati di input non corrispondano allo schema dell'indice di destinazione.When using Azure Search indexers, you can occasionally find yourself in situations where your input data doesn't quite match the schema of your target index. In questi casi è possibile usare i mapping dei campi per trasformare i dati nella forma desiderata.In those cases, you can use field mappings to transform your data into the desired shape.

Alcune situazioni in cui i mapping dei campi sono utili:Some situations where field mappings are useful:

  • L'origine dati include un campo _id, ma Ricerca di Azure non consente nomi di campo che iniziano con un carattere di sottolineatura.Your data source has a field _id, but Azure Search doesn't allow field names starting with an underscore. Un mapping dei campi consente di "rinominare" un campo.A field mapping allows you to "rename" a field.
  • Si vuole popolare diversi campi dell'indice con dati della stessa origine dati, ad esempio per applicare diversi analizzatori a questi campi.You want to populate several fields in the index with the same data source data, for example because you want to apply different analyzers to those fields. I mapping dei campi consentono di "biforcare" un campo dell'origine dati.Field mappings let you "fork" a data source field.
  • È necessaria la codifica o decodifica Base64 dei dati.You need to Base64 encode or decode your data. I mapping dei campi supportano diverse funzioni di mapping, incluse quelle per la codifica e decodifica Base64.Field mappings support several mapping functions, including functions for Base64 encoding and decoding.

Configurazione del mapping dei campiSetting up field mappings

È possibile aggiungere i mapping dei campi quando si crea un nuovo indicizzatore con l'API di creazione dell'indicizzatore .You can add field mappings when creating a new indexer using the Create Indexer API. È possibile gestire i mapping dei campi in un indicizzatore con l'API di aggiornamento dell'indicizzatore .You can manage field mappings on an indexing indexer using the Update Indexer API.

Un mapping dei campi è costituito da tre parti:A field mapping consists of three parts:

  1. sourceFieldName, che rappresenta un campo nell'origine dati.A sourceFieldName, which represents a field in your data source. Questa proprietà è obbligatoria.This property is required.
  2. targetFieldNamefacoltativo, che rappresenta un campo nell'indice di ricerca.An optional targetFieldName, which represents a field in your search index. Se omesso, viene usato lo stesso nome nell'origine dati.If omitted, the same name as in the data source is used.
  3. mappingFunctionfacoltativo, che può trasformare i dati usando una delle varie funzioni predefinite.An optional mappingFunction, which can transform your data using one of several predefined functions. L'elenco completo delle funzioni è riportato di seguito.The full list of functions is below.

I mapping dei campi vengono aggiunti alla matrice fieldMappings nella definizione dell'indicizzatore.Fields mappings are added to the fieldMappings array on the indexer definition.

L'esempio seguente mostra come gestire le differenze nei nomi di campo:For example, here's how you can accommodate differences in field names:


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" : "_id", "targetFieldName" : "id" } ]
}

Un indicizzatore può avere più mapping dei campi.An indexer can have multiple field mappings. L'esempio seguente mostra come "biforcare" un campo:For example, here's how you can "fork" a field:


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

Nota

Ricerca di Azure usa confronti senza distinzione tra maiuscole e minuscole per risolvere il campo e i nomi di funzione nei mapping dei campi.Azure Search uses case-insensitive comparison to resolve the field and function names in field mappings. 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.This is convenient (you don't have to get all the casing right), but it means that your data source or index cannot have fields that differ only by case.

Funzioni del mapping dei campiField mapping functions

Queste funzioni sono attualmente supportate:These functions are currently supported:

base64Encodebase64Encode

Esegue la codifica Base64 sicura per gli URL della stringa di input.Performs URL-safe Base64 encoding of the input string. Si presuppone che l'input sia con codifica UTF-8.Assumes that the input is UTF-8 encoded.

Caso d'uso di esempio - Ricerca della chiave del documentoSample use case - document key lookup

La chiave del documento di Ricerca di Azure può includere solo caratteri sicuri per gli URL, ad esempio perché i clienti devono poter fare riferimento al documento usando l'API di ricerca.Only URL-safe characters can appear in an Azure Search document key (because customers must be able to address the document using the Lookup API, for example). Se i dati contengono caratteri non sicuri per gli URL e si vuole usarli per popolare un campo chiave nell'indice di ricerca, usare questa funzione.If your data contains URL-unsafe characters and you want to use it to populate a key field in your search index, use this function. Dopo aver codificato la chiave, è possibile usare la decodifica Base64 per recuperare il valore originale.Once the key is encoded, you can use base64 decode to retrieve the original value. Per informazioni, vedere la sezione Dettagli della codifica e della decodifica Base64.For details, see the base64 encoding and decoding section.

EsempioExample


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

Caso d'uso di esempio - Recuperare la chiave originaleSample use case - retrieve original key

È presente un indicizzatore di BLOB che indicizza BLOB con i metadati del percorso BLOB come chiave del documento.You have a blob indexer that indexes blobs with the blob path metadata as the document key. Dopo aver recuperato la chiave del documento codificato, si vuole decodificare il percorso e scaricare il BLOB.After retrieving the encoded document key, you want to decode the path and download the blob.

EsempioExample


"fieldMappings" : [
  {
    "sourceFieldName" : "SourceKey",
    "targetFieldName" : "IndexKey",
    "mappingFunction" : { "name" : "base64Encode", "parameters" : { "useHttpServerUtilityUrlTokenEncode" : false } }
  }]

Se non è necessario cercare documenti in base alle chiavi né decodificare il contenuto codificato, è sufficiente escludere parameters per la funzione di mapping, in modo che il valore predefinito di useHttpServerUtilityUrlTokenEncode sia true.If you don't need to look up documents by keys and also don't need to decode the encoded content, you can just leave out parameters for the mapping function, which defaults useHttpServerUtilityUrlTokenEncode to true. In caso contrario, vedere la sezione Dettagli della codifica e della decodifica Base64 per determinare le impostazioni da usare.Otherwise, see base64 details section to decide which settings to use.

base64Decodebase64Decode

Esegue la decodifica Base64 della stringa di input.Performs Base64 decoding of the input string. Si presuppone che l'input sia una stringa con codifica Base64 sicura per gli URL .The input is assumed to a URL-safe Base64-encoded string.

Caso d'uso di esempioSample use case

I valori di metadati personalizzati BLOB devono essere codificati in ASCII.Blob custom metadata values must be ASCII-encoded. È possibile usare la codifica Base64 per rappresentare stringhe UTF-8 arbitrarie nei metadati personalizzati dei BLOB.You can use Base64 encoding to represent arbitrary UTF-8 strings in blob custom metadata. Tuttavia, per rendere significativa la ricerca, è possibile usare questa funzione per riconvertire i dati codificati in stringhe "normali" durante il popolamento dell'indice di ricerca.However, to make search meaningful, you can use this function to turn the encoded data back into "regular" strings when populating your search index.

EsempioExample


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

Se non si specifica alcun valore parameters, il valore predefinito di useHttpServerUtilityUrlTokenDecode è true.If you don't specify any parameters, then the default value of useHttpServerUtilityUrlTokenDecode is true. Vedere la sezione Dettagli della codifica e della decodifica Base64 per determinare le impostazioni da usare.See base64 details section to decide which settings to use.

Dettagli della codifica e della decodifica Base64Details of base64 encoding and decoding

Ricerca di Azure supporta due codifiche Base64: la codifica con token URL HttpServerUtility e la codifica sicura per gli URL senza spaziatura interna.Azure Search supports two base64 encodings: HttpServerUtility URL token and URL-safe base64 encoding without padding. È necessario usare la stessa codifica delle funzioni di mapping se si vuole codificare la chiave di un documento per la ricerca, codificare un valore da decodificare tramite l'indicizzatore o decodificare un campo codificato dall'indicizzatore.You need to use the same encoding as the mapping functions if you want to encode a document key for look up, encode a value to be decoded by the indexer, or decode a field encoded by the indexer.

Se si usa .NET Framework, è possibile impostare useHttpServerUtilityUrlTokenEncode e useHttpServerUtilityUrlTokenDecode su true rispettivamente per la codifica e la decodifica.If you use the .NET Framework, you can set useHttpServerUtilityUrlTokenEncode and useHttpServerUtilityUrlTokenDecode to true, for encoding and decoding respectively. base64Encode si comporta quindi come HttpServerUtility.UrlTokenEncode, mentre base64Decode si comporta come HttpServerUtility.UrlTokenDecode.Then base64Encode behaves like HttpServerUtility.UrlTokenEncode and base64Decode behaves like HttpServerUtility.UrlTokenDecode.

Se non si usa .NET Framework, è necessario impostare useHttpServerUtilityUrlTokenEncode e useHttpServerUtilityUrlTokenDecode su false.If you are not using the .NET Framework, then you should set useHttpServerUtilityUrlTokenEncode and useHttpServerUtilityUrlTokenDecode to false. A seconda della libreria usata, le funzioni dell'utilità di codifica e decodifica Base64 possono essere diverse rispetto a Ricerca di Azure.Depending on the library you use, the base64 encode and decode utility functions may be different from Azure Search.

La tabella seguente confronta diverse codifiche Base64 della stringa 00>00?00.The following table compares different base64 encodings of the string 00>00?00. Per determinare l'eventuale elaborazione aggiuntiva 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.To determine the required additional processing (if any) for your base64 functions, apply your library encode function on the string 00>00?00 and compare the output with the expected output MDA-MDA_MDA.

CodificaEncoding Output della codifica Base64Base64 encode output Elaborazione aggiuntiva dopo la codifica della libreriaAdditional processing after library encoding Elaborazione aggiuntiva prima della codifica della libreriaAdditional processing before library decoding
Base64 con spaziatura internaBase64 with padding MDA+MDA/MDA= Usare caratteri sicuri per gli URL e rimuovere la spaziatura internaUse URL-safe characters and remove padding Usare caratteri Base64 standard e aggiungere spaziatura internaUse standard base64 characters and add padding
Base64 senza spaziatura internaBase64 without padding MDA+MDA/MDA Usare caratteri sicuri per gli URLUse URL-safe characters Usare caratteri Base64 standardUse standard base64 characters
Base64 sicura per gli URL con spaziatura internaURL-safe base64 with padding MDA-MDA_MDA= Rimuovere la spaziatura internaRemove padding Aggiungere spaziatura internaAdd padding
Base64 sicura per gli URL senza spaziatura internaURL-safe base64 without padding MDA-MDA_MDA NessunoNone NessunoNone

extractTokenAtPositionextractTokenAtPosition

Divide un campo stringa usando il delimitatore specificato e sceglie il token nella posizione specificata della divisione risultante.Splits a string field using the specified delimiter, and picks the token at the specified position in the resulting split.

Ad esempio, se l'input è Jane Doe, delimiter è " " (spazio) e position è 0, il risultato è Jane; se position è 1, il risultato è Doe.For example, if the input is Jane Doe, the delimiter is " "(space) and the position is 0, the result is Jane; if the position is 1, the result is Doe. Se la posizione fa riferimento a un token che non esiste, viene restituito un errore.If the position refers to a token that doesn't exist, an error is returned.

Caso d'uso di esempioSample use case

L'origine dati contiene un campo PersonName e si vuole indicizzarla come due campi separati, FirstName e LastName.Your data source contains a PersonName field, and you want to index it as two separate FirstName and LastName fields. È possibile usare questa funzione per dividere l'input usando il carattere spazio come delimitatore.You can use this function to split the input using the space character as the delimiter.

ParametriParameters

  • delimiter: stringa da usare come separatore quando si divide la stringa di input.delimiter: a string to use as the separator when splitting the input string.
  • position: posizione in base zero di tipo integer del token da scegliere dopo la divisione della stringa di input.position: an integer zero-based position of the token to pick after the input string is split.

EsempioExample


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

jsonArrayToStringCollectionjsonArrayToStringCollection

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.Transforms a string formatted as a JSON array of strings into a string array that can be used to populate a Collection(Edm.String) field in the index.

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.For example, if the input string is ["red", "white", "blue"], then the target field of type Collection(Edm.String) will be populated with the three values red, white, and blue. Per i valori di input che non possono essere analizzati come matrici di stringhe JSON, viene restituito un errore.For input values that cannot be parsed as JSON string arrays, an error is returned.

Caso d'uso di esempioSample use case

Il database SQL di Azure non ha un tipo di dati predefinito che esegue normalmente il mapping ai campi Collection(Edm.String) in Ricerca di Azure.Azure SQL database doesn't have a built-in data type that naturally maps to Collection(Edm.String) fields in Azure Search. Per popolare i campi della raccolta di stringhe, formattare i dati di origine come matrice di stringhe JSON e usare questa funzione.To populate string collection fields, format your source data as a JSON string array and use this function.

EsempioExample


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

Come contribuire al miglioramento di Ricerca di AzureHelp us make Azure Search better

Se si hanno domande sulle funzionalità o idee per apportare miglioramenti, contattare Microsoft sul sito UserVoice.If you have feature requests or ideas for improvements, please reach out to us on our UserVoice site.