Dokumentumok keresése (Azure Cognitive Search REST API)

A lekérdezési kérelem a keresési szolgáltatás egyetlen indexének dokumentum-gyűjteményét célozza meg. Olyan paramétereket tartalmaz, amelyek meghatározzák az egyeztetési feltételeket, valamint a választ alkotó paramétereket.

Használhatja a GET vagy a POST bejegyzést. Lekérdezési paraméterek vannak megadva a lekérdezési karakterláncban a Get kérések esetén, valamint a kérelem törzsében a post kérések esetében.

GET https://[service name].search.windows.net/indexes/[index name]/docs?[query parameters] 
  Content-Type: application/json   
  api-key: [admin or query key]  
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 értékkel való híváskor a kérelem URL-címének hossza nem haladhatja meg a 8 KB-ot. Ez a hossz általában elég a legtöbb alkalmazáshoz. Egyes alkalmazások azonban nagyon nagy lekérdezéseket hoznak létre, pontosabban a OData szűrési kifejezéseket használják. Ezekhez az alkalmazásokhoz a HTTP POST jobb választás, mivel nagyobb szűrőket tesz lehetővé, mint a GET.

A POST utasításban a szűrőben szereplő záradékok száma a korlátozási tényező, nem pedig a nyers szűrő karakterláncának mérete, mivel a BEJEGYZÉSre vonatkozó kérelem mérete körülbelül 16 MB. Bár a POST kérelem méretének korlátja nagyon nagy, a szűrési kifejezések nem lehetnek kényesen bonyolultak. Az összetettségi korlátokkal kapcsolatos további információkért tekintse meg az Azure Cognitive Search OData kifejezés szintaxisát.

URI-paraméterek

Paraméter Leírás
[szolgáltatás neve] Kötelező. Ezt állítsa be a keresési szolgáltatás egyedi, felhasználó által definiált nevére.
[index neve]/docs Kötelező. Megnevezett index dokumentumainak gyűjteményét adja meg.
[lekérdezési paraméterek] A lekérdezési paraméterek a GET kérelmek esetében az URI-n vannak megadva, a kérelem törzsében pedig a POST kérések.
api-verzió Kötelező. A jelenlegi verzió: api-version=2020-06-30 . Az összes támogatott verzió listáját lásd: API-verziók az Azure Cognitive Search. A keresési dokumentumok esetében az API-verzió mindig URI-paraméterként van megadva mind a Get, mind a post értékhez.

URL – kódolási javaslatok

Ne feledje, hogy az URL-cím- specifikus lekérdezési paramétereket kódolja a Get REST API közvetlen hívásakor. A keresési dokumentumok műveletéhez URL-kódolásra lehet szükség a következő lekérdezési paraméterekhez:

  • keresés
  • $filter
  • dimenzió
  • highlightPreTag
  • highlightPostTag

Az URL-kódolás csak az egyes paraméterek esetében ajánlott. Ha véletlenül URL-kódolással kódolja a teljes lekérdezési karakterláncot (mindent a után ? ), a kérések megszakadnak.

Emellett az URL-kódolás csak akkor szükséges, ha a REST API közvetlenül a GET paranccsal hívja meg. A POST vagy az Azure Cognitive Search .net Ügyféloldali kódtárhasználata esetén nincs szükség URL-kódolásra, amely kezeli a kódolást.

Kérések fejlécei

A következő táblázat ismerteti a kötelező és választható kérelmek fejléceit.

Mezők Leírás
Content-Type Kötelező. Beállítás az "Application/JSON" értékre
API-kulcs Kötelező. Egy egyedi, rendszer által generált karakterlánc, amely hitelesíti a kérést a keresési szolgáltatásban. A dokumentumok gyűjteményének lekérdezési kérelmei az API-kulcsként rendszergazdai vagy lekérdezési kulcsot is megadhatnak. A lekérdezési kulcs csak olvasási műveletekhez használható a dokumentumok gyűjteményében. A Azure Portal kulcsait lekérheti. További információt a meglévő kulcsok keresésecímű témakörben talál.

Kérelem törzse

A GET: none értékre.

POST:

{  
     "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

Az Azure Cognitive Search néha egyetlen keresési válaszban nem tudja visszaadni az összes kért eredményt. Ez különböző okok miatt fordulhat elő, például ha a lekérdezés túl sok dokumentumot kér, mert nem határoz meg $top, vagy nem ad meg értéket a túl nagy $top. Ilyen esetekben az Azure Cognitive Search tartalmazni fogja a @odata.nextLink megjegyzését a válasz törzsében, valamint azt is, @search.nextPageParameters hogy post kérelem volt-e. A megjegyzések értékeit egy másik keresési kérelem létrehozásához használhatja a keresési válasz következő részének beszerzéséhez. Ezt az eredeti keresési kérelem folytatásaként hívják, és a jegyzetek általában folytatólagos tokenek. Tekintse meg az alábbi példát a megjegyzések szintaxisával kapcsolatos részletekért, és hogy hol jelenjenek meg a válasz törzsében.

Az Azure Cognitive Search a folytatási tokenek visszaküldésének okai a megvalósításra jellemzőek, és változhatnak. A robusztus ügyfeleknek mindig készen kell állniuk arra, hogy kezeljék azokat az eseteket, amelyekben a vártnál kevesebb dokumentum érkezik, és a folytatási token beletartozik a dokumentumok beolvasásának folytatására Azt is vegye figyelembe, hogy a folytatáshoz ugyanazt a HTTP-metódust kell használnia, mint az eredeti kérelem. Ha például egy GET-kérést küldött, az Ön által küldött folytatási kéréseknek is a GET (és hasonló a POST) értékre kell használniuk.

Megjegyzés

A célja, @odata.nextLink @search.nextPageParameters hogy megvédje a szolgáltatást olyan lekérdezésektől, amelyek túl sok eredményt igényelnek, és nem biztosítanak általános mechanizmust a lapozáshoz. Ha az eredményeket szeretné áttekinteni, használja a $top és $skip együtt. Ha például a 10-es méretű lapokat szeretné használni, akkor az első kérésnek $top = 10 és $skip = 0 karakternek kell lennie, a második kérelemnek $top = 1 és $skip = 10 értékkel kell rendelkeznie, a harmadik kérelemnek $top = 10 és $skip = 20 értékkel kell rendelkeznie, és így tovább.

Lekérdezési paraméterek

A lekérdezés az URL-cím során több paramétert is elfogad, ha az hívás a GET kifejezéssel, a kérelem törzsében pedig JSON-tulajdonságok néven a POST parancs hívásakor. Egyes paraméterek szintaxisa némileg eltér a beolvasás és a közzététel között. Ezeket a különbségeket az alábbiakban ismertetett módon kell megállapítani.

Név Típus Leírás
api-verzió sztring Kötelező. A kérelemhez 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-Version URI-paraméterként van megadva, függetlenül attól, hogy a keresési dokumentumokat a Get vagy a post művelettel hívja meg.
$count boolean Választható. Az érvényes értékek: "true" vagy "false". Az alapértelmezett érték a "false". A POST nevű hívás esetén a paraméter neve $count helyett Count. Megadja, hogy le kell-e hívni 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 $top és $skip. Ha ezt az értéket "true" értékre állítja, a teljesítmény csökkenhet. A visszaadott szám egy közelítés. Ha csak a darabszámot szeretné lekérni a dokumentumok nélkül, használhatja a $top = 0 értéket.
dimenzió sztring Választható. Egy mező, amelynek a dimenziója a következő:. A karakterlánc tartalmazhat olyan paramétereket, amelyekkel testre szabható az aspektus, vesszővel tagolt név-érték párokként kifejezve. A POST nevű hívás esetén ez a paraméter a dimenzió helyett dimenzióként van elnevezve.

Az érvényes érték a "Count", a "sort", az "Values", az "Interval" és a "timeoffset".

a "Count" a dimenziós kifejezések maximális száma; az alapértelmezett érték 10. A feltételek száma nem rendelkezik felső korláttal, de a magasabb értékek csökkentik a teljesítményt, különösen akkor, ha a csiszolt mező nagy mennyiségű egyedi kifejezést tartalmaz. Például az "aspektus = kategória, darabszám: 5" az első öt kategóriát kapja meg a dimenzió eredményei között. Ha a Count paraméter értéke kisebb, mint az egyedi kifejezések száma, előfordulhat, hogy az eredmények nem pontosak. Ennek oka az, hogy az egymásra épülő lekérdezések a szegmensek között oszlanak meg. A növekvő darabszám általában növeli a lejárati arányok pontosságát, de a teljesítménnyel kapcsolatos költségeket.

a "sort" érték a "Count", a "Count", a "value", a "-value" értékre állítható be. A darabszám szerint rendezheti a csökkenő sorrendet. A Count (használat) érték alapján növekvő sorrendbe rendezheti a darabszámot. Az érték alapján növekvő sorrendbe rendezheti az értéket. A Value (érték) alapján csökkenő sorrendbe rendezheti az értékeket (például: "dimenzió = kategória, darabszám: 3, rendezés: szám") az első három kategóriát a dimenzióban az egyes városokhoz tartozó dokumentumok száma szerint csökkenő sorrendben jeleníti meg. Ha a három legfontosabb kategória a költségvetést, a motelt és a luxust, a költségvetés pedig 5 találatot tartalmaz, a Motel 6, a luxus pedig 4, akkor a gyűjtők az Order Motel, a Budget, a Luxury. A-Value (dimenzió = minősítés, rendezés:-Value) minden lehetséges minősítéshez gyűjtőket állít elő, csökkenő sorrendben (például ha a minősítések 1 és 5 közöttiek, a gyűjtőket 5, 4, 3, 2, 1 értékre kell rendelni, függetlenül attól, hogy hány dokumentum felel meg az egyes minősítéseknek).

a "Values" csak cső-tagolt numerikus vagy EDM lehet. a DateTimeOffset értékek a dimenzióérték-bejegyzések dinamikus készletét határozzák meg (például "Face = baseRate, Values: 10 20"), amely | három gyűjtőt állít elő: az egyik az alapszintű 0, de nem tartalmazza a 10-et, egyet pedig 10-ig, de 20 és magasabb értéket is. A "facet =" Lastrenovationdate, Values: 2010-02-01T00:00:00Z "karakterlánc két gyűjtőt állít elő: az egyiket a 2010 februárjában, a 2010-es vagy újabb verzióval felújított szállodákhoz.

az "Interval" érték egy egész szám, nullánál nagyobb szám, vagy perc, óra, nap, hét, hónap, negyedév, év a dátum-és időértékekhez. A "facet = baseRate, Interval: 100" például a 100 méretű alaparányú tartományokon alapuló gyűjtőket hoz létre. Ha az alapszintű díjak $60 és $600 között vannak, akkor az 0-100, 100-200, 200-300, 300-400, 400-500 és 500-600 gyűjtők lesznek. A "facet =" Lastrenovationdate, Interval: Year "karakterlánc minden évben létrehoz egy gyűjtőt, amikor a hotelek fel lettek újítva.

a "timeoffset" beállítható a következőre: ([+-] hh: PP, [+-] óópp, vagy [+-] hh). Használata esetén a timeoffset paramétert kombinálni kell az intervallum beállítással, és csak akkor, ha az EDM. DateTimeOffset típusú mezőre van alkalmazva. Az érték azt az UTC-időeltolódást adja meg, amelyet az időhatárok beállítása során figyelembe kell venni. Például: "Face =" Lastrenovationdate, Interval: Day, timeoffset:-01:00 "a nap határát használja, amely a 01:00:00 UTC (éjfél a cél időzónában) kezdődik.

a Count és a sort ugyanabban a aspektusban lehet összevonni, de nem kombinálhatók intervallummal vagy értékekkel, és az intervallum és az értékek nem kombinálhatók együtt.

A dátum-és idődimenziókat a rendszer az UTC idő alapján számítja ki, ha a timeoffset nincs megadva. Például: a "facet =" Lastrenovationdate, Interval: Day "esetén a nap határa 00:00:00 UTC-kor kezdődik.
$filter sztring Választható. Egy strukturált keresési kifejezés a standard OData szintaxisban. Szűrőben csak szűrhető mezők használhatók. A POST függvény hívásakor ez a paraméter neve $filter helyett szűrő. Az Azure Cognitive Search által támogatott OData-kifejezés nyelvtanának részletes ismertetését lásd: OData for azure Cognitive Search .
Jelölje ki sztring Választható. A találatok kiemeléséhez használt vesszővel tagolt mezőnevek halmaza. Csak kereshető mezők használhatók a találatok kiemeléséhez. Alapértelmezés szerint az Azure Cognitive Search mezőben legfeljebb 5 kiemelést ad vissza. A határérték mező szerint konfigurálható, ha a mező neve után hozzáfűzi a "- Max # értéket. A "kiemelés = title-3, Description-10" például a title (cím) mezőben legfeljebb 3 Kiemelt találatot ad vissza, a leírás mező pedig legfeljebb 10 találatot jelez. A csúcsfények maximális számának 1 és 1000 közötti egész számnak kell lennie.
highlightPostTag sztring Választható. Alapértelmezett értéke "</em>" . Egy karakterlánc-címke, amely a Kiemelt kifejezéshez van hozzáfűzve. A highlightPreTag értékkel kell beállítani. Az URL-címben foglalt karaktereknek százalékos kódolással kell rendelkezniük (például: %23 a # helyett).
highlightPreTag sztring Választható. Alapértelmezett értéke "</em>" . Egy karakterlánc-címke, amely a Kiemelt kifejezésre paraméterként megadott. A highlightPostTag értékkel kell beállítani. Az URL-címben foglalt karaktereknek százalékos kódolással kell rendelkezniük (például: %23 a # helyett).
minimumCoverage egész szám Választható. Az érvényes értékek 0 és 100 közötti szám, amely azt jelzi, hogy az index hány százalékát kell elérhetőnek lennie ahhoz, hogy a lekérdezés sikeres legyen. Alapértelmezett értéke "100".

A 100%-os lefedettség azt jelenti, hogy minden szegmens válaszol a kérelemre (sem a szolgáltatás állapotával, sem a karbantartási tevékenységekkel csökkentett lefedettséggel). Az alapértelmezett beállításnál a teljes lefedettség kevesebb, mint a 503-as HTTP-állapotkód.

A minimumCoverage csökkentése akkor lehet hasznos, ha 503 hiba történik, és a lekérdezés sikerességének valószínűségét szeretné javítani, különösen az egyik replikához konfigurált szolgáltatások esetében. Ha a minimumCoverage és a keresés értéke sikeres, akkor a HTTP 200 értéket adja vissza, és @search.coverage a lekérdezésben szereplő index százalékos arányát jelző válasz értékét tartalmazza. Ebben a forgatókönyvben nem minden egyező dokumentum garantáltan jelen van a keresési eredmények között, de ha a keresés elérhetősége fontosabb, mint a visszahívás, a lefedettség csökkentése egy életképes, enyhítő stratégiát jelenthet.
$orderby sztring Választható. A vesszővel tagolt kifejezések listája, amely alapján rendezheti az eredményeket. A POST nevű hívás esetén a paraméter neve OrderBy, $orderby helyett. Mindegyik kifejezés lehet mezőnév vagy a Geo. Distance () függvény hívása. Az egyes kifejezéseket "ASC" követve jelezheti a növekvő és a "desc" értéket, hogy jelezze a csökkenő értéket. Ha a rendezési mezőben null értékek vannak, a Null érték először növekvő sorrendben jelenik meg, és az utolsó csökkenő sorrendben történik. Az alapértelmezett érték a növekvő sorrend. A kapcsolatok a dokumentumok egyezési pontszámai szerint lesznek megszakítva. Ha nincs $orderby megadva, az alapértelmezett rendezési sorrend a dokumentum egyezési pontszáma szerint csökkenő sorrendben történik. A $orderbyhoz legfeljebb 32 záradék használható.
queryType sztring Választható. Az érvényes értékek: "Simple" vagy "Full". Az alapértelmezett érték az "egyszerű".

az "egyszerű" kifejezés a lekérdezési karakterláncokat az egyszerű lekérdezési szintaxissal értelmezi, amely lehetővé teszi a következő szimbólumok használatát: + , * és "" . A lekérdezéseket a rendszer alapértelmezés szerint minden dokumentum összes kereshető mezőjében (vagy a searchFields-ben jelzett mezőkben) értékeli ki.

a "teljes" kifejezés a lekérdezési karakterláncokat a teljes Lucene lekérdezési szintaxissal értelmezi, amely lehetővé teszi a mezőkre vonatkozó és súlyozott kereséseket. A Lucene lekérdezési nyelvben nem támogatott a tartománybeli keresés a hasonló funkciókat kínáló $filter javában.
scoringParameter sztring Választható. Egy pontozási függvényben (például referencePointParameter) definiált paraméterek értékeit jelzi a "Name-érték1, érték2,..." formátum használatával. A POST nevű hívás esetén a paraméter neve scoringParameters, a scoringParameter helyett. Azt is megadhatja, hogy a karakterláncok JSON-tömbje legyen, ahol minden karakterlánc külön név-érték párok.

Egy függvényt tartalmazó pontozási profilok esetében válassza el a függvényt a beviteli listából egy - karakterrel. Egy nevű függvény például a "mylocation" következő: "&scoringParameter = mylocation--122.2, 44.8". Az első kötőjel választja el a függvény nevét az érték listábó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éterek esetében, mint például az olyan címkék kiemelése, amelyek vesszőt tartalmazhatnak, a listában szereplő értékeket egyetlen idézőjelek között lehet kimenekülni. Ha az értékek magukban foglalnak egy idézőjelet, megduplázva megteheti őket. Tegyük fel, hogy a "mytag" "Hello, O'Brien" és a "Smith" címke értékének növelésére van szüksége, és a lekérdezési karakterlánc beállítás értéke "&scoringParameter = mytag-'Hello, O" "", Smith ". Az idézőjelek csak a vesszőket tartalmazó értékek esetében szükségesek.
scoringProfile sztring Választható. Egy pontozási profil neve, amely kiértékeli az egyezési pontszámokat a dokumentumok egyeztetéséhez az eredmények rendezése érdekében.
scoringStatistics sztring Választható. Az érvényes értékek a következők: "local" vagy "Global". Az alapértelmezett érték a "local". Itt adhatja meg, hogy ki kell-e számítani a pontozási statisztikát, például a dokumentumok gyakoriságát, globálisan (az összes szegmensben), hogy konzisztens pontozást vagy helyileg (az aktuális szegmensen) az alacsonyabb késést. Lásd: pontozási statisztika az Azure Cognitive Search. A pontozási statisztikák mindig helyileg lesznek kiszámítva a "~"kifejezést használó kifejezések esetében.
keresés sztring Választható. A keresendő szöveg. A rendszer alapértelmezés szerint minden kereshető mezőt keres, ha meg van adva a searchFields. Az indexben a kereshető mezőben lévő szöveg tokenes, így több kifejezés is elválasztható szóközzel (például: "Search = Hello World"). Ha bármilyen kifejezéssel szeretne megfelelni, használja a * (ez hasznos lehet a logikai szűrők lekérdezéséhez). A paraméter kihagyása ugyanaz, mint a beállítás * . Az egyszerű lekérdezési szintaxist a keresési szintaxisban található részleteknél tekintheti meg.

Az eredmények esetenként meglepőek lehetnek a kereshető mezőkre való lekérdezés során. A tokenizer az angol szövegek, például az aposztrófok, a számok és így tovább. A "Search = 123456" például egyetlen "123 456" kifejezésnek felel meg a "123" és a "456" kifejezés helyett, mivel a vesszők az angol nyelvben nagy számok ezres elválasztói lesznek. Ezért javasoljuk, hogy a szóköz helyett a szóközöket használja a keresési paraméterben szereplő feltételek elkülönítéséhez.
searchMode sztring Választható. Az érvényes értékek: "any" vagy "all" alapértelmezett értéke "any". Meghatározza, hogy a keresési kifejezések bármelyikét vagy mindegyikét meg kell-e egyezni a dokumentum egyezésként való megszámlálása érdekében.
searchFields sztring Választható. A megadott szövegben keresendő, vesszővel tagolt mezőnevek listája. A célként megadott mezőket az index sémában kereshetőként kell megjelölni.
$select sztring Választható. Az eredményhalmazban szerepeltetni kívánt vesszővel tagolt mezők listája. Ebben a záradékban csak lekérhető mezők szerepelhetnek. Ha nincs megadva vagy a értékre * van állítva, a sémában lekérdezhető megjelölt összes mező belekerül a kivetítésbe. A POST nevű hívás esetén a paraméter neve $select helyett a Select (kiválasztás) lesz.
sessionId sztring Választható. A munkamenet-azonosítók használatával javíthatja a több replikával rendelkező keresési szolgáltatások relevanciás pontszámának következetességét. A több replika konfigurációjában az egyes dokumentumok relevanciás pontszáma nem lehet azonos a lekérdezéshez. A munkamenet-azonosító megadásakor a szolgáltatás a legjobb erőfeszítést tesz arra, hogy egy adott kérelmet ugyanarra a replikára irányítsa az adott munkamenet esetében. Legyen óvatos, hogy az azonos munkamenet-azonosító értékek ismételt használata megzavarhatja a kérelmek terheléselosztását a replikák között, és negatív hatással lehet a keresési szolgáltatás teljesítményére. A munkamenet-azonosítóval 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 kihagyni kívánt keresési eredmények száma. A POST nevű hívás esetén a paraméter neve kihagyás $skip helyett. Ez az érték nem lehet nagyobb, mint 100 000. Ha meg kell vizsgálnia a dokumentumokat a sorozatban, de a korlátozás miatt nem tudja használni a $skipt, érdemes lehet $orderby egy olyan mezőhöz használni, amely az index összes dokumentumához (például a dokumentum kulcsához) egyedi értékeket tartalmaz, és a $filter egy tartomány lekérdezéssel.
$top egész szám Választható. A lekérdezni kívánt keresési eredmények száma. Ez az alapértelmezett érték a 50. A POST nevű hívás esetén ez a paraméter a $top helyett a legfelső szintű. Ha 1000-nál nagyobb értéket ad meg, és több mint 1000 eredmény szerepel, a rendszer csak az első 1000-eredményeket adja vissza, valamint az eredmények következő oldalára mutató hivatkozást (lásd @odata.nextLink az alábbi példát).

Az Azure Cognitive Search kiszolgálóoldali lapozást használ annak megakadályozására, hogy a lekérdezések túl sok dokumentumot kérjenek le egyszerre. Az oldalméret alapértelmezett mérete 50, míg a maximális oldalméret 1000. Ez azt jelenti, hogy alapértelmezés szerint a keresési dokumentumok legfeljebb 50 eredményt adnak vissza, ha nem ad meg $Top. Ha több mint 50 eredmény van, akkor a válasz a legfeljebb 50 eredmény következő oldalának lekérésére vonatkozó információkat tartalmazza (lásd @odata.nextLink @search.nextPageParameters az alábbi példákat : "" és "". Hasonlóképpen, ha a $top értéknél 1000 nagyobb értéket ad meg, és több mint 1000 eredmény van megadva, akkor csak az első 1000-as eredmény lesz visszaadva, valamint a legfeljebb 1000 találat következő oldalának lekéréséhez szükséges információkkal.

Reagálás

Állapotkód: 200 OK a sikeres válaszhoz.

  {
    "@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

Az Azure Cognitive Search OData kifejezés szintaxisábantovábbi példákat is talál.

  1. Keresés az index 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"
        }  
    
  2. A részletes keresés során kereshet az indexben, és beolvashatja a kategóriákat, a minősítéseket, a címkéket, valamint az adott tartományokban lévő baseRate elemeket.

    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ó dimenzió egy almezőn van. Az aspektusok megszámolják a fölérendelt dokumentumot (szállodákat) és nem köztes aldokumentumokat (szobák), így a válasz határozza meg, hogy hány olyan szálloda található, amely minden szobában szerepel a gyűjtőben.

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

    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'"  
        }  
    
  4. Egy sokoldalú keresésnél állítson be egy felső korlátot a lekérdezésben visszaadott egyedi kifejezésekhez. Az alapértelmezett érték 10, de ezt az értéket a Face (dimenzió) attribútum Count paraméterének használatával növelheti vagy csökkentheti. Ez a példa a város aspektusait adja vissza, legfeljebb 5.

    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" ]  
        }  
    
  5. Keresés az indexben adott mezőkön belül (például egy nyelvi mező):

    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"
        }  
    
  6. Keresés az indexben több mező között. A kereshető mezőket például több nyelven is tárolhatja és lekérdezheti ugyanazon az indexen belül. Ha az angol és a francia nyelvű leírások közösen szerepelnek ugyanabban a dokumentumban, akkor a lekérdezés eredményeiben bármelyik vagy mindet visszaállíthatja:

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

    Egyszerre csak az indexet lehet lekérdezni. Ne hozzon létre több indexet az egyes nyelvekhez, hacsak nem tervezi egyszerre a lekérdezését.

  7. Lapozás – az elemek első oldalának beolvasása (az oldal mérete 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  
        }  
    
  8. Lapozás – az elemek második oldalának beolvasása (az oldal mérete 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  
        }  
    
  9. A mezők adott halmazának beolvasása:

    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"
        }  
    
  10. Adott szűrési kifejezésnek megfelelő dokumentumok beolvasása:

    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'"  
        }  
    
  11. Keresés az indexben és a töredékek visszaküldése a találati csúcsfényekkel:

    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"  
        }  
    
  12. Keresse meg az indexet, és küldje vissza a hivatkozásokat közelebbről távolabbra a hivatkozási helyekről:

    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)')"
        }  
    
  13. Keresse meg az indexet, feltételezve, hogy létezik egy "geo" nevű pontozási profil két távolsági pontozási függvénnyel, egy "currentLocation" nevű paramétert, és egy "lastLocation" nevű paramétert definiál:

    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" ]  
        }  
    
  14. Az indexben található dokumentumok keresése egyszerű lekérdezési szintaxis használatával. Ez a lekérdezés olyan szállodákat ad vissza, ahol a kereshető mezők tartalmazzák a "Comfort" és a "location", de nem "Motel" kifejezéseket:

    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 searchMode=all felülbírálja az alapértelmezett beállítást searchMode=any , ami azt jelenti, hogy a "és nem" helyett a "vagy nem" értéket kell használni -motel . Nélkül searchMode=all , a "vagy nem", amely kibontja a keresési eredmények korlátozását, és ez az egyes felhasználók számára intuitív lehet.

  15. A Lucene lekérdezési szintaxishasználatával megkeresheti az indexben lévő dokumentumokat. Ez a lekérdezés azokat a szálláshelyeket adja vissza, ahol a Kategória mező tartalmazza a "költségvetés" kifejezést, valamint az "újonnan felújított" kifejezést tartalmazó kereshető mezőket. A "nemrég felújított" kifejezést tartalmazó dokumentumok magasabbra vannak rangsorolva a "Boost Value" (3) kifejezés eredményeképpen

    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"  
    }  
    
  16. Keresse meg az indexben lévő dokumentumokat, miközben előnyben részesíti az alacsonyabb késéssel való konzisztens pontozást. Ez a lekérdezés a teljes indexben számítja ki a dokumentumok gyakoriságát, és a legjobb erőfeszítést tesz arra, hogy ugyanazt a replikát célozza meg az azonos "munkamenetben" lévő összes lekérdezés esetében, ami segít a stabil és reprodukálható rangsorolás létrehozásában.

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

Lásd még