Javaslatok (Azure AI Search REST API)

  • Cikk

A Javaslatkérések olyan keresés mint ön típusú lekérdezések, amelyek egyező értékeket keresnek a javaslattevő által felismert mezőkben, és egyezést tartalmazó dokumentumokat ad vissza. Ha például engedélyezi a javaslatokat egy városmezőn , a "tenger" szöveg beírásával a "Seattle", a "Sea Tac" és a "Seaside" (az összes tényleges városnév) dokumentumot hoz létre az adott mezőhöz.

A válasz egy egyező dokumentum tartalma, valamint a dokumentumkulcs. Az automatikus kiegészítéssel ellentétben, amely egy másodlagos lekérdezésben használt befejezett kifejezést vagy kifejezést ad vissza, ez a kérés olyan információkat ad vissza, amelyek a tényleges dokumentumokra lesznek feloldva. Ha az egyező kifejezések vagy kifejezések azonosak a dokumentumokban, a rendszer megismétli az egyező tartalmat. Az eredmények szerkezetének javítása érdekében fontolja meg a $select szűrő használatát további mezők visszaadására, amelyek nagyobb különbséget és környezetet biztosítanak.

A szolgáltatáskérésekhez HTTPS szükséges. A Javaslat kérés a GET vagy POST metódussal hozható létre.

GET https://[service name].search.windows.net/indexes/[index name]/docs/suggest?[query parameters]  
  Content-Type: application/json  
  api-key: [admin or query key]   

POST https://[service name].search.windows.net/indexes/[index name]/docs/suggest?api-version=[api-version]  
  Content-Type: application/json  
  api-key: [admin or query key]

A Keresési dokumentumok kéréssel ellentétben előfordulhat, hogy a Javaslatok hívást a billentyűzet bemenetéhez köti, míg a Keresési hívás egy kattintáseseményhez van kötve.

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 jelenlegi stabil verzió a következő api-version=2020-06-30: . További verziókért 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. A Javaslatok műveletekhez a következők tartoznak:

  • 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. Nem szükséges URL-kódolás a Javaslatok POST használatával történő meghívásakor, vagy ha az Azure AI Search .NET ügyfélkódtára kezeli az URL-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. Az API-kulcs egy egyedi, rendszer által létrehozott sztring, amely hitelesíti a keresési szolgáltatásnak küldött kérést. A dokumentumgyűjtemény lekérdezési kérelmei megadhatnak egy rendszergazdai kulcsot vagy egy lekérdezéskulcsot API-kulcsként. A lekérdezéskulcs a dokumentumgyűjteményen végzett írásvédett műveletekhez használatos. 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:

{  
      "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),  
      "orderby": "orderby_expression",  
      "search": "partial_search_input",  
      "searchFields": "field_name_1, field_name_2, ...",  
      "select": "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 az API-verziók című témakörben találja. Ehhez a művelethez az API-verzió lekérdezési paraméterként van megadva az URL-címben, függetlenül attól, hogy GET vagy POST használatával hívja-e meg az API-t.
$filter sztring Választható. Egy kifejezés, amely szűri a javaslatokat tartalmazó dokumentumokat. Szűrőben csak szűrhető mezők használhatók. Az Automatikus kiegészítés API nem támogatja a "search.ismatch" és a "search.ismatchscoring*" szűrőkifejezéseket. 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. A szerkesztési távolság lekérdezési sztringenként 1. Ha a lekérdezési sztring több kifejezésből áll, a teljes sztringben csak egy hiányzó, extra, helyettesítő vagy transzponált karakter szerepelhet. Az intelligens egyezés engedélyezése bizonyos esetekben jobb élmény lehet, hiszen teljesítményköltséggel jár, mivel a homályos javaslatok keresése lassabb, és több erőforrást használ 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ékkó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).
$orderby sztring Választható. Vesszővel tagolt kifejezések listája az eredmények szerint történő rendezéshez. Minden kifejezés lehet mezőnév vagy a függvény hívása geo.distance() . Minden kifejezést követhet az "asc" (növekvő) vagy a "desc" (csökkenő). Az alapértelmezett érték a növekvő sorrend. A $orderby legfeljebb 32 záradékot tartalmaz. Ha POST-tal hívjuk meg, ez a paraméter a $orderby helyett sorrendben van elnevezve.
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 minimumCoverage értékétől függetlenül az index százalékos arányának elérhetőnek kell lennie, vagy a Javaslatok a HTTP 503-at tartalmazó állapotkódot adja vissza. Ha a javaslatok sikeresek 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 lekérdezések javaslatához használandó 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.
$select sztring Választható. A lekérendő vesszővel elválasztott mezők listája. Ha nincs meghatározva, a rendszer csak a dokumentumkulcsot és a javaslat szövegét adja vissza. Az összes mezőt explicit módon kérheti le, ha ezt a paramétert a értékre állítja *. Ha POST használatával hív, a paraméter neve select (kiválasztás) lesz a $select helyett.
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értelmezett érték: 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áskor ez a paraméter a $top helyett a felső névvel lesz elnevezve.

Reagálás

Állapotkód: A rendszer az "200 OK" értéket adja vissza a sikeres válaszhoz.

{  
  "@search.coverage": # (if minimumCoverage was provided in the query),  
  "value": [  
    {  
      "@search.text": "...",  
      "<key field>": "..."  
    },  
    ...  
  ]  
}

Ha a leképezési beállítással kéri le a mezőket, a tömb minden eleme tartalmazza őket:

{  
  "value": [  
    {  
      "@search.text": "...",  
      "<key field>": "..."  
      <other projected data fields>  
    },  
    ...  
  ]  
}

Példák

5 javaslat lekérése, ahol a részleges keresési bemenet "lux":

GET /indexes/hotels/docs/suggest?search=lux&$top=5&suggesterName=sg&api-version=2020-06-30 

POST /indexes/hotels/docs/suggest?api-version=2020-06-30 
    {  
      "search": "lux",  
      "top": 5,  
      "suggesterName": "sg"  
    }

Figyelje meg, hogy a suggesterName megadása kötelező a Javaslatok műveletben.

Lásd még