Mezőleképezések és átalakítások az Azure AI Search indexelőivel
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 adatfolyam mindkét oldalán (a támogatott adatforrás mezői és a keresési index mezői között). Ha olyan képességekkel bővített tartalmat importál, amely a memóriában található, az outputFieldMappings használatával leképezheti a memóriában lévő csomópontokat a keresési index mezőinek kimenetére.
Csak keresési indexek. Ha egy tudástárat hoz létre, használjon előrejelzéseket az adatútvonal konfigurálására.
Csak legfelső szintű keresési mezők, ahol az
targetFieldName
egyszerű mező vagy gyűjtemény. A célmező nem lehet összetett típus.
Feljegyzés
Ha összetett adatokkal (beágyazott vagy hierarchikus struktúrákkal) dolgozik, és tükrözni szeretné ezt az adatstruktúrát a keresési indexben, a keresési indexnek pontosan meg kell egyeznie a forrásstruktúrával (ugyanazokkal a mezőnevekkel, szintekkel és típusokkal), hogy az alapértelmezett leképezések működjenek. 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 ).
Támogatott esetek
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. |
Mezőleképezés definiálása
A mezőleképezések hozzáadódnak egy fieldMappings
indexelődefiníció tömbjére. 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. |
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. A megkerülő megoldás egy olyan indexséma létrehozása, amely megegyezik a mezőnevek és adattípusok nyers tartalmával. Lásd az oktatóanyagot: Beágyazott JSON-blobok indexelése egy példához.
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.
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, alapértelmezett mezőleképezéseket adnak hozzá az indexkulcs mezőhöz.
A REST API-val vagy egy Azure SDK-val mezőleképezéseket határozhat meg.
Használja az Indexelő létrehozása (REST) vagy az Indexelő frissítése (REST) bármely API-verziót.
Ez a példa egy mezőnév eltérését kezeli.
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" } ]
}
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" }
]
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 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=2020-06-30
{
"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=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" }
]
}
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_path
az 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.
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.
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 true
httpServerUtility.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?00
kü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 red
lesz 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-sztringtömbként előre 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"
}
}
]