Keresési dokumentumok (Azure AI Search REST API)

Cikk
11/13/2023

A lekérdezési kérelem egy keresési szolgáltatás egyetlen indexének dokumentumgyűjteményét célozza meg. Olyan paramétereket tartalmaz, amelyek meghatározzák a megfeleltetés feltételeit, valamint a választ meghatározó paramétereket. A 2021-04-30-Preview API-verziótól kezdve egy indexalias használatával is megcélozhat egy adott indexet, nem pedig magát az indexnevet.

Használhatja a GET vagy a POST parancsot. A lekérdezési paraméterek a GET-kérések lekérdezési sztringjében és a POST-kérések kérelemtörzsében vannak megadva.

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

HA POST-ot használ, adja hozzá a "search" műveletet URI-paraméterként.

POST https://[service name].search.windows.net/indexes/[index name]/docs/search?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 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 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.
[lekérdezési paraméterek]	A lekérdezési paraméterek a GET-kérések URI-ján és a POST-kérések kérelemtörzsében vannak megadva.
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 Dokumentumok keresése művelethez url-kódolásra lehet szükség a következő lekérdezési paraméterekhez:

keresés
$filter
Tényezője
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 "application/json" értékre
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 .

Mezők

Description

Content-Type

Kötelező. Állítsa ezt "application/json" értékre

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:

{  
     "count": true | false (default),  
     "facets": [ "facet_expression_1", "facet_expression_2", ... ],  
     "filter": "odata_filter_expression",  
     "highlight": "highlight_field_1, highlight_field_2, ...",  
     "highlightPreTag": "pre_tag",  
     "highlightPostTag": "post_tag",  
     "minimumCoverage": # (% of index that must be covered to declare query successful; default 100),  
     "orderby": "orderby_expression",  
     "queryType": "simple" (default) | "full",
     "scoringParameters": [ "scoring_parameter_1", "scoring_parameter_2", ... ],  
     "scoringProfile": "scoring_profile_name",  
     "scoringStatistics" : "local" | "global",
     "search": "simple_query_expression",  
     "searchFields": "field_name_1, field_name_2, ...",  
     "searchMode": "any" (default) | "all",  
     "select": "field_name_1, field_name_2, ...",  
     "sessionId" : "session_id",
     "skip": # (default 0),  
     "top": #  
   }

Részleges keresési válaszok folytatása

Előfordulhat, hogy az Azure AI Search nem tudja visszaadni az összes kért találatot egyetlen keresési válaszban. Ez különböző okokból történhet, például ha a lekérdezés túl sok dokumentumot kér, mert nem ad meg $top vagy ad meg túl nagy értéket $top . Ilyen esetekben az Azure AI Search tartalmazza a @odata.nextLink megjegyzést a válasz törzsében, valamint azt is @search.nextPageParameters , hogy post kérés volt-e. Ezeknek a széljegyzeteknek az értékeit használva létrehozhat egy másik keresési kérést a keresési válasz következő részének lekéréséhez. Ezt nevezzük az eredeti keresési kérelem folytatásának , és a széljegyzeteket általában folytatási jogkivonatoknak nevezzük. A megjegyzések szintaxisáról és a válasz törzsében való megjelenésükről az alábbi Válasz szakaszban talál további információt.

Az Azure AI Search által visszaadott folytatási jogkivonatok implementációspecifikusak és változhatnak. A robusztus ügyfeleknek mindig készen kell állniuk az olyan esetek kezelésére, amikor a rendszer a vártnál kevesebb dokumentumot ad vissza, és a dokumentumok lekérésének folytatásához egy folytatási jogkivonatot is tartalmaz. Azt is vegye figyelembe, hogy a folytatáshoz ugyanazt a HTTP-metódust kell használnia, mint az eredeti kérés. Ha például GET kérést küldött, az elküldött folytatási kéréseknek a GET (és a POST) függvényt is használniuk kell.

Megjegyzés

A és @search.nextPageParameters célja@odata.nextLink, hogy megvédje a szolgáltatást a túl sok eredményt kérő lekérdezésektől, nem pedig általános mechanizmust biztosít a lapozáshoz. Ha az eredményeket szeretné áttekinteni, használja $top együtt a és $skip a elemet. Ha például 10-es méretű oldalakat szeretne, az első kérésnek és , a másodiknak $top=10 és $skip=10, a harmadik kérésnek és $skip=20, és így tovább kell lennie$top=10.$skip=0$top=10

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ó URI-paraméterként van megadva, függetlenül attól, hogy get vagy POST használatával hívja-e meg a Keresési dokumentumok szolgáltatást .
`$count`	boolean	Választható. Az érvényes értékek "igaz" vagy "hamis". Alapértelmezés szerint "false" (hamis). A POST használatával történő meghívásakor ez a paraméter a count (darabszám) nevet adja a helyett `$count`. Meghatározza, hogy lekérje-e az eredmények teljes számát. Ez az összes olyan dokumentum száma, amely megfelel a keresési és $filter paramétereknek, figyelmen kívül hagyva a és `$skip`a paramétert`$top`. Ha ezt az értéket "true" értékre állítja, az ronthatja a teljesítményt. A darabszám akkor pontos, ha az index stabil, de a aktívan hozzáadott, frissített vagy törölt dokumentumok alatt vagy felül lesz jelentve. Ha csak a dokumentum nélküli darabszámot szeretné megkapni, használhatja `$top`az =0 értéket.
aspektusok vagy aspektusok	sztring	Választható. Egy olyan mező, amelyet fel kell meddőíteni, ahol a mező "facetable" (facetable) attribútummal van elosztva. Ha a GET metódussal hívja meg, `facet` az egy mező (`facet: field1`). A POST metódussal történő meghívásakor a paraméter neve a helyett`facet`, `facets` tömbként (`facets: [field1, field2, field3]`) van megadva. A sztring tartalmazhat paramétereket az arculat testreszabásához, vesszővel tagolt név-érték párokként kifejezve. Az érvényes paraméterek a következők: "count", "sort", "values", "interval" és "timeoffset". A "count" a aspektuskifejezések maximális száma; alapértelmezett értéke 10. A kifejezések számának nincs felső korlátja, de a magasabb értékek rontják a teljesítményt, különösen akkor, ha a kiemelt mező nagy számú egyedi kifejezést tartalmaz. A "facet=category,count:5" például az első öt kategóriát kapja meg az aspektuseredményekben. Ha a count paraméter kisebb, mint az egyedi kifejezések száma, előfordulhat, hogy az eredmények nem pontosak. Ennek az az oka, ahogyan az arculati lekérdezések el vannak osztva a szegmensek között. A darabszámot nullára vagy olyan értékre állíthatja, amely nagyobb vagy egyenlő a facetable mező egyedi értékeinek számával, hogy pontos számot kapjon az összes szegmensben. A kompromisszum nagyobb késést jelent. A "rendezés" értéke lehet "count", "-count", "value", "-value". A darabszám használatával csökkenő sorrendbe rendezhet darabszám szerint. A -count függvénnyel növekvő sorrendet rendezhet szám szerint. Az érték használatával növekvő sorrendbe rendezhet érték szerint. A -value függvénnyel csökkenő sorrendben rendezhet érték szerint (például a "facet=category,count:3,sort:count" a aspektus első három kategóriáját kapja, és csökkenő sorrendben jeleníti meg az egyes városneveket tartalmazó dokumentumok számát). Ha az első három kategória a Költségvetés, a Motel és a Luxus, és a Budget 5 találatot, Motel 6, a Luxus pedig 4, akkor a gyűjtők sorrendben Motel, Budget, Luxus. A -value esetében a "facet=rating,sort:-value" gyűjtőket hoz létre az összes lehetséges értékeléshez, érték szerinti csökkenő sorrendben (például ha az értékelések 1 és 5 között vannak, a gyűjtők 5, 4, 3, 2, 1 sorrendben jelennek meg, függetlenül attól, hogy hány dokumentum felel meg az egyes értékeléseknek). Az "értékek" értéke lehet pipe-delimited numerikus vagy Edm.DateTimeOffset érték, amely a aspektusbejegyzési értékek dinamikus készletét adja meg (például "facet=baseRate,values:10 \| A 20" három gyűjtőt állít elő: egyet az alapkamat 0-ig, de nem tartalmazza a 10-et, egyet a 10-hez, a 20-ig, egyet pedig a 20-hoz és a magasabbhoz). A "facet=lastRenovationDate,values:2010-02-01T00:00:00Z" sztring két gyűjtőt hoz létre: egyet a 2010. február előtt felújított szállodákhoz, egyet pedig a 2010. február 1-jei vagy újabb felújítású szállodákhoz. Az értékeknek szekvenciálisan, növekvő sorrendben kell szerepelnie a várt eredmények eléréséhez. Az "intervallum" a számok esetében 0-nál nagyobb egész számintervallum, a dátum-időértékek esetében pedig perc, óra, nap, hét, hónap, negyedév, év. Például a "facet=baseRate,interval:100" gyűjtőket hoz létre a 100-es méretű alapkamattartományok alapján. Ha az alapkamatok 60 és 600 dollár között vannak, akkor 0-100, 100-200, 200-300, 300-400, 400-500 és 500-600 gyűjtők lesznek. A "facet=lastRenovationDate,interval:year" sztring minden évben egy gyűjtőt állít elő a szállodák felújításakor. A "timeoffset" értéke ([+-]hh:mm, [+-]hhmm vagy [+-]hh). Ha ezt használja, az időoffset paramétert össze kell kapcsolni az intervallum beállítással, és csak akkor, ha az Edm.DateTimeOffset típusú mezőre van alkalmazva. Az érték határozza meg az UTC időeltolódását az időhatárok beállításához. Például: "facet=lastRenovationDate,interval:day,timeoffset:-01:00" a 01:00:00 (UTC) időponttól (a cél időzónában éjfélkor) kezdődő naphatárt használja. a darabszám és a rendezés kombinálható ugyanabban a aspektusspecifikációban, de nem kombinálhatók intervallummal vagy értékekkel, és az intervallum és az értékek nem kombinálhatók. A dátum-idő intervallum aspektusait az UTC idő alapján számítja ki a rendszer, ha nincs megadva időeltúllépés. Például: a "facet=lastRenovationDate,interval:day" esetében a naphatár 00:00:00 UTC-kor kezdődik.
$filter	sztring	Választható. Strukturált keresési kifejezés a standard OData szintaxisban. Szűrőben csak szűrhető mezők használhatók. Post használatával történő híváskor ezt a paramétert $filter helyett szűrőnek nevezik el. 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.
Kiemelni	sztring	Választható. A találatok kiemeléséhez használt vesszővel tagolt mezőnevek halmaza. A találatok kiemeléséhez csak kereshető mezők használhatók. Alapértelmezés szerint az Azure AI Search mezőnként legfeljebb 5 kiemelést ad vissza. A korlát mezőnként konfigurálható úgy, hogy a mező neve után hozzáfűzi a "-<max # of highlights>" értéket. A "highlight=title-3,description-10" például legfeljebb 3 kiemelt találatot ad vissza a címmezőből, és legfeljebb 10 találatot a leírás mezőből. A kiemelések maximális számának 1 és 1000 közötti egész számnak kell lennie.
highlightPostTag	sztring	Választható. Az alapértelmezett érték: `"</em>"`. 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).
highlightPreTag	sztring	Választható. Az alapértelmezett érték: `"</em>"`. Egy sztringcímke, amely a kiemelt kifejezésre hivatkozik. A highlightPostTag 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).
minimumCoverage	egész szám	Választható. Az érvényes értékek egy 0 és 100 közötti szám, amely azt jelzi, hogy az indexnek hány százalékban kell rendelkezésre állnia ahhoz, hogy a lekérdezést sikeresként lehessen jelenteni. Alapértelmezés szerint "100". A száz százalékos lefedettség azt jelenti, hogy minden szegmens válaszolt a kérésre (sem a szolgáltatás állapotával kapcsolatos problémák, sem a karbantartási tevékenységek nem csökkentették a lefedettséget). Az alapértelmezett beállításnál kevesebb, mint teljes lefedettség adja vissza az 503-at a HTTP-állapotkódnak. A minimális adatátvétel csökkentése akkor lehet hasznos, ha 503-at érintő hibák történnek, és növelni szeretné a lekérdezések sikerességének valószínűségét, különösen az egy replikához konfigurált szolgáltatások esetében. Ha beállítja a minimumátvételt, és a keresés sikeres, a HTTP 200 értéket adja vissza, és a válaszban szerepel egy @search.coverage érték, amely a lekérdezésben szereplő index százalékos arányát jelzi. Ebben a forgatókönyvben nem minden egyező dokumentum szerepel a keresési eredmények között, de ha a keresés elérhetősége fontosabb a visszahívásnál, akkor a lefedettség csökkentése megvalósítható kockázatcsökkentési stratégia lehet.
$orderby	sztring	Választható. Vesszővel tagolt kifejezések listája az eredmények rendezéséhez. Ha POST használatával hívja meg, a paraméter neve orderby lesz, nem pedig $orderby. Minden kifejezés lehet mezőnév vagy a geo.distance() függvény hívása. Minden kifejezés után az "asc" betűvel növekvő, a "desc" pedig csökkenő értéket jelölhet. Ha a rendezési mezőben null értékek szerepelnek, a null értékek először növekvő sorrendben, majd csökkenő sorrendben jelennek meg. Az alapértelmezett érték a növekvő sorrend. A dokumentumok egyezési pontszáma megszakítja a kötelékeket. Ha nincs megadva $orderby, az alapértelmezett rendezési sorrend a dokumentumegyezés pontszáma szerint csökkenő lesz. A $orderby legfeljebb 32 záradékot tartalmaz.
queryType	sztring	Választható. Az érvényes értékek "egyszerűek" vagy "teljesek". Alapértelmezés szerint "egyszerű". Az "egyszerű" a lekérdezési sztringeket az egyszerű lekérdezési szintaxissal értelmezi, amely lehetővé teszi az olyan szimbólumok használatát, mint `+`a és `*""`a . A lekérdezések kiértékelése alapértelmezés szerint az egyes dokumentumok összes kereshető mezőjében (vagy a keresőmezőkben megadott mezőkben) történik. A "full" a lekérdezési sztringeket a teljes Lucene lekérdezési szintaxissal értelmezi, amely lehetővé teszi a mezőspecifikus és súlyozott kereséseket. A Lucene lekérdezési nyelv tartománykeresése nem támogatott a hasonló funkciókat kínáló $filter mellett.
scoringParameter	sztring	Választható. Egy pontozófüggvényben (például referencePointParameter) definiált paraméterek értékeit jelzi a "name-value1,value2,... A POST használatával történő meghívásakor ez a paraméter a scoringParameters nevet viseli a scoringParameters helyett. Emellett sztringek JSON-tömbjeként is megadhatja, ahol minden sztring külön név-érték pár. Függvényt tartalmazó pontozási profilok esetén válassza el a függvényt a bemeneti listától egy `-` karakterrel. Egy nevű `"mylocation"` függvény például "&scoringParameter=mylocation--122.2,44.8". Az első kötőjel elválasztja a függvény nevét az értéklistától, míg a második kötőjel az első érték része (ebben a példában a hosszúság). Az olyan pontozási paramétereknél, mint a vesszőket tartalmazó címkék kiemelése, egyetlen idézőjelek használatával feloldhatja a lista ilyen értékeit. Ha maguk az értékek egyetlen idézőjelet tartalmaznak, a duplikálással feloldhatja őket. Tegyük fel, hogy van egy nevű `"mytag"` címkefokozó paramétere, és a "Hello, O'Brien" és "Smith" címkeértékeket szeretné növelni, a lekérdezési sztring beállítás ezután "&scoringParameter=mytag-'Hello, O''Brien',Smith" lesz. Az idézőjelek csak vesszőt tartalmazó értékekhez szükségesek.
scoringProfile	sztring	Választható. Egy pontozási profil neve, amely kiértékeli az egyező dokumentumok egyező pontszámait az eredmények rendezése érdekében.
scoringStatistics	sztring	Választható. Az érvényes értékek a "helyi" vagy a "globális" értékek. Az alapértelmezett érték a "local" (helyi). Itt adhatja meg, hogy számítsa ki a pontozási statisztikákat, például a dokumentum gyakoriságát globálisan (az összes szegmensben) a következetesebb pontozás érdekében, vagy helyileg (az aktuális szegmensen) az alacsonyabb késés érdekében. Lásd: Pontozási statisztikák az Azure AI Searchben. A pontozási statisztikákat a rendszer mindig helyileg számítja ki az intelligens keresést (~) használó kifejezésekhez.
keresés	sztring	Választható. A keresendő szöveg. Az összes kereshető mező alapértelmezés szerint keres, kivéve, ha a searchFields paraméter meg van adva. Az indexben a kereshető mezőkben lévő szöveg jogkivonatos, így több kifejezés is elválasztható szóközzel (például: 'search=hello world'). Bármely kifejezésnek megfeleltethető a használata `` (ez logikai szűrőlekérdezések esetén lehet hasznos). A paraméter kihagyása ugyanazzal a hatással jár, mint a értékre állítása ``. A keresési szintaxissal kapcsolatos részletekért lásd: Egyszerű lekérdezési szintaxis . Az eredmények néha meglepőek lehetnek a kereshető mezők lekérdezésekor. A tokenizer olyan logikát tartalmaz, amely az angol szövegben gyakran előforduló eseteket, például aposztrófokat, számok vesszőit stb. kezeli. A "search=123,456" kifejezés például egyetlen "123 456" kifejezéssel fog megegyezni, nem pedig az "123" és a "456" egyedi kifejezéssel, mivel a vesszőket több ezer elválasztóként használják angolul nagy számokhoz. Ezért azt javasoljuk, hogy írásjelek helyett használjon szóközt a keresési paraméterben lévő kifejezések elválasztásához.
searchMode	sztring	Választható. Az érvényes értékek az "any" vagy az "all" Alapértelmezett értékek az "any" értékre. Itt adhatja meg, hogy a keresési kifejezések bármelyikének vagy mindegyikének egyeznie kell-e ahhoz, hogy a dokumentumot egyezésnek számítsa.
searchFields	sztring	Választható. A megadott szöveg kereséséhez használandó vesszővel tagolt mezőnevek listája. A célmezőket kereshetőként kell megjelölni az indexsémában.
$select	sztring	Választható. Az eredményhalmazba felvenni kívánt vesszővel tagolt mezők listája. Ebben a záradékban csak lekérdezhetőként megjelölt mezők vehetők fel. Ha nincs meghatározva vagy értékre `*`van állítva, akkor a sémában lekérdezhetőként megjelölt összes mező szerepel a leképezésben. Ha POST használatával hívja meg, a paraméter neve select lesz $select helyett.
Munkamenet	sztring	Választható. A sessionId használatával javíthatja a több replikával rendelkező keresési szolgáltatások relevanciapont-konzisztenciáját. A többreplika-konfigurációkban az egyes dokumentumok relevanciapontszámai között kisebb különbségek lehetnek ugyanazon lekérdezés esetében. Amikor meg van adva egy munkamenet-azonosító, a szolgáltatás mindent megtesz annak érdekében, hogy egy adott kérést ugyanarra a replikára irányítson az adott munkamenethez. Legyen óvatos, ha ugyanazokat a munkamenet-azonosító értékeket ismételten használja fel, megzavarhatja a kérések terheléselosztását a replikák között, és hátrányosan befolyásolhatja a keresési szolgáltatás teljesítményét. A sessionIdként használt érték nem kezdődhet _karakterrel. Ha egy szolgáltatás nem rendelkezik replikákkal, ez a paraméter nincs hatással a teljesítményre vagy a pontszám konzisztenciájára.
$skip	egész szám	Választható. A kihagyandó keresési eredmények száma. A POST használatával történő meghívásakor a paraméter neve kihagyás lesz a helyett `$skip`. Ez az érték nem lehet nagyobb 100 000-nél. Ha egymás után kell beolvasnia a dokumentumokat, de ez a korlátozás miatt nem `$skip` használható, fontolja meg $orderby használatát egy olyan mezőn, amely egyedi értékekkel rendelkezik az index minden dokumentumához (például a dokumentumkulcshoz), és $filter egy tartomány lekérdezésével.
$top	egész szám	Választható. A lekérendő keresési eredmények száma. Ez az alapértelmezett érték 50. A POST metódussal történő meghívásakor a paraméter neve felső lesz a helyett `$top`. Ha 1000-nél nagyobb értéket ad meg, és több mint 1000 találatot ad meg, csak az első 1000 eredményt adja vissza, valamint egy hivatkozást az eredmények következő oldalára (lásd @odata.nextLink az alábbi példát). Az Azure AI Search kiszolgálóoldali lapozással megakadályozza, hogy a lekérdezések egyszerre túl sok dokumentumot lekértek. Az alapértelmezett oldalméret 50, a maximális oldalméret pedig 1000. Ez azt jelenti, hogy alapértelmezés szerint a Keresési dokumentumok legfeljebb 50 találatot ad vissza, ha nem adja meg a értéket `$top`. Ha több mint 50 találat van, a válasz legfeljebb 50 találat következő oldalának lekérésére vonatkozó információkat tartalmaz (lásd az alábbi példákban a "@odata.nextLink" és a "@search.nextPageParameters" részt). Hasonlóképpen, ha 1000-nél `$top` nagyobb értéket ad meg, és több mint 1000 találat van, csak az első 1000 találat lesz visszaadva, valamint a legfeljebb 1000 találatból álló következő oldal lekéréséhez szükséges információk.

Reagálás

Állapotkód: Sikeres válasz esetén a rendszer 200 OK-t ad vissza.

  {
    "@odata.count": # (if `$count`=true was provided in the query),
    "@search.coverage": # (if minimumCoverage was provided in the query),
    "@search.facets": { (if faceting was specified in the query)
      "facet_field": [
        {
          "value": facet_entry_value (for non-range facets),
          "from": facet_entry_value (for range facets),
          "to": facet_entry_value (for range facets),
          "count": number_of_documents
        }
      ],
      ...
    },
    "@search.nextPageParameters": { (request body to fetch the next page of results if not all results could be returned in this response and Search was called with POST)
      "count": ... (value from request body if present),
      "facets": ... (value from request body if present),
      "filter": ... (value from request body if present),
      "highlight": ... (value from request body if present),
      "highlightPreTag": ... (value from request body if present),
      "highlightPostTag": ... (value from request body if present),
      "minimumCoverage": ... (value from request body if present),
      "orderby": ... (value from request body if present),
      "scoringParameters": ... (value from request body if present),
      "scoringProfile": ... (value from request body if present),
      "scoringStatistics": ... (value from request body if present),
      "search": ... (value from request body if present),
      "searchFields": ... (value from request body if present),
      "searchMode": ... (value from request body if present),
      "select": ... (value from request body if present),
      "sessionId" : ... (value from request body if present),
      "skip": ... (page size plus value from request body if present),
      "top": ... (value from request body if present minus page size),
    },
    "value": [
      {
        "@search.score": document_score (if a text query was provided),
        "@search.highlights": {
          field_name: [ subset of text, ... ],
          ...
        },
        "@search.features": {
          "field_name": {
            "uniqueTokenMatches": feature_score,
            "similarityScore": feature_score,
            "termFrequency": feature_score,
          },
          ...
        },
        key_field_name: document_key,
        field_name: field_value (retrievable fields or specified projection),
        ...
      },
      ...
    ],
    "@odata.nextLink": (URL to fetch the next page of results if not all results could be returned in this response; Applies to both GET and POST)
  }

Példák

További példákat az Azure AI Search OData Kifejezésszintaxisában talál.

Keresés az indexben dátum szerint csökkenő sorrendben:

GET /indexes/hotels/docs?search=*&$orderby=LastRenovationDate desc&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "*",  
      "orderby": "LastRenovationDate desc"
    }

A részletes keresés során keressen rá az indexre, és kérje le a kategóriák, értékelések, címkék és elemek aspektusait, amelyek adott tartományokban a baseRate értéket tartalmazzák.
```
GET /indexes/hotels/docs?search=*&facet=Category&facet=Rating&facet=Tags&facet=Rooms/BaseRate,values:80|150|220&api-version=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "test",  
      "facets": [ "Category", "Rating", "Tags", "Rooms/BaseRate,values:80|150|220" ]  
    }  
```
Figyelje meg, hogy az utolsó szempont egy almezőn van. A aspektusok a szülődokumentumot (Szállodák) és nem a köztes aldokumentumokat (Szobák) számolják, így a válasz határozza meg az egyes árgyűjtőkben található szobák számát.

Szűrő használatával szűkítse le az előző aspektusú lekérdezés eredményét, miután a felhasználó a 3. minősítést és a "Motel" kategóriát választja.

GET /indexes/hotels/docs?search=*&facet=tags&facet=Rooms/BaseRate,values:80|150|220&$filter=Rating eq 3 and Category eq 'Motel'&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "test",  
      "facets": [ "tags", "Rooms/BaseRate,values:80|150|220" ],  
      "filter": "Rating eq 3 and Category eq 'Motel'"  
    }

Az aspektusalapú keresésben állítsa be a lekérdezésben visszaadott egyedi kifejezések felső korlátját. Az alapértelmezett érték 10, de ezt az értéket növelheti vagy csökkentheti a facet attribútum count paraméterével. Ez a példa a város aspektusait adja vissza, legfeljebb 5-öt.
```
GET /indexes/hotels/docs?search=*&facet=Address/City,count:5&api-version=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "test",  
      "facets": [ "Address/City,count:5" ]  
    }  
```

Keresés az indexben adott mezőkben (például egy nyelvmezőben):

GET /indexes/hotels/docs?search=hôtel&searchFields=Description_fr&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "hôtel",  
      "searchFields": "Description_fr"
    }

Keresés az indexben több mező között. A kereshető mezőket például több nyelven is tárolhatja és kérdezheti le, ugyanabban az indexben. Ha az angol és a francia leírás együtt szerepel ugyanabban a dokumentumban, a lekérdezési eredmények bármelyikét vagy mindegyikét visszaadhatja:
```
GET /indexes/hotels/docs?search=hotel&searchFields=Description,Description_fr&api-version=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "hotel",  
      "searchFields": "Description, Description_fr"
    }  
```
Az indexet egyszerre csak lekérdezheti. Ne hozzon létre több indexet az egyes nyelvekhez, hacsak nem tervez egyszerre egy lekérdezést.

Lapozás – Az elemek első oldalának lekérése (az oldalméret 10):

GET /indexes/hotels/docs?search=*&$skip=0&$top=10&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "*",  
      "skip": 0,  
      "top": 10  
    }

Lapozás – Az elemek második oldalának lekérése (az oldalméret 10):

GET /indexes/hotels/docs?search=*&$skip=10&$top=10&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "*",  
      "skip": 10,  
      "top": 10  
    }

Adott mezőkészlet lekérése:

GET /indexes/hotels/docs?search=*&$select=HotelName,Description&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "*",  
      "select": "HotelName, Description"
    }

Egy adott szűrőkifejezésnek megfelelő dokumentumok lekérése:

GET /indexes/hotels/docs?$filter=(Rooms/BaseRate ge 60 and Rooms/BaseRate lt 300) or HotelName eq 'Fancy Stay'&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "filter": "(Rooms/BaseRate ge 60 and Rooms/BaseRate lt 300) or HotelName eq 'Fancy Stay'"  
    }

Keressen rá az indexre, és találatkiemelésekkel adja vissza a töredékeket:

GET /indexes/hotels/docs?search=something&highlight=Description&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "something",  
      "highlight": "Description"  
    }

Keressen rá az indexre, és a hivatkozási helytől közelebbről távolabb rendezett dokumentumokat adjon vissza:

GET /indexes/hotels/docs?search=something&$orderby=geo.distance(Location, geography'POINT(-122.12315 47.88121)')&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "something",  
      "orderby": "geo.distance(Location, geography'POINT(-122.12315 47.88121)')"
    }

Keressen rá az indexre, feltéve, hogy van egy "geo" nevű pontozási profil két távolsági pontozási függvénysel, az egyik az "currentLocation" nevű paramétert definiálja, a másik pedig a "lastLocation" paramétert definiálja. A következő példában az "currentLocation" egy kötőjel elválasztójelével rendelkezik (-). Ezt a hosszúsági és szélességi koordináták követik, ahol a hosszúság negatív érték.
```
GET /indexes/hotels/docs?search=something&scoringProfile=geo&scoringParameter=currentLocation--122.123,44.77233&scoringParameter=lastLocation--121.499,44.2113&api-version=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "something",  
      "scoringProfile": "geo",  
      "scoringParameters": [ "currentLocation--122.123,44.77233", "lastLocation--121.499,44.2113" ]  
    }  
```
Dokumentumok keresése az indexben egyszerű lekérdezési szintaxis használatával. Ez a lekérdezés olyan szállodákat ad vissza, ahol a kereshető mezők a "kényelem" és a "hely" kifejezést tartalmazzák, de nem a "motel" kifejezést:
```
Get /indexes/hotels/docs?search=comfort +location –motel&searchMode=all&api-version=22020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "comfort +location -motel",  
      "searchMode": "all"  
    }  
```
Tipp

A felülbírálások használata searchMode=all az alapértelmezett érték searchMode=any, biztosítva, hogy " -motel ÉS NEM" legyen a "VAGY NEM" helyett. Nélküle searchMode=all"VAGY NEM" jelenik meg, amely nem korlátozza, hanem kibontja a keresési eredményeket, és ez egyes felhasználók számára nem magától értetődő lehet.
Dokumentumok keresése az indexben Lucene lekérdezési szintaxissal). Ez a lekérdezés olyan szállodákat ad vissza, ahol a kategóriamező tartalmazza a "budget" kifejezést és az összes kereshető mezőt, amely a "nemrég felújított" kifejezést tartalmazza. A "nemrég felújított" kifejezést tartalmazó dokumentumok rangsorolása magasabb a kiemelési érték kifejezés miatt (3)
```
GET /indexes/hotels/docs?search=Category:budget AND \"recently renovated\"^3&searchMode=all&api-version=2020-06-30&querytype=full` 
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
     "search": "Category:budget AND \"recently renovated\"^3",  
      "queryType": "full",  
      "searchMode": "all"  
}  
```
Dokumentumok keresése az indexben, miközben a következetes pontozást részesíti előnyben az alacsonyabb késéssel szemben. Ez a lekérdezés kiszámítja a dokumentum gyakoriságát a teljes indexben, és mindent megtesz annak érdekében, hogy ugyanazt a replikát ugyanazon a "munkameneten" belül minden lekérdezéshez megcélzhatja, ami segít stabil és reprodukálható rangsorolást létrehozni.
```
GET /indexes/hotels/docs?search=hotel&sessionId=mySessionId&scoringStatistics=global&api-version=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "hotel",  
      "sessionId": "mySessionId",
      "scoringStatistics" :"global"
    }  
```