Fältmappningar och transformeringar med Azure Cognitive Search indexerare

Indexerarens faser

När en Azure Cognitive Search indexerare läser in ett sökindex avgör den datasökvägen via fältmappningar från källa till mål. Implicita fältmappningar är interna och inträffar när fältnamn och datatyper är kompatibla mellan källan och målet.

Om indata och utdata inte matchar kan du definiera explicita fältmappningar för att konfigurera datasökvägen enligt beskrivningen i den här artikeln. Fältmappningar kan också användas för att introducera datakonvertering med låg vikt, till exempel kodning eller avkodning, via mappningsfunktioner. Om mer bearbetning krävs bör du överväga Azure Data Factory för att överbrygga klyftan.

Fältmappningar gäller för:

  • Fysiska datastrukturer på båda sidor av dataströmmen (mellan en datakälla som stöds och ett sökindex). Om du importerar kunskapsberikat innehåll som finns i minnet använder du outputFieldMappings i stället.

  • Sök endast index. Om du fyller i ett kunskapslager använder du projektioner för konfiguration av datasökväg.

  • Endast sökfält på den översta nivån, där "targetFieldName" antingen är ett enkelt fält eller en samling. Ett målfält kan inte vara en komplex typ.

Anteckning

Om du arbetar med komplexa data (kapslade eller hierarkiska strukturer) och du vill spegla datastrukturen i sökindexet måste ditt sökindex matcha källstrukturen exakt (samma fältnamn, nivåer och typer) så att standardmappningarna fungerar. Du kanske vill ha några få noder i den komplexa strukturen. Om du vill hämta enskilda noder kan du platta ut inkommande data till en strängsamling (se outputFieldMappings för den här lösningen).

Scenarier som stöds

Användningsfall Beskrivning
Namnavvikelse Anta att datakällan har ett fält med namnet _city. Med tanke på att Azure Cognitive Search inte tillåter fältnamn som börjar med ett understreck kan du med en fältmappning effektivt mappa "_city" till "stad".

Om indexeringskraven omfattar att hämta innehåll från flera datakällor, där fältnamnen varierar mellan källorna, kan du använda en fältmappning för att klargöra sökvägen.
Typavvikelse Anta att du vill att ett käll heltalsfält ska vara av typen Edm.String så att det kan sökas i sökindexet. Eftersom typerna är olika måste du definiera en fältmappning för att datasökvägen ska lyckas. Observera att Cognitive Search har en mindre uppsättning datatyper som stöds än många datakällor. Om du importerar SQL-data kan du med en fältmappning mappa den SQL-datatyp som du vill använda i ett sökindex.
En-till-många-datasökvägar Du kan fylla i flera fält i indexet med innehåll från samma källfält. Du kanske till exempel vill använda olika analysverktyg för varje fält för att stödja olika användningsfall i klientappen.
Kodning och avkodning Du kan använda mappningsfunktioner för att stödja Base64-kodning eller avkodning av data under indexering.
Dela upp strängar eller omarbeta matriser i samlingar Du kan använda mappningsfunktioner för att dela upp en sträng som innehåller en avgränsare eller för att skicka en JSON-matris till ett sökfält av typen Collection(Edm.String).

Definiera en fältmappning

Fältmappningar läggs till i matrisen "fieldMappings" för en indexeraredefinition. En fältmappning består av tre delar.

"fieldMappings": [
  {
    "sourceFieldName": "_city",
    "targetFieldName": "city",
    "mappingFunction": null
  }
],
Egenskap Beskrivning
sourceFieldName Krävs. Representerar ett fält i datakällan.
targetFieldName Valfritt. Representerar ett fält i sökindexet. Om det utelämnas antas värdet för "sourceFieldName" för målet. Målfält måste vara enkla fält eller samlingar på den översta nivån. Det kan inte vara en komplex typ eller samling. Om du hanterar ett problem med datatypen anges ett fälts datatyp i indexdefinitionen. Fältmappningen behöver bara ha fältets namn.
mappingFunction Valfritt. Består av fördefinierade funktioner som transformerar data.

Azure Cognitive Search använder skiftlägesokänslig jämförelse för att lösa fält- och funktionsnamnen i fältmappningar. Det här är praktiskt (du behöver inte få allt hölje rätt), men det innebär att datakällan eller indexet inte kan ha fält som bara skiljer sig åt från fall till fall.

Anteckning

Om det inte finns några fältmappningar antar indexerarna att datakällfält ska mappas till indexfält med samma namn. Om du lägger till en fältmappning åsidosätts standardfältmappningar för käll- och målfältet. Vissa indexerare, till exempel bloblagringsindexeraren, lägger till standardfältmappningar för indexnyckelfältet.

Du kan använda REST API eller en Azure SDK för att definiera fältmappningar.

Använd Create Indexer (REST) eller Update Indexer (REST), vilken API-version som helst.

Det här exemplet hanterar en fältnamnsavvikelse.

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

Det här exemplet mappar ett enda källfält till flera målfält ("en-till-många"-mappningar). Du kan "förgrena" ett fält genom att kopiera samma källfältinnehåll till två olika indexfält som ska analyseras eller hänföras på olika sätt i indexet.


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

Mappningsfunktioner och exempel

En fältmappningsfunktion transformerar innehållet i ett fält innan det lagras i indexet. Följande mappningsfunktioner stöds för närvarande:

base64Encode-funktion

Utför URL-säker Base64-kodning av indatasträngen. Förutsätter att indata är UTF-8-kodade.

Exempel: Grundläggande kodning av en dokumentnyckel

Endast URL-säkra tecken kan visas i en Azure Cognitive Search dokumentnyckel (så att du kan adressera dokumentet med hjälp av Uppslags-API:et). Om källfältet för nyckeln innehåller URL-osäkra tecken, till exempel - och \, använder du base64Encode funktionen för att konvertera den vid indexeringstiden.

I följande exempel anges funktionen base64Encode på "metadata_storage_name" för att hantera tecken som inte stöds.

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

En dokumentnyckel (både före och efter konverteringen) får inte vara längre än 1 024 tecken. När du hämtar den kodade nyckeln vid söktillfället använder du base64Decode funktionen för att hämta det ursprungliga nyckelvärdet och använder den för att hämta källdokumentet.

Exempel: Gör ett baskodat fält "sökbart"

Det finns tillfällen då du behöver använda en kodad version av ett fält som "metadata_storage_path" som nyckel, men du behöver också en okodad version för fulltextsökning. För att stödja båda scenarierna kan du mappa "metadata_storage_path" till två fält: ett för nyckeln (kodat) och ett andra för ett sökvägsfält som vi kan anta tillskrivs som "sökbart" i indexschemat.

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

Exempel – bevara ursprungliga värden

Blob Storage-indexeraren lägger automatiskt till en fältmappning från metadata_storage_path, blobens URI, till indexnyckelfältet om ingen fältmappning har angetts. Det här värdet är Base64-kodat så det är säkert att använda som en Azure Cognitive Search dokumentnyckel. I följande exempel visas hur du samtidigt mappar en URL-säker Base64-kodad version av metadata_storage_path till ett index_key fält och bevarar det ursprungliga värdet i ett metadata_storage_path fält:

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

Om du inte inkluderar en parameteregenskap för mappningsfunktionen {"useHttpServerUtilityUrlTokenEncode" : true}är värdet som standard .

Azure Cognitive Search stöder två olika Base64-kodningar. Du bör använda samma parametrar när du kodar och avkodar samma fält. Mer information finns i base64-kodningsalternativ för att bestämma vilka parametrar som ska användas.

base64Decode-funktion

Utför Base64-avkodning av indatasträngen. Indata antas vara en URL-säker Base64-kodad sträng.

Exempel – avkoda blobmetadata eller URL:er

Dina källdata kan innehålla Base64-kodade strängar, till exempel blobmetadatasträngar eller webb-URL:er, som du vill göra sökbara som oformaterad text. Du kan använda base64Decode funktionen för att återställa kodade data till vanliga strängar när du fyller i sökindexet.

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

Om du inte inkluderar en parameteregenskap är standardvärdet {"useHttpServerUtilityUrlTokenEncode" : true}.

Azure Cognitive Search stöder två olika Base64-kodningar. Du bör använda samma parametrar när du kodar och avkodar samma fält. Mer information finns i base64-kodningsalternativ för att bestämma vilka parametrar som ska användas.

base64-kodningsalternativ

Azure Cognitive Search stöder URL-säker base64-kodning och normal base64-kodning. En sträng som är base64-kodad under indexering bör avkodas senare med samma kodningsalternativ, annars matchar resultatet inte originalet.

Om parametrarna useHttpServerUtilityUrlTokenEncode eller för kodning respektive avkodning är inställda på truefungerar base64Encode det som HttpServerUtility.UrlTokenEncode och base64Decode fungerar som HttpServerUtility.UrlTokenDecodeuseHttpServerUtilityUrlTokenDecode.

Varning

Om base64Encode används för att generera nyckelvärden useHttpServerUtilityUrlTokenEncode måste anges till true. Endast URL-säker base64-kodning kan användas för nyckelvärden. Se Namngivningsregler för den fullständiga uppsättningen begränsningar för tecken i nyckelvärden.

.NET-biblioteken i Azure Cognitive Search förutsätter den fullständiga .NET Framework, som tillhandahåller inbyggd kodning. Alternativen useHttpServerUtilityUrlTokenEncode och useHttpServerUtilityUrlTokenDecode tillämpar den här inbyggda funktionen. Om du använder .NET Core eller något annat ramverk rekommenderar vi att du ställer in dessa alternativ på false och anropar ramverkets kodnings- och avkodningsfunktioner direkt.

I följande tabell jämförs olika base64-kodningar för strängen 00>00?00. Om du vill fastställa vilken bearbetning som krävs (om någon) för dina base64-funktioner använder du bibliotekskodfunktionen på strängen 00>00?00 och jämför utdata med förväntade utdata MDA-MDA_MDA.

Kodning Base64-kodningsutdata Extra bearbetning efter bibliotekskodning Extra bearbetning före avkodning av bibliotek
Base64 med utfyllnad MDA+MDA/MDA= Använd URL-säkra tecken och ta bort utfyllnad Använd standardbas64-tecken och lägg till utfyllnad
Base64 utan utfyllnad MDA+MDA/MDA Använda URL-säkra tecken Använd standardbas64-tecken
URL-säker base64 med utfyllnad MDA-MDA_MDA= Ta bort utfyllnad Lägg till utfyllnad
URL-säker base64 utan utfyllnad MDA-MDA_MDA Inga Inga

funktionen extractTokenAtPosition

Delar upp ett strängfält med den angivna avgränsaren och väljer token vid den angivna positionen i den resulterande delningen.

Den här funktionen använder följande parametrar:

  • delimiter: en sträng som ska användas som avgränsare när du delar indatasträngen.
  • position: en nollbaserad heltalsposition för token som ska väljas när indatasträngen har delats.

Om indata till exempel är , är (blanksteg) och position är 0 är Janeresultatet ; om position är 1 är Doeresultatet ." "delimiterJane Doe Om positionen refererar till en token som inte finns returneras ett fel.

Exempel – extrahera ett namn

Datakällan innehåller ett PersonName fält och du vill indexera det som två separata FirstName fält och LastName fält. Du kan använda den här funktionen för att dela indata med blankstegstecknet som avgränsare.

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

funktionen jsonArrayToStringCollection

Omvandlar en sträng formaterad som en JSON-matris med strängar till en strängmatris som kan användas för att fylla i ett Collection(Edm.String) fält i indexet.

Om indatasträngen till exempel är ["red", "white", "blue"]fylls målfältet av typen Collection(Edm.String) i med de tre värdena red, whiteoch blue. För indatavärden som inte kan parsas som JSON-strängmatriser returneras ett fel.

Exempel – fylla i samling från relationsdata

Azure SQL Database har ingen inbyggd datatyp som naturligt mappar till Collection(Edm.String) fält i Azure Cognitive Search. Om du vill fylla i strängsamlingsfält kan du förbearbeta dina källdata som en JSON-strängmatris och sedan använda mappningsfunktionen jsonArrayToStringCollection .

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

urlEncode-funktion

Den här funktionen kan användas för att koda en sträng så att den är "URL-säker". När den används med en sträng som innehåller tecken som inte tillåts i en URL konverterar den här funktionen dessa "osäkra" tecken till teckenentitetsmotsvarigheter. Den här funktionen använder UTF-8-kodningsformatet.

Exempel – uppslag av dokumentnyckel

urlEncode funktionen kan användas som ett alternativ till base64Encode funktionen, om endast OSÄKRA URL-tecken ska konverteras, samtidigt som andra tecken bevaras som de är.

Anta att indatasträngen är <hello> – då fylls målfältet av typen (Edm.String) i med värdet %3chello%3e

När du hämtar den kodade nyckeln vid söktillfället kan du använda urlDecode funktionen för att hämta det ursprungliga nyckelvärdet och använda det för att hämta källdokumentet.

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

urlDecode-funktion

Den här funktionen konverterar en URL-kodad sträng till en avkodad sträng med UTF-8-kodningsformat.

Exempel – avkoda blobmetadata

Vissa Azure Storage-klienter URL-kodar automatiskt blobmetadata om de innehåller icke-ASCII-tecken. Men om du vill göra sådana metadata sökbara (som oformaterad text) kan du använda urlDecode funktionen för att återställa kodade data till vanliga strängar när du fyller i sökindexet.

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

funktionen fixedLengthEncode

Den här funktionen konverterar en sträng med valfri längd till en sträng med fast längd.

Exempel – mappa dokumentnycklar som är för långa

Om det uppstår fel som är relaterade till dokumentnyckelns längd som överstiger 1 024 tecken kan den här funktionen användas för att minska dokumentnyckelns längd.


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

Se även