Partager via

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

  • Article

Étapes de l'indexeur

Cet article explique comment définir des mappages de champs explicites qui établissent le chemin d’accès aux données entre les champs sources d’une source de données prise en charge et des champs cibles dans un index de recherche.

Quand définir un mappage de champs

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 :

  • Structures de données physiques des deux côtés du chemin d’accès aux données. Les structures de données logiques créées par des compétences se trouvent seulement en mémoire. Utilisez outputFieldMappings pour mapper des nœuds en mémoire aux champs de sortie d’un index de recherche.

  • Index de recherche IA parents uniquement. Pour les index « secondaires » avec des documents « enfants » ou des « blocs », reportez-vous aux scénarios de mappage de champs avancés.

  • 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.

Scénarios pris en charge

Veillez à utiliser une source de données prise en charge pour l’indexation pilotée par l’indexeur.

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

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 automatiquement des mappages de champs par défaut pour le champ de clé d’index.

Les champs complexes ne sont pas pris en charge dans un mappage de champs. Votre structure source (des structures imbriquées ou hiérarchiques) doit correspondre exactement au type complexe dans l’index pour que les mappages par défaut fonctionnent. Pour plus d’informations et obtenir un exemple, consultez Tutoriel : Indexer des blobs JSON imbriqués. 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.

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

Définir un mappage de champs

Cette section explique les étapes de configuration des mappages de champs.

  1. Utilisez Créer un indexeur, Créer ou mettre à jour un indexeur ou une méthode équivalente dans un Kit de développement logiciel (SDK) Azure. Voici un exemple de définition d’un indexeur.

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

  2. Renseignez le tableau fieldMappings pour spécifier les mappages. 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.

Exemple : différence de nom ou de type

Un mappage de champ explicite établit un chemin d’accès aux données pour les cas où le nom et le type ne sont pas identiques.

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.

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

Exemple : chemins d’accès aux données un-à-plusieurs ou dupliqués (fork)

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

Vous pouvez utiliser une approche similaire pour le contenu généré par des compétences.

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 :

Notez que ces fonctions sont exclusivement prises en charge pour les index parents pour l’instant. Elles ne sont pas compatibles avec le mappage d’index segmenté : ces fonctions ne peuvent donc pas être utilisées pour des projections d’index.

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 traiter les caractères non pris en charge.

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

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

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

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.

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

Scénarios de mappage de champs avancés

Dans les scénarios où vous avez des relations de document « un-à-plusieurs », telles que la segmentation ou la division de données, suivez ces instructions pour mapper les champs des documents parents aux documents « enfants » (blocs) :

1. Ignorer l’indexation des documents parents

Si vous ignorez l’indexation des documents parents (en définissant projectionMode sur skipIndexingParentDocuments dans l’indexProjectionsde l’ensemble de compétences), utilisez les projections d’index pour mapper les champs des documents parents aux documents « enfants ».

2. Indexer les documents parents et « enfants »

Si vous indexez des documents parents et des documents « enfants » :

  • Utilisez les mappages de champs pour mapper les champs aux documents parents.
  • Utilisez les projections d’index pour mapper les champs aux documents « enfants ».

3. Mapper les valeurs transformées par une fonction aux documents parents et/ou « enfants »

Si un champ du document parent nécessite une transformation (à l’aide de fonctions de mappage telles que l’encodage) et doit être mappé aux documents parents et/ou « enfants » :

  • Appliquez la transformation à l’aide des fonctions des mappages de champs dans l’indexeur.
  • Utilisez les projections d’index dans l’ensemble de compétences pour mapper le champ transformé aux documents « enfants ».

Voir aussi