Mappages de champs et transformations à l’aide d’indexeurs Azure AI Recherche

Article
03/17/2024

Quand un indexeur Recherche Azure AI charge un index de recherche, il détermine le chemin d’accès des données en utilisant des mappages de champs source à destination. Les mappages de champs implicites sont internes et se produisent lorsque les noms de champs et les types de données sont compatibles entre la source et la destination. Si les entrées et sorties ne correspondent pas, vous pouvez définir des mappages de champs explicites pour configurer le chemin d’accès aux données, comme décrit dans cet article.

Les mappages de champs peuvent également être utilisés pour des conversions de données légères, comme l’encodage ou le décodage, via des fonctions de mappage. Si un traitement plus important est nécessaire, envisagez Azure Data Factory pour combler l’écart.

Les mappages de champs s’appliquent aux éléments suivants :

Les structures de données physiques des deux côtés du flux de données (entre les champs d’une source de données prise en charge et les champs d’un index de recherche). Si vous importez du contenu enrichi par des compétences qui réside en mémoire, utilisez outputFieldMappings faire mapper les nœuds en mémoire à des champs de sortie dans un index de recherche.
Les index de recherche uniquement. Si vous remplissez une base de connaissances, utilisez des projections pour la configuration du chemin des données.
Des champs de recherche du plus haut niveau seulement, où targetFieldName est un champ simple ou une collection. Un champ cible ne peut pas être un type complexe.

Remarque

Si vous utilisez des données complexes (structures imbriquées ou hiérarchiques) et que vous souhaitez reproduire fidèlement cette structure de données dans votre index de recherche, l’index de recherche doit correspondre exactement à la structure source (mêmes noms, niveaux et types de champs) afin que les mappages par défaut fonctionnent. Vous pouvez aussi avoir seulement besoin de quelques nœuds dans la structure complexe. Pour obtenir des nœuds individuels, aplatissez les données entrantes dans une collection de chaînes (voir outputFieldMappings pour cette autre solution).

Scénarios pris en charge

Cas d’utilisation	Description
Disparité de nom	Supposons que votre source de données comprend un champ nommé `_city`. Comme Azure AI Recherche n’autorise pas les noms de champs commençant par un trait de soulignement, un mappage de champs vous permet de mapper « _city » à « city ». Si vos exigences d’indexation incluent la récupération de contenu à partir de plusieurs sources de données, où les noms de champs varient entre les sources, vous pouvez utiliser un mappage de champs pour clarifier le chemin.
Disparité de type	Supposez que vous souhaitiez qu’un champ source d’entiers soit de type `Edm.String` afin qu’il puisse faire l’objet d’une recherche dans l’index de recherche. Étant donné que les types sont différents, vous devez définir un mappage de champs qui puisse résoudre correctement le chemin des données. Notez qu’Azure AI Recherche a un plus petit ensemble de types de données pris en charge que beaucoup de sources de données. Si vous importez des données SQL, un mappage de champs vous permet de mapper le type de données SQL souhaité dans un index de recherche.
Chemins de données un-à-plusieurs	Vous pouvez remplir plusieurs champs dans l’index avec du contenu provenant du même champ source. Par exemple, vous pouvez appliquer différents analyseurs à chaque champ pour prendre en charge plusieurs cas d’usage dans votre application cliente.
Encodage et décodage	Vous pouvez appliquer des fonctions de mappage pour prendre en charge l’encodage base64 ou le décodage des données pendant l’indexation.
Diviser des chaînes ou recaster des tableaux en collections	Vous pouvez appliquer des fonctions de mappage pour diviser une chaîne qui inclut un délimiteur ou pour envoyer un tableau JSON vers un champ de recherche de type `Collection(Edm.String)`.

Définir un mappage de champs

Les mappages de champs sont ajoutés au tableau fieldMappings d’une définition d’indexeur. Un mappage de champs se compose de trois parties.

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

Propriété	Description
sourceFieldName	Obligatoire. Représente un champ de votre source de données.
targetFieldName	facultatif. Représente un champ de votre index de recherche. Si elle est omise, la valeur de `sourceFieldName` est utilisée pour la cible. Les champs cibles doivent être des champs ou collections simples de premier niveau. Il ne peut pas s’agir d’un type ou d’une collection complexe. Si vous rencontrez un problème de type de données, sachez que le type de données d’un champ est spécifié dans la définition d’index. Le mappage de champs requiert seulement d’avoir le nom de champ.
mappingFunction	facultatif. Se compose de fonctions prédéfinies qui transforment des données.

Si vous obtenez une erreur similaire à "Field mapping specifies target field 'Address/city' that doesn't exist in the index", c’est parce que les mappages de champs cibles ne peuvent pas être d’un type complexe. La solution de contournement consiste à créer un schéma d’index identique au contenu brut pour les noms des champs et les types de données. Consultez Tutoriel : Indexer des blobs JSON imbriqués pour obtenir un exemple.

Azure AI Recherche utilise une comparaison qui ne respecte pas la casse pour résoudre les noms de champ et de fonction dans les mappages de champs. C'est pratique (vous n'avez besoin de faire attention à la casse), mais cela signifie que votre source de données et votre index ne peuvent pas comporter des champs qui diffèrent uniquement par la casse.

Remarque

Si aucun mappage de champs n’est présent, les indexeurs supposent que les champs de source de données doivent être mappés à des champs d’index du même nom. L’ajout d’un mappage de champs remplace les mappages de champs par défaut pour les champs source et cible. Certains indexeurs, comme l’indexeur de stockage d’objets blob, ajoutent des mappages de champs par défaut pour le champ de clé d’index.

Vous pouvez utiliser l’API REST ou un SDK Azure pour définir les mappages de champs.

API REST
Kit de développement logiciel (SDK) .NET (C#)

Utilisez Create Indexer (REST) ou Update Indexer (REST) dans la version de l’API de votre choix.

Cet exemple résout une disparité de nom de champ.

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

Cet exemple mappe un champ source unique à plusieurs champs cibles (« mappages un-à-plusieurs »). Vous pouvez dupliquer (« fork ») un champ en copiant le même contenu de champ source vers deux champs d’index différents qui seront analysés ou attribués différemment dans l’index.


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

Dans le Kit de développement logiciel (SDK) Azure pour .NET, utilisez la classe FieldMapping qui fournit les propriétés SourceFieldName et TargetFieldName ainsi qu’une référence MappingFunction facultative.

Spécifiez des mappages de champs lors de la construction de l’indexeur, ou ultérieurement en définissant directement SearchIndexer.FieldMappings. L’exemple C# suivant définit les mappages de champs lors de la construction d’un indexeur.

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);

Fonctions et exemples de mappage

Une fonction de mappage de champ transforme le contenu d’un champ avant son stockage dans l’index. Les fonctions de mappage actuellement prises en charge sont les suivantes :

base64Encode
base64Decode
extractTokenAtPosition
jsonArrayToStringCollection
urlEncode
urlDecode

Fonction base64Encode

Exécute l’encodage Base64 sécurisé pour les URL de la chaîne d'entrée. Suppose que l'entrée est encodée en UTF-8.

Exemple : codage base d’une clé de document

Seuls les caractères sécurisés pour les URL peuvent apparaître dans une clé de document Azure AI Recherche, de façon à ce que vous puissiez traiter le document à l’aide de l’API de recherche. Si le champ source de votre clé contient des caractères non sécurisés pour les URL, comme - et \, utilisez la fonction base64Encode pour les convertir au moment de l’indexation.

L’exemple suivant spécifie la fonction base64Encode sur metadata_storage_name pour gérer les caractères non pris en charge.

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

Une clé de document (avant et après la conversion) ne doit pas dépasser 1 024 caractères. Une fois que vous avez récupéré la clé encodée au moment de la recherche, utilisez la fonction base64Decode pour obtenir la valeur de clé d’origine, et l’utiliser pour récupérer le document source.

Exemple : Créer un champ « recherchable » codé en base

Vous pouvez avoir besoin d’utiliser une version encodée d’un champ comme metadata_storage_path en tant que clé, mais aussi avoir besoin d’une version décodée pour la recherche en texte intégral. Pour prendre en charge les deux scénarios, vous pouvez mapper metadata_storage_path à deux champs : un pour la clé (encodé), et un second pour un champ de chemin d’accès dont nous pouvons supposer qu’il a un attribut searchabledans le schéma d’index.

PUT /indexers/blob-indexer?api-version=2020-06-30
{
    "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" }
      ]
}

Exemple : conserver les valeurs d’origine

L’indexeur de stockage d’objets blob ajoute automatiquement un mappage de champs à partir de metadata_storage_path, l’URI de l’objet blob, au champ de clé d’index si aucun mappage de champs n’est spécifié. Cette valeur est encodée en Base64 afin d’être utilisée en toute sécurité comme clé de document Azure AI Recherche. L’exemple suivant montre comment mapper simultanément une version de metadata_storage_path en codage Base64 sécurisée pour les URL à un champ index_key et conserver la valeur d’origine dans un champ metadata_storage_path :

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

Si vous n’incluez aucune propriété de paramètre pour votre fonction de mappage, la valeur par défaut est {"useHttpServerUtilityUrlTokenEncode" : true}.

Azure AI Recherche prend en charge deux encodages en Base64 différents. Vous devez utiliser les mêmes paramètres lors de l’encodage et du décodage du même champ. Pour décider quels paramètres utiliser, consultez les options relatives à l’encodage base64.

Fonction base64Decode

Effectue le décodage en Base64 de la chaîne d'entrée. L’entrée est considérée comme une chaîne encodée en Base64 et sécurisée pour les URL.

Exemple : décodage de métadonnées de blob ou d’URL

Votre source de données peut contenir des chaînes encodées en Base64, telles que des chaînes de métadonnées de blob ou des URL web, que vous voulez rendre disponibles pour des recherches sous la forme de texte brut. Vous pouvez utiliser la fonction base64Decode pour transformer les données encodées en chaînes normales lors du remplissage de votre index de recherche.

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

Si vous n’incluez aucune propriété de paramètre, la valeur par défaut est {"useHttpServerUtilityUrlTokenEncode" : true}.

Options d’encodage en Base64

Azure AI Recherche prend en charge l’encodage en base64 normal et sécurisé pour les URL. Une chaîne encodée en base64 lors de l’indexation devra être décodée ultérieurement avec les mêmes options d’encodage. Dans le cas contraire, le résultat ne correspondra pas à la version d’origine.

Si les paramètres useHttpServerUtilityUrlTokenEncode ou useHttpServerUtilityUrlTokenDecode d’encodage et de décodage, respectivement, sont définis sur true, base64Encode se comporte comme HttpServerUtility.UrlTokenEncode et base64Decode se comporte comme HttpServerUtility.UrlTokenDecode.

Avertissement

Si base64Encode est utilisé pour générer des valeurs de clé, useHttpServerUtilityUrlTokenEncode doit être défini sur true. Seul l’encodage en base64 sécurisé pour les URL peut être utilisé pour les valeurs de clés. Pour obtenir l’ensemble des restrictions appliquées aux caractères des valeurs de clé, consultez Règles de nommage.

Les bibliothèques .NET dans Azure AI Recherche utilisent l’intégralité de .NET Framework qui fournit un encodage intégré. Les options useHttpServerUtilityUrlTokenEncode et useHttpServerUtilityUrlTokenDecode appliquent cette fonctionnalité intégrée. Si vous utilisez .NET Core ou une autre infrastructure, nous vous recommandons de définir ces options sur false et d’appeler directement les fonctions d’encodage et de décodage de votre infrastructure.

Le tableau suivant compare les différents encodages base64 de la chaîne 00>00?00. Pour déterminer quel traitement s’avère nécessaire (le cas échéant) pour vos fonctions base64, appliquez votre fonction d’encodage de bibliothèque à la chaîne 00>00?00 et comparez le résultat obtenu au résultat attendu MDA-MDA_MDA.

Encodage	Résultat d’encodage base64	Autre traitement après l’encodage de bibliothèque	Autre traitement avant l’encodage de bibliothèque
Base64 avec remplissage	`MDA+MDA/MDA=`	Utiliser des caractères sécurisés pour les URL et supprimer le remplissage	Utiliser des caractères base64 standard et ajouter le remplissage
Base64 sans remplissage	`MDA+MDA/MDA`	Utiliser des caractères sécurisés pour les URL	Utiliser des caractères base64 standard
Base64 sécurisé pour les URL avec remplissage	`MDA-MDA_MDA=`	Supprimer le remplissage	Ajouter le remplissage
Base64 sécurisé pour les URL sans remplissage	`MDA-MDA_MDA`	None	None

Fonction extractTokenAtPosition

Divise un champ de chaîne en utilisant le séparateur spécifié et récupère le jeton à la position spécifiée dans le fractionnement résultant.

Cette fonction utilise les paramètres suivants :

delimiter: une chaîne à utiliser comme séparateur lors du fractionnement de la chaîne d'entrée.
position: une position entière à base zéro du jeton à choisir une fois la chaîne d'entrée fractionnée.

Par exemple, si l’entrée est Jane Doe, que le delimiter est " " (espace) et que la position est 0, le résultat est Jane ; si la position est 1, le résultat est Doe. Si la position fait référence à un jeton qui n’existe pas, une erreur est retournée.

Exemple : extraction d’un nom

Votre source de données contient un champ PersonName et vous souhaitez l’indexer en tant que deux champs FirstName et LastName distincts. Vous pouvez utiliser cette fonction pour fractionner l'entrée en utilisant l'espace comme séparateur.

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

Fonction jsonArrayToStringCollection

Transforme une chaîne formatée en tant que tableau de chaînes JSON en un tableau de chaînes utilisable pour remplir un champ Collection(Edm.String) dans l'index.

Par exemple, si la chaîne d’entrée est ["red", "white", "blue"], le champ cible de type Collection(Edm.String) est rempli avec les valeurs red, white et blue. Pour les valeurs d’entrée qui ne peuvent pas être analysées en tant que tableaux de chaînes JSON, une erreur est retournée.

Exemple : remplissage d’une collection avec des données relationnelles

Azure SQL Database n’inclut aucun type de données intégré qui mappe naturellement aux champs Collection(Edm.String) dans Azure AI Recherche. Pour remplir les champs de la collection de chaînes, vous pouvez prétraiter votre source de données en tant que tableau de chaînes JSON, puis utiliser la fonction de mappage jsonArrayToStringCollection.

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

fonction urlEncode

Cette fonction peut être utilisée pour encoder une chaîne de sorte qu’elle soit « URL safe ». Lorsqu’elle est utilisée avec une chaîne qui contient des caractères qui ne sont pas autorisés dans une URL, cette fonction convertit ces caractères « non sécurisés » en équivalents d’entité de caractère. Cette fonction utilise le format d’encodage UTF-8.

Exemple de recherche d’une clé de document

La fonction urlEncode peut être utilisée comme alternative à la fonction base64Encode, si seuls les caractères non sécurisés d’URL doivent être convertis, tout en conservant les autres caractères tels quels.

Par exemple, si la chaîne d’entrée est <hello>, le champ cible de type(Edm.String) est rempli avec la valeur %3chello%3e

Une fois que vous avez récupéré la clé encodée au moment de la recherche, vous pouvez utiliser la fonction urlDecode pour obtenir la valeur de clé d’origine, et l’utiliser pour récupérer le document source.

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

fonction urlDecode

Cette fonction convertit une chaîne encodée en URL en chaîne décodée à l’aide du format d’encodage UTF-8.

Exemple : décodage de métadonnées de blob

Certains clients de stockage Azure codent automatiquement les métadonnées de blob au format URL si elles contiennent des caractères non-ASCII. Toutefois, si vous souhaitez effectuer des recherches dans ces métadonnées (en texte brut), vous pouvez utiliser la fonction urlDecode pour réactiver les données encodées dans des chaînes normales lors du remplissage de votre index de recherche.

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

Fonction fixedLengthEncode

Cette fonction convertit une chaîne de n’importe quelle longueur en chaîne de longueur fixe.

Exemple - mapper des clés de document trop longues

Lorsque des erreurs liées à la longueur de clé de document supérieure à 1 024 caractères se produisent, cette fonction peut être appliquée pour réduire la longueur de la clé de document.


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

Fonction toJson

Cette fonction convertit une chaîne en un objet JSON mis en forme. Ceci peut être utilisé pour les scénarios où la source de données, comme Azure SQL, ne prend pas en charge nativement les types de données composés ou hiérarchiques, puis les mappe à des champs complexes.

Exemple – Mapper du contenu de texte à un champ complexe

Supposons qu’il existe une ligne SQL avec une chaîne JSON qui doit être mappée à un champ complexe (défini en conséquence) dans l’index : la fonction toJson peut être utilisée pour cela. Par exemple, si un champ complexe dans l’index doit être rempli avec les données suivantes :

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

Il est possible d’y parvenir en utilisant la fonction de mappage toJson sur une colonne de chaîne JSON dans une ligne SQL qui ressemble à ceci : {"id": 5, "info": {"name": "Jane", "surname": "Smith", "skills": ["SQL", "C#", "Azure"]}, "dob": "2005-11-04T12:00:00"}.

Le mappage de champ doit être spécifié comme indiqué ci-dessous.


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