Mezőleképezések és átalakítások az Azure AI Search indexelőivel

Cikk
09/01/2024

Ez a cikk bemutatja, hogyan állíthat be explicit mezőleképezéseket, amelyek létrehozzák a támogatott adatforrás forrásmezői és a keresési index célmezői közötti adatelérési utat.

Mikor kell mezőleképezést beállítani?

Amikor egy Azure AI Search-indexelő betölt egy keresési indexet, a forrás–cél mezőleképezések használatával határozza meg az elérési utat. Az implicit mezőleképezések belsőek, és akkor fordulnak elő, ha a mezőnevek és az adattípusok kompatibilisek a forrás és a cél között. Ha a bemenetek és kimenetek nem egyeznek, explicit mezőleképezéseket határozhat meg az adatútvonal beállításához a jelen cikkben leírtak szerint.

A mezőleképezések a leképezési függvényeken keresztül kis súlyú adatátalakításokhoz is használhatók, például kódoláshoz vagy dekódoláshoz. Ha további feldolgozásra van szükség, vegye figyelembe az Azure Data Factoryt a szakadék áthidalásához.

A mezőleképezések a következőre vonatkoznak:

Fizikai adatstruktúrák az adatútvonal mindkét oldalán. A készségek által létrehozott logikai adatstruktúrák csak a memóriában találhatók. Az outputFieldMappings használatával leképezheti a memóriában lévő csomópontokat a keresési indexben lévő mezőkre.
Csak szülő AI Search-indexek. A "gyermek" dokumentumokat vagy adattömböket tartalmazó "másodlagos" indexek esetében tekintse meg a speciális mezőleképezési forgatókönyveket.
Csak legfelső szintű keresési mezők, ahol az targetFieldName egyszerű mező vagy gyűjtemény. A célmező nem lehet összetett típus.

Támogatott esetek

Győződjön meg arról, hogy támogatott adatforrást használ az indexelők által vezetett indexeléshez.

Használati eset	Leírás
Néveltérés	Tegyük fel, hogy az adatforrásnak van egy nevű mezője `_city`. Mivel az Azure AI Search nem engedélyezi az aláhúzásjellel kezdődő mezőneveket, a mezőleképezés lehetővé teszi, hogy a "_city" hatékonyan "város" legyen. Ha az indexelési követelmények közé tartozik a tartalom lekérése több adatforrásból, ahol a mezőnevek eltérőek a források között, akkor egy mezőleképezéssel tisztázhatja az elérési utat.
Típuseltérés	Tegyük fel, hogy azt szeretné, hogy egy forrás egész mező típusa `Edm.String` legyen, hogy az kereshető legyen a keresési indexben. Mivel a típusok eltérőek, mezőleképezést kell definiálnia ahhoz, hogy az adatelérési út sikeres legyen. Vegye figyelembe, hogy az Azure AI Search kevesebb támogatott adattípussal rendelkezik, mint számos adatforrás. HA SQL-adatokat importál, a mezőleképezés lehetővé teszi a keresési indexben a kívánt SQL-adattípus leképezését.
Egy-a-többhöz adatelérési utak	Az indexben több mezőt is feltölthet ugyanabból a forrásmezőből származó tartalommal. Előfordulhat például, hogy különböző elemzőket szeretne alkalmazni az egyes mezőkre az ügyfélalkalmazás különböző használati eseteinek támogatásához.
Kódolás és dekódolás	Leképezési függvényeket alkalmazhat a Base64-adatok kódolásának vagy dekódolásának támogatására az indexelés során.
Sztringek felosztása vagy tömbök átdolgozása gyűjteményekbe	A leképezési függvényeket alkalmazhatja egy elválasztójelet tartalmazó sztring felosztására, vagy JSON-tömb küldésére egy típusú `Collection(Edm.String)`keresőmezőbe.

Feljegyzés

Ha nincsenek mezőleképezések, az indexelők feltételezik, hogy az adatforrásmezőket azonos nevű indexmezőkre kell leképezni. A mezőleképezés hozzáadása felülbírálja a forrás- és célmező alapértelmezett mezőleképezéseit. Egyes indexelők, például a blobtároló indexelője automatikusan hozzáadják az indexkulcs mező alapértelmezett mezőleképezéseit.

Az összetett mezők nem támogatottak a mezőleképezésben. A forrásstruktúrának (beágyazott vagy hierarchikus struktúráknak) pontosan meg kell egyeznie az index összetett típusával, hogy az alapértelmezett leképezések működhessenek. További információ : Oktatóanyag: Beágyazott JSON-blobok indexelése példaként. Ha hasonló hibaüzenetet kap, annak az az oka, hogy "Field mapping specifies target field 'Address/city' that doesn't exist in the index"a célmező-leképezések nem lehetnek összetettek.

Igény szerint csak néhány csomópontot szeretne az összetett struktúrában. Az egyes csomópontok lekéréséhez a bejövő adatokat sztringgyűjteménybe lehet egyesíteni (a kerülő megoldáshoz lásd az outputFieldMappings parancsot ).

Mezőleképezés definiálása

Ez a szakasz a mezőleképezések beállításának lépéseit ismerteti.

REST API-k
.NET SDK (C#)

Indexelő létrehozása, Indexelő létrehozása vagy frissítése vagy ezzel egyenértékű metódus használata egy Azure SDK-ban. Íme egy példa egy indexelő definíciójára.

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

Töltse ki a fieldMappings tömböt a leképezések megadásához. A mezőleképezés három részből áll.

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

Tulajdonság	Leírás
sourceFieldName	Szükséges. Az adatforrás egy mezőjét jelöli.
targetFieldName	Opcionális. A keresési index egy mezőjét jelöli. Ha nincs megadva, a cél értéke `sourceFieldName` lesz feltételezve. A célmezőknek felső szintű egyszerű mezőknek vagy gyűjteményeknek kell lenniük. Nem lehet összetett típus vagy gyűjtemény. Adattípus-probléma kezelése esetén a mező adattípusa az indexdefinícióban van megadva. A mezőleképezésnek csak a mező nevével kell rendelkeznie.
mappingFunction	Opcionális. Előre definiált függvényekből áll, amelyek átalakítják az adatokat.

Példa: Név- vagy típuseltérés

Az explicit mezőleképezés adatelérési utat hoz létre olyan esetekben, amikor a név és a típus nem azonos.

Az Azure AI Search a kis- és nagybetűk érzéketlen összehasonlításával oldja fel a mező- és függvényneveket a mezőleképezésekben. Ez kényelmes (nem kell minden burkolatot helyesen beszereznie), de ez azt jelenti, hogy az adatforrás vagy az index nem tartalmazhat olyan mezőket, amelyek csak esetenként különböznek.

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

Példa: Egy-a-többhöz vagy elágazott adatútvonalak

Ez a példa egy forrásmezőt több célmezőre (egy-a-többhöz) képez le. Elágaztathat egy mezőt, és ugyanazt a forrásmezőtartalmat két különböző indexmezőbe másolhatja, amelyeket az index másként elemez vagy attribútumol.


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

Hasonló megközelítést használhat a készségek által létrehozott tartalmakhoz.

A .NET-hez készült Azure SDK-ban használja a FieldMapping osztályt, amely tulajdonságokat és TargetFieldName opcionális MappingFunction hivatkozást biztosítSourceFieldName.

Mezőleképezéseket adhat meg az indexelő létrehozásakor vagy később a SearchIndexer.FieldMappings közvetlen beállításával. Az alábbi C# példa a mezőleképezéseket állítja be egy indexelő létrehozásakor.

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

Leképezési függvények és példák

A mezőleképezési függvény átalakítja egy mező tartalmát az indexben való tárolás előtt. Jelenleg a következő leképezési függvények támogatottak:

base64Encode
base64Decode
extractTokenAtPosition
jsonArrayToStringCollection
urlEncode
urlDecode

Vegye figyelembe, hogy ezek a függvények jelenleg kizárólag a szülőindexek esetében támogatottak. Nem kompatibilisek az adattömbök indexleképezésével, ezért ezek a függvények nem használhatók index-előrejelzésekhez.

base64Encode függvény

A bemeneti sztring URL-címbiztos Base64-kódolását hajtja végre. Feltételezi, hogy a bemenet UTF-8 kódolású.

Példa: Dokumentumkulcs alapkódolása

Az Azure AI Search dokumentumkulcsában csak URL-címmel rendelkező karakterek jelenhetnek meg (így a lookup API használatával megcímzheti a dokumentumot). Ha a kulcs forrásmezője URL-nem biztonságos karaktereket tartalmaz, például - és \, használja a függvényt az base64Encode indexelés idején való konvertáláshoz.

Az alábbi példa a base64Encode függvényt adja meg a metadata_storage_name nem támogatott karakterek kezeléséhez.

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

A dokumentumkulcsok (átalakítás előtt és után is) nem lehetnek hosszabbak 1024 karakternél. A kódolt kulcs keresési időpontban történő lekérésekor a base64Decode függvény használatával szerezze be az eredeti kulcs értékét, és ezzel kérje le a forrásdokumentumot.

Példa: Alapkódolt mező "kereshetővé tétele"

Vannak esetek, amikor egy mező kódolt verzióját kell használnia, például metadata_storage_path kulcsként, de a teljes szöveges kereséshez is kódolatlan verzióra van szüksége. Mindkét forgatókönyv támogatásához két mezőhöz rendelhet leképezést metadata_storage_path : az egyik a kulcshoz (kódolt), a másodikhoz pedig egy olyan elérésiút-mezőhöz, amelyet feltételezhetünk, az indexsémához hasonlóan searchable van hozzárendelve.

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

Példa – eredeti értékek megőrzése

A blobtároló indexelője automatikusan hozzáad egy mezőleképezést a blob URI-jából metadata_storage_pathaz indexkulcs mezőhöz, ha nincs megadva mezőleképezés. Ez az érték Base64 kódolású, így biztonságosan használható Azure AI Search-dokumentumkulcsként. Az alábbi példa bemutatja, hogyan képezheti le egyszerre az URL-címvédett Base64 kódolt verzióját metadata_storage_path egy index_key mezőre, és hogyan őrizheti meg az eredeti értéket egy metadata_storage_path mezőben:

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

Ha nem tartalmaz paramétertulajdonságot a leképezési függvényhez, az alapértelmezés szerint az érték {"useHttpServerUtilityUrlTokenEncode" : true}lesz.

Az Azure AI Search két különböző Base64-kódolást támogat. Ugyanazokat a paramétereket kell használnia ugyanazon mező kódolása és dekódolása során. További információ: base64 kódolási beállítások , amelyek eldöntik, hogy mely paramétereket érdemes használni.

base64Decode függvény

A bemeneti sztring Base64-dekódolását hajtja végre. A bemenet egy URL-címvédett Base64-kódolású sztringnek számít.

Példa – blob metaadatainak vagy URL-címeinek dekódolás

A forrásadatok tartalmazhatnak Base64-kódolt sztringeket, például blob metaadat-sztringeket vagy webes URL-címeket, amelyeket egyszerű szövegként szeretne kereshetővé tenni. A függvény használatával a base64Decode kódolt adatokat normál sztringekké alakíthatja a keresési index feltöltésekor.

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

Ha nem tartalmaz paramétertulajdonságot, az alapértelmezés szerint az érték {"useHttpServerUtilityUrlTokenEncode" : true}lesz.

Base64 kódolási lehetőségek

Az Azure AI Search támogatja az URL-biztonságos base64 kódolást és a normál base64-kódolást. Az indexelés során base64 kódolású sztringet később ugyanezekkel a kódolási beállításokkal kell dekódolni, különben az eredmény nem egyezik meg az eredetivel.

Ha a useHttpServerUtilityUrlTokenEncode kódoláshoz és useHttpServerUtilityUrlTokenDecode a dekódoláshoz használt paraméterek értéke a truehttpServerUtility.UrlTokenEncode, és base64Decode base64Encode úgy viselkedik, mint a HttpServerUtility.UrlTokenDecode.

Figyelmeztetés

Ha base64Encode kulcsértékek előállítására szolgál, useHttpServerUtilityUrlTokenEncode igaz értékre kell állítani. Kulcsértékekhez csak AZ URL-cím biztonságos base64 kódolása használható. A kulcsértékekben szereplő karakterekre vonatkozó korlátozások teljes készletének elnevezési szabályai .

Az Azure AI Search .NET-kódtárai a teljes .NET-keretrendszer feltételezik, amely beépített kódolást biztosít. A useHttpServerUtilityUrlTokenEncode beállítások ezt useHttpServerUtilityUrlTokenDecode a beépített funkciót alkalmazzák. Ha .NET Core-t vagy más keretrendszert használ, javasoljuk, hogy false közvetlenül adja meg és hívja meg a keretrendszer kódolási és dekódolási függvényeit.

Az alábbi táblázat a sztring 00>00?00különböző base64-kódolásait hasonlítja össze. A base64-függvényekhez szükséges feldolgozás (ha van ilyen) meghatározásához alkalmazza a kódtár kódoló függvényét a sztringre 00>00?00 , és hasonlítsa össze a kimenetet a várt kimenettel MDA-MDA_MDA.

Kódolás	Base64 kódolás kimenete	További feldolgozás a kódtár kódolása után	További feldolgozás a kódtár dekódolása előtt
Base64 párnázással	`MDA+MDA/MDA=`	Használjon URL-címbiztos karaktereket, és távolítsa el a kitöltést	Standard base64 karakter használata és kitöltés hozzáadása
Base64 kitöltés nélkül	`MDA+MDA/MDA`	URL-címben biztonságos karakterek használata	Standard alap64 karakter használata
URL-biztonságos base64 kitöltéssel	`MDA-MDA_MDA=`	Padding eltávolítása	Kitöltés hozzáadása
URL-biztonságos base64 kitöltés nélkül	`MDA-MDA_MDA`	Egyik sem	Egyik sem

extractTokenAtPosition függvény

Feloszt egy sztringmezőt a megadott elválasztójellel, és kiválasztja a jogkivonatot az eredményül kapott felosztás megadott helyén.

Ez a függvény a következő paramétereket használja:

delimiter: a bemeneti sztring felosztásakor elválasztóként használni kívánt sztring.
position: a bemeneti sztring felosztása után kiválasztandó jogkivonat nullaalapú egész pozíciója.

Ha például a bemenet Jane Doe, az delimiter is " "(szóköz) és a position 0, az eredmény Jane; ha az position 1, akkor az eredmény .Doe Ha a pozíció nem létező jogkivonatra hivatkozik, a függvény hibát ad vissza.

Példa – név kinyerés

Az adatforrás tartalmaz egy PersonName mezőt, és két külön FirstName mezőként LastName szeretné indexelni. Ezzel a függvénnyel feloszthatja a bemenetet a szóköz karakterrel elválasztóként.

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

jsonArrayToStringCollection függvény

Sztringek JSON-tömbjeként formázott sztringeket alakít át egy sztringtömbbe, amely az index egy Collection(Edm.String) mezőjének kitöltésére használható.

Ha például a bemeneti sztring az ["red", "white", "blue"], akkor a típus Collection(Edm.String) célmezője a három értékkel redlesz feltöltve, whiteés blue. JSON-sztringtömbként nem elemezhető bemeneti értékek esetén a rendszer hibát ad vissza.

Példa – gyűjtemény feltöltése relációs adatokból

Az Azure SQL Database nem rendelkezik beépített adattípussal, amely természetesen leképzi az Collection(Edm.String) Azure AI Search mezőit. A sztringgyűjtemény mezőinek feltöltéséhez a forrásadatokat JSON-karakterlánctömbként is feldolgozhatja, majd használhatja a leképezési jsonArrayToStringCollection függvényt.

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

urlEncode függvény

Ez a függvény sztringek kódolására használható úgy, hogy az "URL-cím biztonságos legyen". Ha olyan sztringet használ, amely url-címben nem engedélyezett karaktereket tartalmaz, ez a függvény ezeket a "nem biztonságos" karaktereket karakter-entitás megfelelőivé alakítja. Ez a függvény az UTF-8 kódolási formátumot használja.

Példa – dokumentumkulcs-keresés

urlEncode függvény a függvény alternatívaként is használható, ha csak az base64Encode URL-cím nem biztonságos karaktereket konvertálja, miközben a többi karakter is változatlan marad.

Tegyük fel, hogy a bemeneti sztring - <hello> akkor a típus (Edm.String) célmezője fel lesz töltve az értékkel %3chello%3e

A kódolt kulcs kereséskor történő lekérése után a urlDecode függvény segítségével lekérheti az eredeti kulcs értékét, és ezzel lekérheti a forrásdokumentumot.

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

urlDecode függvény

Ez a függvény egy URL-kódolású sztringet UTF-8 kódolási formátummal dekódolt sztringgé alakít át.

Példa – blob metaadatainak dekódolás

Egyes Azure Storage-ügyfelek automatikusan URL-kódolják a blob metaadatait, ha nem ASCII-karaktereket tartalmaznak. Ha azonban az ilyen metaadatokat kereshetővé szeretné tenni (egyszerű szövegként), a urlDecode függvény használatával a kódolt adatokat visszakapcsolhatja normál sztringekké a keresési index feltöltésekor.

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

fixedLengthEncode függvény

Ez a függvény bármilyen hosszúságú sztringet rögzített hosszúságú sztringgé alakít át.

Példa – túl hosszú dokumentumkulcsok leképezése

Ha a dokumentumkulcs 1024 karakternél hosszabb hosszával kapcsolatos hibák lépnek fel, ez a függvény a dokumentumkulcs hosszának csökkentésére alkalmazható.


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

toJson függvény

Ez a függvény formázott JSON-objektummá konvertál egy sztringet. Ez olyan helyzetekben használható, amikor az adatforrás( például az Azure SQL) natív módon nem támogatja az összetett vagy hierarchikus adattípusokat, majd összetett mezőkre képezheti le.

Példa – szövegtartalom leképezése összetett mezőre

Tegyük fel, hogy van egy JSON-sztringgel rendelkező SQL-sor, amelyet le kell képezni az index egy (megfelelően definiált) összetett mezőjére, a toJson függvény ennek eléréséhez használható. Ha például az index egy összetett mezőjét a következő adatokkal kell kitölteni:

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

Ez a következőhöz hasonló SQL-sor JSON-sztringoszlopának leképezési függvényével toJson érhető el: {"id": 5, "info": {"name": "Jane", "surname": "Smith", "skills": ["SQL", "C#", "Azure"]}, "dob": "2005-11-04T12:00:00"}.

A mezőleképezést az alább látható módon kell megadni.


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

Speciális mezőleképezési forgatókönyvek

Azokban az esetekben, amikor "egy-a-többhöz" dokumentumkapcsolatokkal rendelkezik, például adattömbök vagy felosztás, kövesse az alábbi irányelveket a mezők szülődokumentumokból "gyermek" dokumentumokba (adattömbökbe) való leképezéséhez:

1. A szülődokumentum indexelésének kihagyása

Ha kihagyja a szülődokumentumok indexelését (a képességkészletben indexProjectionsvaló beállítással skipIndexingParentDocuments projectionMode), az index-előrejelzések használatával a szülődokumentumok mezőit a "gyermek" dokumentumokra képezheti le.

2. Szülő- és gyermekdokumentumok indexelése

Ha a szülődokumentumokat és a "gyermek" dokumentumokat is indexeli:

Mezők leképezése a szülődokumentumokhoz mezőleképezések használatával.
Az index-előrejelzések használatával mezőket képezhet le a "gyermek" dokumentumokhoz.

3. Függvényátalakítású értékek leképezése szülő- és/vagy "gyermek" dokumentumokba

Ha a szülődokumentum egy mezője átalakítást igényel (a leképezési függvények, például a kódolás használatával), és le kell képezni a szülő- és/vagy "gyermek" dokumentumokra:

Alkalmazza az átalakítást mezőleképezések függvényeivel az indexelőben.
A képességkészletben index-előrejelzések használatával képezze le az átalakított mezőt a "gyermek" dokumentumokra.

Megosztás a következőn keresztül: