Automatikus kiegészítés (Azure AI Search REST API)
Az Automatikus kiegészítés API befejez egy részlegesen beírt lekérdezési bemenetet a keresési index meglévő kifejezéseinek használatával, hogy egy másodlagos lekérdezésben használhassa. Ha például a lekérdezés bemenete "medic", az Automatikus kiegészítés API a , értéket "medicaid""medicine" adja vissza"medicare", ha ezek a kifejezések szerepelnek az indexben. A keresőmotor belsőleg keres egyező kifejezéseket azokban a mezőkben, amelyekben konfigurált egy javaslattevő .
A szolgáltatáskérésekhez HTTPS szükséges. Az automatikus kiegészítési kérés a GET vagy a POST metódussal hozható létre.
GET https://[service name].search.windows.net/indexes/[index name]/docs/autocomplete?[query parameters]
Content-Type: application/json
api-key: [admin or query key]
POST https://[service name].search.windows.net/indexes/[index name]/docs/autocomplete?api-version=[api-version]
Content-Type: application/json
api-key: [admin or query key]
A GET használatával történő meghívás esetén a kérelem URL-címe nem haladhatja meg a 8 KB-ot. Ez a hossz általában elegendő a legtöbb alkalmazáshoz. Egyes alkalmazások azonban nagyon nagy lekérdezéseket hoznak létre, különösen OData-szűrőkifejezések használatakor. Ezekben az alkalmazásokban a HTTP POST jobb választás, mert nagyobb szűrőket tesz lehetővé, mint a GET.
A POST esetében a szűrő záradékainak száma a korlátozó tényező, nem pedig a nyers szűrősztring mérete, mivel a POST kérelemméretkorlátja körülbelül 16 MB. Bár a POST-kérelem méretkorlátja nagyon nagy, a szűrőkifejezések nem lehetnek tetszőlegesen összetettek. A szűrés összetettségére vonatkozó korlátozásokkal kapcsolatos további információkért lásd: OData Expression Szintaxis az Azure AI Search szolgáltatáshoz.
URI-paraméterek
| Paraméter | Leírás |
|---|---|
| [szolgáltatás neve] | Kötelező. Állítsa be ezt a keresési szolgáltatás egyedi, felhasználó által megadott nevére. |
| [index neve]/dokumentumok | Kötelező. Egy elnevezett index dokumentumgyűjteményét adja meg. |
| api-verzió | Kötelező. A támogatott verziók listáját lásd: API-verziók . Lekérdezések esetén az API-verzió mindig URI-paraméterként van megadva a GET és a POST esetében is. |
URL-kódolási javaslatok
Ne felejtse el URL-kódolással megadni a lekérdezési paramétereket a GET REST API közvetlen meghívásakor. Az automatikus kiegészítés esetében az URL-kódolás szükséges lehet a következő lekérdezési paraméterekhez:
- keresés
- $filter
- highlightPreTag
- highlightPostTag
Az URL-kódolás csak az egyes paraméterekhez ajánlott. Ha véletlenül URL-kódolással kódolja a teljes lekérdezési sztringet (minden a után), a ?kérések megszakadnak.
Emellett az URL-kódolás csak akkor szükséges, ha a REST API-t közvetlenül a GET használatával hívja meg. A POST használatakor vagy az Azure AI Search .NET ügyfélkódtár használatakor nincs szükség URL-kódolásra, amely kezeli a kódolást.
Kérelemfejlécek
Az alábbi táblázat a szükséges és nem kötelező kérelemfejléceket ismerteti.
| Mezők | Description |
|---|---|
| Content-Type | Kötelező. Állítsa ezt a következőre: application/json |
| api-key | Nem kötelező , ha Azure-szerepköröket használ, és egy tulajdonosi jogkivonatot ad meg a kéréshez, ellenkező esetben kulcsra van szükség. A gyűjteményre docs irányuló lekérdezési kérelmek rendszergazdai kulcsot vagy lekérdezési kulcsot adhatnak meg.api-key A lekérdezéskulcs az indexdokumentumok gyűjteményén végzett írásvédett műveletekhez használható. A részletekért lásd: Csatlakozás az Azure AI Searchhöz kulcshitelesítés használatával . |
Kérelem törzse
GET esetén: Nincs.
POST esetén:
{
"autocompleteMode": "oneTerm" (default) | "twoTerms" | "oneTermWithContext",
"filter": "odata_filter_expression",
"fuzzy": true | false (default),
"highlightPreTag": "pre_tag",
"highlightPostTag": "post_tag",
"minimumCoverage": # (% of index that must be covered to declare query successful; default 80),
"search": "partial_search_input",
"searchFields": "field_name_1, field_name_2, ...",
"suggesterName": "suggester_name",
"top": # (default 5)
}
Lekérdezési paraméterek
A lekérdezések több paramétert is elfogadnak az URL-címben, ha a GET-et meghívják, és JSON-tulajdonságokként a kérelem törzsében, amikor POST használatával hívják meg őket. Egyes paraméterek szintaxisa kissé eltér a GET és a POST függvény között. Ezeket a különbségeket alább találja.
| Név | Típus | Description |
|---|---|---|
| api-verzió | sztring | Kötelező. A kéréshez használt REST API verziója. A támogatott verziók listáját lásd: API-verziószámozás. Ehhez a művelethez az API-verzió URI-paraméterként van megadva, függetlenül attól, hogy a GET vagy POST használatával hívja-e meg az Automatikus kiegészítést . |
| autocompleteMode | sztring | Választható. Az alapértelmezett érték a oneTerm. Az érvényes értékek a következők: oneTerm, twoTerms, oneTermWithContext. A oneTerm egyetlen kifejezést ad vissza. Ha a lekérdezésnek két kifejezése van, csak az utolsó kifejezés fejeződik be. A válasz "washington medic"lehet például a következő egyetlen kifejezés bármelyike: "medicaid", "medicare", "medicine". A twoTerms egyezik az indexben lévő kétkifejezéses kifejezésekkel. Például a megadott "medic"válasz lehet "medicare coverage", vagy "medical assistant". Sok esetben az egyetlen kifejezés "medicare" , vagy "medical" nem ad vissza, mert előnyben részesítik a két kifejezés, hogy egyezik.A oneTermWithContext egy lekérdezés utolsó kifejezését tölti ki két vagy több kifejezéssel, ahol az utolsó két kifejezés az indexben található kifejezés. A megadott "washington medic"válasz "washington medicaid"lehet például , "washington medical". |
| $filter | sztring | Választható. Strukturált keresési kifejezés a standard OData szintaxisban, amely szűri a befejezett kifejezésjavaslatok létrehozásához figyelembe vett dokumentumokat. Az Automatikus kiegészítés API nem támogatja a "search.ismatch" és a "search.ismatchscoring*" szűrőkifejezéseket. Szűrőben csak szűrhető mezők használhatók. Ha POST használatával hívja meg, ezt a paramétert a rendszer szűrőnek nevezi el a $filter helyett. Az Azure AI Search által támogatott OData-kifejezéshelyességi szintaxissal kapcsolatos részletekért tekintse meg az Azure AI Search OData-kifejezésszintaxisát ismertető cikket. |
| Fuzzy | boolean | Választható. Az alapértelmezett érték a hamis. Ha igaz értékre van állítva, ez az API akkor is talál javaslatokat, ha egy helyettesítő vagy hiányzó karakter szerepel a keresési szövegben (1). Ez bizonyos forgatókönyvekben jobb élményt nyújt, de teljesítményköltséggel jár, mivel a homályos javaslatok keresései lassabbak és több erőforrást használnak fel. |
| highlightPostTag | sztring | Választható. Alapértelmezés szerint egy üres sztring. A kiemelt kifejezéshez hozzáfűző sztringcímke. A highlightPreTag paraméterrel kell beállítani. Az URL-címben lévő fenntartott karaktereknek százalékban kódoltnak kell lenniük (például a #helyett %23). Get használatával történő meghívás esetén az URL-címben lévő fenntartott karaktereknek százalékban kódoltnak kell lenniük (például a #helyett %23). |
| highlightPreTag | sztring | Választható. Alapértelmezés szerint egy üres sztring. Egy sztringcímke, amely a kiemelt kifejezésre van előzve. A highlightPostTag értéket kell megadni. Get használatával történő meghívás esetén az URL-címben lévő fenntartott karaktereknek százalékban kódoltnak kell lenniük (például a #helyett %23). |
| minimumCoverage | egész szám | Választható. Alapértelmezés szerint 80. Egy 0 és 100 közötti szám, amely azt jelzi, hogy az index hány százaléka legyen elérhető a lekérdezés kiszolgálásához ahhoz, hogy sikeresként lehessen jelenteni. Az alapértelmezett érték a teljes lefedettséghez képest a sebesség és a hatékonyság torzítása. A lefedettség csökkentése korlátozza a lekérdezések bővítését, így az eredmények gyorsabban térnek vissza. Azt is lehetővé teszi, hogy a lekérdezés részleges index-rendelkezésre állás esetén is sikeres legyen, még akkor is, ha egy szegmens lassan válaszol vagy nem érhető el szolgáltatásállapot-problémák vagy indexkarbantartás miatt. A minimumátvétel értékétől függetlenül az index százalékos arányának elérhetőnek kell lennie, vagy az automatikus kiegészítés az 503-at tartalmazó HTTP-állapotkódot adja vissza. Ha az automatikus kiegészítés sikeres a minimálisCoverage szinten, akkor HTTP 200 értéket ad vissza, és a válaszban szerepel egy @search.coverage érték, amely a lekérdezés karbantartásakor rendelkezésre álló index százalékos arányát jelzi. Az érték csökkentése 503 hiba esetén hasznos lehet. Ellenkező esetben érdemes lehet növelni az értéket, ha a válasz nem ad megfelelő egyezést. |
| keresés | sztring | Kötelező. A keresett szöveg. A befejezendő keresési szöveg. Legalább 1 karakternek és legfeljebb 100 karakternek kell lennie. Nem tartalmazhat operátorokat, lekérdezési szintaxist vagy idézett kifejezéseket. |
| searchFields | sztring | Választható. A vesszővel elválasztott mezőnevek listája a megadott keresési szöveg kereséséhez. A célmezőknek szerepelnie kell az index Javaslattevők definíciójában. |
| suggesterName | sztring | Kötelező. A javaslattevő neve az indexdefiníció részét képező Javaslattevők gyűjteményben megadottak szerint. A javaslattevő meghatározza, hogy mely mezőket vizsgálja a rendszer a javasolt lekérdezési kifejezésekhez. |
| $top | egész szám | Választható. Alapértelmezés szerint 5. A lekérendő automatikus kiegészítési javaslatok száma. Az értéknek 1 és 100 közötti számnak kell lennie. A POST használatával történő hívás esetén ez a paraméter a $top helyett felső névvel lesz elnevezve. |
(1) A fuzzy korlátozásai az automatikus kiegészítésben:
Először is, a szerkesztési távolság tokenenként csak egy karakterkülönbségre korlátozódik, ellentétben a keresésben lévő homályos paramétersel. Ha a szerkesztési távolságot egy karakterre korlátozza, az azt jelenti, hogy nem minden jelölt egyezés található, de a korlátra szükség van az elfogadható teljesítményszint biztosításához.
Másodszor, a fuzzy lépés a részleges tokenbővítés után történik, és csak az azonos index-szegmensből származó kifejezéseket veszi figyelembe a rendszer a homályos egyezésekhez. Ez a kényszer növeli az automatikus kiegészítési API teljesítményét azáltal, hogy megszünteti a homályos egyezések összesítését az összes szegmensben. Ez a kényszer kevésbé észrevehető, mivel több kifejezést adnak hozzá az indexhez, ami hasonló kifejezéseloszlást eredményez az egyes szegmensekhez. Mivel a kifejezések egyenletesen oszlanak el, a szegmensen belüli homályos egyezések jó közelítést jelentenek a teljes indexben lévő homályos egyezésekhez. Az eredmények azonban rosszabbak lehetnek, ha az index kevesebb kifejezéssel rendelkezik, például egy teszt- vagy prototípusindexben, ami egyenetlen reprezentációt eredményez a szegmensek között. Az indexek szegmensekre való felosztásáról további információt a partíció- és replikakombinációk című témakörben talál.
Reagálás
Állapotkód: A rendszer az "200 OK" értéket adja vissza a sikeres válaszhoz.
A válasz hasznos adatainak két tulajdonsága van.
| Tulajdonság | Leírás |
|---|---|
| "szöveg" | A befejezett kifejezés vagy kifejezés |
| "queryPlusText" | A kezdeti lekérdezés bemenete, valamint a befejezett kifejezés vagy kifejezés |
{
"@search.coverage": # (if minimumCoverage was provided in the query),
"value": [
{
"text": "...",
"queryPlusText": "..."
},
...
]
}
Példák
1. példa: Három automatikus kiegészítési javaslat lekérése, ahol a részleges keresési bemenet alapértelmezett módban van 'washington medic' (oneTerm):
GET /indexes/insurance/docs/autocomplete?search=washington%20medic&$top=3&suggesterName=sg&api-version=2020-06-30
POST /indexes/insurance/docs/autocomplete?api-version=2020-06-30
{
"search": "washington medic",
"filter": "search.in(roleId, 'admin,manager')",
"top": 3,
"suggesterName": "sg"
}
Válasz:
{
"value": [
{
"text": "medicaid",
"queryPlusText": "washington medicaid"
},
{
"text": "medicare",
"queryPlusText": "washington medicare"
},
{
"text": "medicine",
"queryPlusText": "washington medicine"
}
]
}
2. példa: Három automatikus kiegészítési javaslat lekérése, ahol a részleges keresési bemenet és autocompleteMode=twoTermsa 'washington medic' :
GET /indexes/insurance/docs/autocomplete?search=washington%20medic&$top=3&suggesterName=sg&autocompleteMode=twoTerms&api-version=2020-06-30
POST /indexes/insurance/docs/autocomplete?api-version=2020-06-30
{
"search": "washington medic",
"autocompleteMode": "twoTerms",
"filter": "planDuration ge 1",
"top": 3,
"suggesterName": "sg"
}
Válasz:
{
"value": [
{
"text": "medicaid insurance",
"queryPlusText": "washington medicaid insurance"
},
{
"text": "medicare plan",
"queryPlusText": "washington medicare plan"
},
{
"text": "medicine book",
"queryPlusText": "washington medicine book"
}
]
}
Figyelje meg, hogy a suggesterName megadása kötelező egy automatikus kiegészítési műveletben.