Veldtoewijzingen en transformaties met behulp van Azure AI Search-indexeerfuncties

  • Artikel

Indexer Stages

Wanneer een Azure AI Search-indexeerfunctie een zoekindex laadt, wordt het gegevenspad bepaald met behulp van bron-naar-doelveldtoewijzingen. Impliciete veldtoewijzingen zijn intern en vinden plaats wanneer veldnamen en gegevenstypen compatibel zijn tussen de bron en bestemming. Als invoer en uitvoer niet overeenkomen, kunt u expliciete veldtoewijzingen definiëren om het gegevenspad in te stellen, zoals beschreven in dit artikel.

Veldtoewijzingen kunnen ook worden gebruikt voor lichte gegevensconversies, zoals codering of decodering, via toewijzingsfuncties. Als er meer verwerking is vereist, kunt u Azure Data Factory overwegen om de kloof te overbruggen.

Veldtoewijzingen zijn van toepassing op:

  • Fysieke gegevensstructuren aan beide zijden van de gegevensstroom (tussen velden in een ondersteunde gegevensbron en velden in een zoekindex). Als u inhoud importeert die is verrijkt met vaardigheden die zich in het geheugen bevindt, gebruikt u outputFieldMappings om in-memory knooppunten toe te wijzen aan uitvoervelden in een zoekindex.

  • Alleen zoekindexen. Als u een kennisarchief invult, gebruikt u projecties voor de configuratie van het gegevenspad.

  • Alleen zoekvelden op het hoogste niveau, waarbij het targetFieldName een eenvoudig veld of een verzameling is. Een doelveld kan geen complex type zijn.

Notitie

Als u werkt met complexe gegevens (geneste of hiërarchische structuren) en u die gegevensstructuur in de zoekindex wilt spiegelen, moet uw zoekindex exact overeenkomen met de bronstructuur (dezelfde veldnamen, niveaus en typen), zodat de standaardtoewijzingen werken. Desgewenst wilt u slechts enkele knooppunten in de complexe structuur. Als u afzonderlijke knooppunten wilt ophalen, kunt u binnenkomende gegevens platzetten in een tekenreeksverzameling (zie outputFieldMappings voor deze tijdelijke oplossing).

Ondersteunde scenario's

Use-case Beschrijving
Naamverschillen Stel dat uw gegevensbron een veld heeft met de naam _city. Aangezien Azure AI Search geen veldnamen toestaat die beginnen met een onderstrepingsteken, kunt u met een veldtoewijzing '_city' effectief toewijzen aan 'plaats'.

Als uw indexeringsvereisten bestaan uit het ophalen van inhoud uit meerdere gegevensbronnen, waarbij veldnamen per bron verschillen, kunt u een veldtoewijzing gebruiken om het pad te verduidelijken.
Typeverschillen U moet een bron-geheel getalveld van het type Edm.String zijn, zodat het doorzoekbaar is in de zoekindex. Omdat de typen verschillen, moet u een veldtoewijzing definiëren om het gegevenspad te laten slagen. Houd er rekening mee dat Azure AI Search een kleinere set ondersteunde gegevenstypen heeft dan veel gegevensbronnen. Als u SQL-gegevens importeert, kunt u met een veldtoewijzing het gewenste SQL-gegevenstype toewijzen in een zoekindex.
Een-op-veel-gegevenspaden U kunt meerdere velden in de index vullen met inhoud uit hetzelfde bronveld. U kunt bijvoorbeeld verschillende analyses toepassen op elk veld om verschillende use cases in uw client-app te ondersteunen.
Codering en decodering U kunt toewijzingsfuncties toepassen ter ondersteuning van Base64-codering of -decodering van gegevens tijdens het indexeren.
Tekenreeksen splitsen of matrices herschikken in verzamelingen U kunt toewijzingsfuncties toepassen om een tekenreeks te splitsen die een scheidingsteken bevat of om een JSON-matrix te verzenden naar een zoekveld van het typeCollection(Edm.String).

Een veldtoewijzing definiëren

Veldtoewijzingen worden toegevoegd aan de fieldMappings matrix van een indexeerfunctiedefinitie. Een veldtoewijzing bestaat uit drie delen.

"fieldMappings": [
  {
    "sourceFieldName": "_city",
    "targetFieldName": "city",
    "mappingFunction": null
  }
]
Eigenschappen Beschrijving
sourceFieldName Vereist. Vertegenwoordigt een veld in uw gegevensbron.
targetFieldName Optioneel. Vertegenwoordigt een veld in uw zoekindex. Als u dit weglaat, wordt de waarde sourceFieldName ervan uitgegaan voor het doel. Doelvelden moeten eenvoudige velden of verzamelingen op het hoogste niveau zijn. Het kan geen complex type of verzameling zijn. Als u een probleem met een gegevenstype verwerkt, wordt het gegevenstype van een veld opgegeven in de indexdefinitie. De veldtoewijzing moet alleen de naam van het veld hebben.
mappingFunction Optioneel. Bestaat uit vooraf gedefinieerde functies waarmee gegevens worden getransformeerd.

Als u een fout krijgt die vergelijkbaar is met "Field mapping specifies target field 'Address/city' that doesn't exist in the index", komt dit doordat doelveldtoewijzingen geen complex type kunnen zijn. De tijdelijke oplossing is het maken van een indexschema dat identiek is aan de onbewerkte inhoud voor veldnamen en gegevenstypen. Zie Zelfstudie: Geneste JSON-blobs indexeren voor een voorbeeld.

Azure AI Search maakt gebruik van hoofdlettergevoelige vergelijkingen om de veld- en functienamen in veldtoewijzingen op te lossen. Dit is handig (u hoeft niet alle hoofdletters op te halen), maar dit betekent dat uw gegevensbron of index geen velden kan bevatten die alleen per geval verschillen.

Notitie

Als er geen veldtoewijzingen aanwezig zijn, gaan indexeerfuncties ervan uit dat gegevensbronvelden moeten worden toegewezen aan indexvelden met dezelfde naam. Als u een veldtoewijzing toevoegt, worden de standaardveldtoewijzingen voor het bron- en doelveld overschreven. Sommige indexeerfuncties, zoals de indexeerfunctie voor blobopslag, voegen standaardveldtoewijzingen toe voor het indexsleutelveld.

U kunt de REST API of een Azure SDK gebruiken om veldtoewijzingen te definiëren.

Gebruik Indexeerfunctie (REST) maken of Indexeerfunctie (REST) bijwerken, elke API-versie.

In dit voorbeeld wordt een discrepantie voor veldnamen verwerkt.

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

In dit voorbeeld wordt één bronveld toegewezen aan meerdere doelvelden ('een-op-veel'-toewijzingen). U kunt een veld 'splitsen' en dezelfde inhoud van het bronveld kopiëren naar twee verschillende indexvelden die anders in de index worden geanalyseerd of toegeschreven.


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

Toewijzingsfuncties en voorbeelden

Met een functie voor veldtoewijzing wordt de inhoud van een veld getransformeerd voordat deze in de index wordt opgeslagen. De volgende toewijzingsfuncties worden momenteel ondersteund:

base64Encode, functie

Voert URL-veilige Base64-codering van de invoertekenreeks uit. Wordt ervan uitgegaan dat de invoer UTF-8 is gecodeerd.

Voorbeeld: Een documentsleutel basiscodering

Alleen URL-veilige tekens kunnen worden weergegeven in een Azure AI Search-documentsleutel (zodat u het document kunt adresseren met behulp van de Zoek-API). Als het bronveld voor uw sleutel URL-onveilige tekens bevat, zoals - en \, gebruikt u de base64Encode functie om het te converteren tijdens het indexeren.

In het volgende voorbeeld wordt de base64Encode-functie metadata_storage_name opgegeven voor het verwerken van niet-ondersteunde tekens.

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

Een documentsleutel (zowel vóór als na conversie) mag niet langer zijn dan 1024 tekens. Wanneer u de gecodeerde sleutel tijdens het zoeken ophaalt, gebruikt u de base64Decode functie om de oorspronkelijke sleutelwaarde op te halen en gebruikt u deze om het brondocument op te halen.

Voorbeeld: Een met base gecodeerd veld 'doorzoekbaar' maken

Er zijn momenten waarop u een gecodeerde versie van een veld zoals metadata_storage_path de sleutel moet gebruiken, maar ook een niet-gecodeerde versie nodig hebt voor zoeken in volledige tekst. Ter ondersteuning van beide scenario's kunt metadata_storage_path u toewijzen aan twee velden: één voor de sleutel (gecodeerd) en een seconde voor een padveld dat we kunnen aannemen, wordt toegeschreven als searchable in het indexschema.

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

Voorbeeld: oorspronkelijke waarden behouden

De indexeerfunctie voor blobopslag voegt automatisch een veldtoewijzing toe van metadata_storage_path, de URI van de blob, aan het indexsleutelveld als er geen veldtoewijzing is opgegeven. Deze waarde is Base64 gecodeerd, zodat deze veilig kan worden gebruikt als een Azure AI Search-documentsleutel. In het volgende voorbeeld ziet u hoe u tegelijkertijd een met URL veilige Base64 gecodeerde versie van metadata_storage_path een index_key veld kunt toewijzen en de oorspronkelijke waarde in een metadata_storage_path veld kunt behouden:

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

Als u geen parametereigenschap voor uw toewijzingsfunctie opneemt, wordt deze standaard ingesteld op de waarde {"useHttpServerUtilityUrlTokenEncode" : true}.

Azure AI Search ondersteunt twee verschillende Base64-coderingen. U moet dezelfde parameters gebruiken bij het coderen en decoderen van hetzelfde veld. Zie base64-coderingsopties om te bepalen welke parameters moeten worden gebruikt voor meer informatie.

base64Decode, functie

Hiermee wordt Base64-decodering van de invoertekenreeks uitgevoerd. De invoer wordt ervan uitgegaan dat het een url-veilige Base64-gecodeerde tekenreeks is.

Voorbeeld: blobmetagegevens of -URL's decoderen

Uw brongegevens bevatten mogelijk met Base64 gecodeerde tekenreeksen, zoals tekenreeksen voor blobmetagegevens of web-URL's, die u doorzoekbaar wilt maken als tekst zonder opmaak. U kunt de base64Decode functie gebruiken om de gecodeerde gegevens terug te zetten in reguliere tekenreeksen bij het invullen van uw zoekindex.

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

Als u geen eigenschap parameters opneemt, wordt deze standaard ingesteld op de waarde {"useHttpServerUtilityUrlTokenEncode" : true}.

Azure AI Search ondersteunt twee verschillende Base64-coderingen. U moet dezelfde parameters gebruiken bij het coderen en decoderen van hetzelfde veld. Zie base64-coderingsopties om te bepalen welke parameters moeten worden gebruikt voor meer informatie.

Opties voor base64-codering

Azure AI Search biedt ondersteuning voor URL-veilige base64-codering en normale base64-codering. Een tekenreeks die base64 is gecodeerd tijdens het indexeren, moet later worden gedecodeerd met dezelfde coderingsopties, anders komt het resultaat niet overeen met het origineel.

Als de useHttpServerUtilityUrlTokenEncode of useHttpServerUtilityUrlTokenDecode parameters voor respectievelijk codering en decodering zijn ingesteld trueop , gedraagt base64Encode zich als HttpServerUtility.UrlTokenEncode en base64Decode gedraagt zich als HttpServerUtility.UrlTokenDecode.

Waarschuwing

Als base64Encode wordt gebruikt om sleutelwaarden te produceren, useHttpServerUtilityUrlTokenEncode moet deze worden ingesteld op waar. Alleen URL-veilige base64-codering kan worden gebruikt voor sleutelwaarden. Zie Naamgevingsregels voor de volledige set beperkingen voor tekens in sleutelwaarden.

Voor de .NET-bibliotheken in Azure AI Search wordt ervan uitgegaan dat het volledige .NET Framework, dat ingebouwde codering biedt. De useHttpServerUtilityUrlTokenEncode en useHttpServerUtilityUrlTokenDecode opties passen deze ingebouwde functionaliteit toe. Als u .NET Core of een ander framework gebruikt, raden we u aan deze opties rechtstreeks in te false stellen en de coderings- en decoderingsfuncties van uw framework aan te roepen.

In de volgende tabel worden verschillende base64-coderingen van de tekenreeks vergeleken 00>00?00. Als u de vereiste verwerking (indien aanwezig) voor uw base64-functies wilt bepalen, past u de codefunctie van de bibliotheek toe op de tekenreeks 00>00?00 en vergelijkt u de uitvoer met de verwachte uitvoer MDA-MDA_MDA.

Codering Uitvoer van Base64-codering Extra verwerking na bibliotheekcodering Extra verwerking vóór bibliotheekdecodering
Base64 met opvulling MDA+MDA/MDA= URL-veilige tekens gebruiken en opvulling verwijderen Standaard base64-tekens gebruiken en opvulling toevoegen
Base64 zonder opvulling MDA+MDA/MDA URL-veilige tekens gebruiken Standaard base64-tekens gebruiken
URL-veilig base64 met opvulling MDA-MDA_MDA= Opvulling verwijderen Opvulling toevoegen
URL-veilig base64 zonder opvulling MDA-MDA_MDA Geen Geen

extractTokenAtPosition, functie

Splitst een tekenreeksveld met behulp van het opgegeven scheidingsteken en kiest het token op de opgegeven positie in de resulterende splitsing.

Deze functie gebruikt de volgende parameters:

  • delimiter: een tekenreeks die moet worden gebruikt als scheidingsteken bij het splitsen van de invoertekenreeks.
  • position: een geheel getal op basis van nul van het token dat moet worden gekozen nadat de invoertekenreeks is gesplitst.

Als de invoer Jane Doebijvoorbeeld is, is de delimiter ( " "spatie) en de position 0, het resultaat is Jane; als het position 1 is, is Doehet resultaat . Als de positie verwijst naar een token dat niet bestaat, wordt er een fout geretourneerd.

Voorbeeld: een naam extraheren

Uw gegevensbron bevat een PersonName veld en u wilt deze indexeren als twee afzonderlijke FirstNameLastName velden. U kunt deze functie gebruiken om de invoer te splitsen met behulp van het spatieteken als scheidingsteken.

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

jsonArrayToStringCollection, functie

Transformeert een tekenreeks die is opgemaakt als een JSON-matrix met tekenreeksen in een tekenreeksmatrix die kan worden gebruikt om een Collection(Edm.String) veld in de index te vullen.

Als de invoertekenreeks bijvoorbeeld is ["red", "white", "blue"], wordt het doelveld van het type Collection(Edm.String) gevuld met de drie waarden red, whiteen blue. Voor invoerwaarden die niet kunnen worden geparseerd als JSON-tekenreeksmatrices, wordt een fout geretourneerd.

Voorbeeld: verzameling van relationele gegevens vullen

Azure SQL Database heeft geen ingebouwd gegevenstype dat op natuurlijke wijze wordt toegewezen aan Collection(Edm.String) velden in Azure AI Search. Als u tekenreeksverzamelingsvelden wilt vullen, kunt u de brongegevens vooraf verwerken als een JSON-tekenreeksmatrix en vervolgens de jsonArrayToStringCollection toewijzingsfunctie gebruiken.

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

urlEncode, functie

Deze functie kan worden gebruikt om een tekenreeks te coderen, zodat deze 'URL veilig' is. Wanneer deze functie wordt gebruikt met een tekenreeks die tekens bevat die niet zijn toegestaan in een URL, worden deze 'onveilige' tekens geconverteerd naar equivalenten van tekens. Deze functie maakt gebruik van de UTF-8-coderingsindeling.

Voorbeeld: opzoeken van documentsleutels

urlEncode de functie kan worden gebruikt als alternatief voor de base64Encode functie, als alleen onveilige URL-tekens moeten worden geconverteerd, terwijl andere tekens als zodanig worden behouden.

Stel dat de invoertekenreeks is <hello> : het doelveld van het type (Edm.String) wordt gevuld met de waarde %3chello%3e

Wanneer u de gecodeerde sleutel tijdens het zoeken ophaalt, kunt u vervolgens de urlDecode functie gebruiken om de oorspronkelijke sleutelwaarde op te halen en dat te gebruiken om het brondocument op te halen.

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

urlDecode, functie

Met deze functie wordt een tekenreeks met URL-codering geconverteerd naar een gedecodeerde tekenreeks met behulp van UTF-8-coderingsindeling.

Voorbeeld: blobmetagegevens decoderen

Sommige Azure Storage-clients coderen automatisch metagegevens van blob-URL's als deze niet-ASCII-tekens bevatten. Als u dergelijke metagegevens echter doorzoekbaar wilt maken (als tekst zonder opmaak), kunt u de urlDecode functie gebruiken om de gecodeerde gegevens terug te zetten in gewone tekenreeksen bij het invullen van uw zoekindex.

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

fixedLengthEncode, functie

Met deze functie wordt een tekenreeks van elke lengte geconverteerd naar een tekenreeks met een vaste lengte.

Voorbeeld: documentsleutels toewijzen die te lang zijn

Wanneer er fouten optreden die betrekking hebben op de lengte van de documentsleutel die langer is dan 1024 tekens, kan deze functie worden toegepast om de lengte van de documentsleutel te verminderen.


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

toJson, functie

Met deze functie wordt een tekenreeks geconverteerd naar een opgemaakt JSON-object. Dit kan worden gebruikt voor scenario's waarin de gegevensbron, zoals Azure SQL, geen systeemeigen ondersteuning biedt voor samengestelde of hiërarchische gegevenstypen en deze vervolgens toe te wijzen aan complexe velden.

Voorbeeld: tekstinhoud toewijzen aan een complex veld

Stel dat er een SQL-rij is met een JSON-tekenreeks die moet worden toegewezen aan een (bijbehorend gedefinieerd) complex veld in de index. De toJson functie kan hiervoor worden gebruikt. Als een complex veld in de index bijvoorbeeld moet worden gevuld met de volgende gegevens:

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

Dit kan worden bereikt met behulp van de toJson toewijzingsfunctie in een JSON-tekenreekskolom in een SQL-rij die er als volgt uitziet: {"id": 5, "info": {"name": "Jane", "surname": "Smith", "skills": ["SQL", "C#", "Azure"]}, "dob": "2005-11-04T12:00:00"}.

De veldtoewijzing moet worden opgegeven zoals hieronder wordt weergegeven.


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

Zie ook