Hledání dokumentů (rozhraní REST API služby Azure AI Search)

Článek
11/13/2023

Požadavek dotazu cílí na kolekci dokumentů jednoho indexu ve vyhledávací službě. Obsahuje parametry, které definují kritéria shody, a parametry, které formuje odpověď. Od verze rozhraní API 2021-04-30-Preview můžete také použít alias indexu k cílení na konkrétní index místo samotného názvu indexu.

Můžete použít GET nebo POST. Parametry dotazu jsou zadané v řetězci dotazu pro požadavky GET a v textu požadavku pro požadavky POST.

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

Pokud používáte POST, přidejte akci "search" jako parametr URI.

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]

Při volání pomocí get nesmí délka adresy URL požadavku překročit 8 kB. Tato délka je obvykle dostatečná pro většinu aplikací. Některé aplikace však vytvářejí velké dotazy, konkrétně při použití výrazů filtru OData. Pro tyto aplikace je lepší volbou HTTP POST, protože umožňuje větší filtry než GET.

U funkce POST je limitačním faktorem počet klauzulí ve filtru, nikoli velikost nezpracovaného řetězce filtru, protože limit velikosti požadavku pro POST je přibližně 16 MB. I když je limit velikosti požadavku POST velký, výrazy filtru nemůžou být libovolně složité. Další informace o omezeních složitosti filtrů najdete v tématu Syntaxe výrazů OData pro Azure AI Search.

Parametry identifikátoru URI

Parametr	Popis
[název služby]	Povinná hodnota. Nastavte ho na jedinečný uživatelsky definovaný název vaší vyhledávací služby.
[název indexu]/docs	Povinná hodnota. Určuje kolekci dokumentů pojmenovaného indexu.
[parametry dotazu]	Parametry dotazu jsou zadané v identifikátoru URI pro požadavky GET a v textu požadavku pro požadavky POST.
verze-api	Povinná hodnota. Aktuální stabilní verze je `api-version=2020-06-30`. Další verze najdete v tématu Verze rozhraní API . Pro dotazy je api-version vždy zadán jako parametr URI pro GET i POST.

Doporučení pro kódování adres URL

Při přímém volání rozhraní GET REST API nezapomeňte zakódovat konkrétní parametry dotazu pomocí adresy URL. Pro operaci Hledat dokumenty může být kódování adresy URL nezbytné pro následující parametry dotazu:

search
$filter
omezující vlastnost
highlightPreTag
highlightPostTag

Kódování adresy URL se doporučuje pouze pro jednotlivé parametry. Pokud nechtěně zakódujete celý řetězec dotazu pomocí adresy URL (vše po ?), požadavky se přeruší.

Kódování adresy URL je také nutné pouze při volání rozhraní REST API přímo pomocí příkazu GET. Při použití POST nebo klientské knihovny Azure AI Search .NET, která zajišťuje kódování za vás, není nutné kódovat adresu URL.

Hlavičky požadavku

Následující tabulka popisuje požadované a volitelné hlavičky požadavků.

Pole	Description
Typ obsahu	Povinná hodnota. Nastavte tuto možnost na application/json.
api-key	Volitelné, pokud používáte role Azure a v požadavku je k dispozici nosný token, jinak se vyžaduje klíč. Klíč api-key je jedinečný systémově vygenerovaný řetězec, který ověřuje požadavek pro vaši vyhledávací službu. Požadavky dotazů na kolekci dokumentů můžou jako klíč rozhraní API zadat klíč správce nebo klíč dotazu. Klíč dotazu se používá pro operace jen pro čtení s kolekcí dokumentů. Podrobnosti najdete v tématu Připojení ke službě Azure AI Search pomocí ověřování pomocí klíče .

Pole

Description

Typ obsahu

Povinná hodnota. Nastavte tuto možnost na application/json.

api-key

Volitelné, pokud používáte role Azure a v požadavku je k dispozici nosný token, jinak se vyžaduje klíč. Klíč api-key je jedinečný systémově vygenerovaný řetězec, který ověřuje požadavek pro vaši vyhledávací službu. Požadavky dotazů na kolekci dokumentů můžou jako klíč rozhraní API zadat klíč správce nebo klíč dotazu. Klíč dotazu se používá pro operace jen pro čtení s kolekcí dokumentů. Podrobnosti najdete v tématu Připojení ke službě Azure AI Search pomocí ověřování pomocí klíče .

Text požadavku

Pro GET: Žádné.

Pro 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": #  
   }

Pokračování částečných odpovědí hledání

Služba Azure AI Search někdy nemůže vrátit všechny požadované výsledky v jedné odpovědi hledání. K tomu může dojít z různých důvodů, například když dotaz vyžaduje příliš mnoho dokumentů tím, že nezadá $top nebo nezadá hodnotu, $top která je příliš velká. V takových případech Azure AI Search zahrne poznámku @odata.nextLink do textu odpovědi a také @search.nextPageParameters v případě, že se jednalo o požadavek POST. Pomocí hodnot těchto poznámek můžete formulovat další požadavek hledání, abyste získali další část odpovědi hledání. Tomu se říká pokračování původního požadavku hledání a poznámky se obecně označují jako tokeny pokračování. Podrobnosti o syntaxi těchto poznámek a jejich umístění v textu odpovědi najdete v následujícím příkladu v části Odpověď.

Důvody, proč služba Azure AI Search může vracet tokeny pokračování, jsou specifické pro implementaci a můžou se změnit. Robustní klienti by měli být vždy připraveni na zpracování případů, kdy se vrátí méně dokumentů, než se očekávalo, a je součástí tokenu pokračování, aby bylo možné pokračovat v načítání dokumentů. Mějte také na paměti, že pokud chcete pokračovat, musíte použít stejnou metodu HTTP jako původní požadavek. Pokud jste například odeslali požadavek GET, musí všechny odeslané žádosti o pokračování používat také funkci GET (a podobně i pro POST).

Poznámka

Účelem @odata.nextLink@search.nextPageParameters a je chránit službu před dotazy, které požadují příliš mnoho výsledků, nikoli poskytovat obecný mechanismus pro stránkování. Pokud chcete výsledky procházet stránkou, použijte $top a $skip společně. Pokud například chcete stránky o velikosti 10, první požadavek by měl mít $top=10 a $skip=0, druhý požadavek by měl mít $top=10 a $skip=10, třetí požadavek by měl mít $top=10 a $skip=20atd.

Parametry dotazu

Dotaz přijímá několik parametrů na adrese URL při volání pomocí příkazu GET a jako vlastnosti JSON v textu požadavku při volání pomocí POST. Syntaxe některých parametrů se mezi funkcemi GET a POST mírně liší. Tyto rozdíly jsou uvedené níže.

Název	Typ	Description
verze-api	řetězec	Povinná hodnota. Verze rozhraní REST API použitá pro požadavek Seznam podporovaných verzí najdete v tématu Verze rozhraní API. Pro tuto operaci se jako parametr identifikátoru URI zadává api-version bez ohledu na to, jestli voláte dokumenty hledání pomocí příkazu GET nebo POST.
`$count`	boolean	Nepovinný parametr. Platné hodnoty jsou true nebo false. Výchozí hodnota je false. Při zavolání pomocí funkce POST má tento parametr název count místo `$count`. Určuje, jestli se má načíst celkový počet výsledků. Jedná se o počet všech dokumentů, které odpovídají parametrům hledání a $filter, přičemž se ignorují `$top` parametry a `$skip`. Nastavení této hodnoty na true může snížit výkon. Počet je přesný, pokud je index stabilní, ale bude pod nebo přepočítává všechny dokumenty, které jsou aktivně přidány, aktualizovány nebo odstraněny. Pokud chcete získat jenom počet bez dokumentů, můžete použít `$top`=0.
fasety nebo fasety	řetězec	Nepovinný parametr. Pole, podle kterého se má použít faset, kde je pole přiřazeno jako "facetable". Při zavolání pomocí funkce GET `facet` se jedná o pole (`facet: field1`). Při zavolání pomocí POST je tento parametr pojmenován `facets` místo `facet` a je zadaný jako pole (`facets: [field1, field2, field3]`). Řetězec může obsahovat parametry pro přizpůsobení fazety vyjádřené jako dvojice název-hodnota oddělené čárkami. Platné parametry jsou "count", "sort", "values", "interval" a "timeoffset". "count" je maximální počet omezujících výrazů; výchozí hodnota je 10. Neexistuje žádný horní limit počtu termínů, ale vyšší hodnoty sníží výkon, zejména pokud pole s omezujícími vlastnostmi obsahuje velký počet jedinečných termínů. Například "facet=category,count:5" získá prvních pět kategorií ve výsledcích omezující vlastnosti. Pokud je parametr count menší než počet jedinečných termínů, nemusí být výsledky přesné. Důvodem je způsob distribuce dotazů s omezujícími tvářemi napříč horizontálními oddíly. Počet můžete nastavit na nulu nebo na hodnotu, která je větší nebo rovna počtu jedinečných hodnot v poli facetable, abyste získali přesný počet napříč všemi horizontálními oddíly. Kompromisem je zvýšená latence. "sort" lze nastavit na "count", "-count", "value", "-value". Pomocí funkce Count můžete seřadit sestupně podle počtu. Pokud chcete seřadit vzestupně podle počtu, použijte -count. Použijte hodnotu k seřazení vzestupně podle hodnoty. Pomocí parametru -value seřadíte sestupně podle hodnoty (například "facet=category,count:3;sort:count" získá první tři kategorie ve výsledcích omezující vlastnosti v sestupném pořadí podle počtu dokumentů s názvem každého města). Pokud jsou první tři kategorie Rozpočet, Motel a Luxus a Rozpočet má 5 hitů, Motel má 6 a Luxury má 4, pak jsou kbelíky v pořadí Motel, Budget, Luxury. Pro hodnotu -value vytvoří "facet=rating,sort:-value" kontejnery pro všechna možná hodnocení v sestupném pořadí podle hodnoty (například pokud jsou hodnocení od 1 do 5, jsou kontejnery seřazeny 5, 4, 3, 2, 1 bez ohledu na to, kolik dokumentů odpovídá jednotlivým hodnocením). "values" lze nastavit na číselné hodnoty oddělené kanály nebo hodnoty Edm.DateTimeOffset určující dynamickou sadu vstupních hodnot omezující vlastnosti (například "facet=baseRate,values:10 \| 20" vytvoří tři kbelíky: jeden pro základní sazbu 0 do 10, jeden pro 10 až 20, ale nezahrnuje 20 a jeden pro 20 a vyšší). Řetězec facet=lastRenovationDate,values:2010-02-01T00:00:00Z vytvoří dva kbelíky: jeden pro hotely rekonstruované před únorem 2010 a druhý pro hotely rekonstruované 1. února 2010 nebo novější. Hodnoty musí být uvedeny v sekvenčním vzestupném pořadí, aby se získaly očekávané výsledky. "interval" je celočíselný interval větší než 0 pro čísla nebo minuta, hodina, den, týden, měsíc, čtvrtletí a rok pro hodnoty data a času. Například "facet=baseRate,interval:100" vytvoří kontejnery založené na rozsahech základní sazby o velikosti 100. Pokud jsou základní sazby všechny mezi 60 a 600 USD, budou existovat kontejnery pro 0-100, 100-200, 200-300, 300-400, 400-500 a 500-600. Řetězec "facet=lastRenovationDate,interval:year" vytvoří jeden kbelík pro každý rok, kdy byly hotely renovovány. "timeoffset" lze nastavit na ([+-]hh:mm, [+-]hhmm nebo [+-]hh). Pokud je použit parametr timeoffset, musí být kombinován s možností intervalu a pouze při použití u pole typu Edm.DateTimeOffset. Hodnota určuje časový posun UTC, který se má zohlednit při nastavení časových hranic. Příklad: "facet=lastRenovationDate,interval:den,timeoffset:-01:00" používá hranici dne, která začíná v 01:00:00 UTC (půlnoc v cílovém časovém pásmu). funkce count a sort se dají kombinovat ve stejné specifikaci omezující vlastnosti, ale nedají se kombinovat s intervalem nebo hodnotami a interval a hodnoty se nedají kombinovat dohromady. Fasety intervalu pro datum a čas se počítají na základě času UTC, pokud není zadána sada časových omezení. Příklad: pro "facet=lastRenovationDate,interval:den" začíná hranice dne v 00:00:00 UTC.
$filter	řetězec	Nepovinný parametr. Strukturovaný vyhledávací výraz ve standardní syntaxi OData. Ve filtru lze použít pouze filtrovatelná pole. Při volání s post má tento parametr název filter místo $filter. Podrobnosti o podmnožině gramatiky výrazu OData, kterou azure AI Search podporuje, najdete v tématu Syntaxe výrazů OData pro Azure AI Search.
Zvýraznit	řetězec	Nepovinný parametr. Sada názvů polí oddělených čárkami, které se používají pro zvýraznění přístupů. Ke zvýraznění přístupů je možné použít pouze prohledávatelná pole. Ve výchozím nastavení azure AI Search vrátí až 5 zvýraznění na jedno pole. Limit je možné konfigurovat pro jednotlivá pole tak, že za název pole přidáte "-max# of highlights" (-<max# of highlights>). Například výraz "highlight=title-3,description-10" vrátí až 3 zvýrazněné přístupy z pole nadpisu a až 10 přístupů z pole popis. Maximální počet zvýraznění musí být celé číslo mezi 1 a 1 000 včetně.
highlightPostTag	řetězec	Nepovinný parametr. Výchozí hodnota je `"</em>"`. Značka řetězce, která se připojí ke zvýrazněnýmu termínu. Musí být nastaven pomocí highlightPreTag. Rezervované znaky v adrese URL musí být zakódované v procentech (například %23 místo #).
highlightPreTag	řetězec	Nepovinný parametr. Výchozí hodnota je `"</em>"`. Značka řetězce, která se předeznamuje zvýrazněným termínem. Musí být nastaven pomocí highlightPostTag. Rezervované znaky v adrese URL musí být zakódované v procentech (například %23 místo #).
minimumCoverage	integer	Nepovinný parametr. Platné hodnoty jsou číslo od 0 do 100, což označuje procento indexu, které musí být k dispozici pro obsluhu dotazu, aby bylo možné hlásit úspěch. Výchozí hodnota je 100. Stoprocentní pokrytí znamená, že všechny horizontální oddíly odpověděly na požadavek (ani problémy se stavem služby ani aktivity údržby nesnížovaly pokrytí). Ve výchozím nastavení vrátí stavový kód HTTP 503 menší než úplné pokrytí. Snížení minimumCoverage může být užitečné, pokud dochází k chybám 503 a chcete zvýšit pravděpodobnost úspěchu dotazu, zejména u služeb, které jsou nakonfigurované pro jednu repliku. Pokud nastavíte minimumCoverage a hledání proběhne úspěšně, vrátí http 200 a zahrne @search.coverage do odpovědi hodnotu označující procento indexu, který byl zahrnut do dotazu. V tomto scénáři není zaručeno, že se ve výsledcích hledání budou vyskytovat všechny odpovídající dokumenty, ale pokud je dostupnost hledání důležitější než úplnost, pak snížení pokrytí může být životaschopnou strategií pro zmírnění rizik.
$orderby	řetězec	Nepovinný parametr. Seznam výrazů oddělených čárkami, podle které se mají výsledky seřadit. Při zavolání pomocí POST se tento parametr nazývá orderby místo $orderby. Každý výraz může být buď názvem pole, nebo voláním funkce geo.distance(). Za každým výrazem může následovat "asc" označující vzestupné a "desc" označující sestupně. Pokud jsou v poli řazení hodnoty null, zobrazí se hodnoty null jako první vzestupně a poslední v sestupném pořadí. Výchozí hodnota je vzestupné pořadí. Vazby budou přerušeny skóre shody dokumentů. Pokud není zadána žádná $orderby, výchozí pořadí řazení je sestupné podle skóre shody dokumentu. Pro $orderby platí limit 32 klauzulí.
queryType	řetězec	Nepovinný parametr. Platné hodnoty jsou "simple" nebo "full". Výchozí hodnota je "simple". "simple" interpretuje řetězce dotazů pomocí jednoduché syntaxe dotazu , která umožňuje symboly, jako `+`jsou , `*` a `""`. Dotazy se ve výchozím nastavení vyhodnocují ve všech prohledávatelných polích (nebo polích označených v vyhledávacích polích) v každém dokumentu. "full" interpretuje řetězce dotazů pomocí úplné syntaxe dotazu Lucene , která umožňuje vyhledávání podle polí a vážené vyhledávání. Vyhledávání v rozsahu v dotazovacím jazyce Lucene se nepodporuje ve prospěch $filter, která nabízí podobné funkce.
bodováníParameter	řetězec	Nepovinný parametr. Určuje hodnoty pro každý parametr definovaný v bodovací funkci (například referencePointParameter) ve formátu name-value1,value2,.... Při zavolání pomocí POST má tento parametr název scoringParameters místo scoringParameter. Zadáte ho také jako pole JSON řetězců, kde každý řetězec je samostatnou dvojicí název-hodnota. U profilů bodování, které obsahují funkci, oddělte funkci od jejího vstupního seznamu znakem `-` . Například funkce s názvem `"mylocation"` "&scoringParameter=mylocation--122.2;44.8". První pomlčka odděluje název funkce od seznamu hodnot, zatímco druhá pomlčka je součástí první hodnoty (v tomto příkladu zeměpisná délka). U hodnoticích parametrů, jako je například zvýšení značek, které mohou obsahovat čárky, můžete všechny takové hodnoty v seznamu uvozovat pomocí jednoduchých uvozovek. Pokud samotné hodnoty obsahují jednoduché uvozovky, můžete je uvozovat zdvojnásobováním. Předpokládejme, že máte parametr zvýšení hodnoty značky s názvem `"mytag"` a chcete zvýšit hodnoty značek "Hello, O'Brien" a "Smith", možnost řetězce dotazu by pak byla "&scoringParameter=mytag-'Hello, O'Brien',Smith". Uvozovky jsou povinné pouze pro hodnoty, které obsahují čárky.
scoringProfile	řetězec	Nepovinný parametr. Název profilu bodování, který má vyhodnotit skóre shody pro odpovídající dokumenty, aby bylo možné výsledky seřadit.
scoringStatistics	řetězec	Nepovinný parametr. Platné hodnoty jsou "local" nebo "global". Výchozí hodnota je "local". Určete, jestli se mají vypočítat statistiky bodování, jako je četnost dokumentů, globálně (napříč všemi horizontálními oddíly) pro zajištění konzistentnějšího vyhodnocování, nebo místně (v aktuálním horizontálním oddílu) pro snížení latence. Viz Statistika bodování ve službě Azure AI Search. Statistika bodování se vždy vypočítá místně pro termíny, které používají přibližné vyhledávání (~).
search	řetězec	Nepovinný parametr. Text, který chcete vyhledat. Všechna prohledávatelná pole se ve výchozím nastavení prohledávají, pokud není zadána pole searchFields. V indexu je text v prohledávatelných polích tokenizován, takže více termínů může být odděleno prázdnými znaky (například: 'search=hello world'). Pokud chcete shodovat s libovolným termínem, použijte `` (to může být užitečné pro dotazy logických filtrů). Vynechání tohoto parametru má stejný účinek jako jeho nastavení na ``hodnotu . Podrobnosti o syntaxi vyhledávání najdete v části Jednoduchá syntaxe dotazu . Výsledky můžou být při dotazování na prohledávatelná pole někdy překvapivé. Tokenizátor obsahuje logiku pro zpracování případů běžných pro anglický text, jako jsou apostrofy, čárky v číslech atd. Například "search=123,456" bude odpovídat jednomu výrazu "123 456" místo jednotlivých termínů "123" a "456", protože čárky se používají jako oddělovače tisíců pro velká čísla v angličtině. Z tohoto důvodu doporučujeme místo interpunkce použít prázdné znaky k oddělení termínů ve vyhledávacím parametru.
searchMode	řetězec	Nepovinný parametr. Platné hodnoty jsou "any" nebo "all" Výchozí hodnoty jsou "any". Určuje, zda musí být některé nebo všechny hledané termíny shodné, aby bylo možné dokument spočítat jako shodu.
searchFields	řetězec	Nepovinný parametr. Seznam názvů polí oddělených čárkami pro vyhledání zadaného textu. Cílová pole musí být ve schématu indexu označená jako prohledávatelná.
$select	řetězec	Nepovinný parametr. Seznam polí oddělených čárkami, která se mají zahrnout do sady výsledků. Do této klauzule lze zahrnout pouze pole označená jako získatelná. Pokud není zadáno nebo nastaveno na `*`hodnotu , všechna pole označená jako načístelná ve schématu se zahrnou do projekce. Při zavolání pomocí POST má tento parametr místo $select název select.
Sessionid	řetězec	Nepovinný parametr. Použití sessionId pomáhá zlepšit konzistenci skóre relevance pro vyhledávací služby s více replikami. V konfiguracích s více replikami můžou existovat mírné rozdíly mezi skóre relevance jednotlivých dokumentů pro stejný dotaz. Když je zadané ID relace, služba se co nejlépe snaží směrovat daný požadavek na stejnou repliku pro danou relaci. Buďte opatrní, že opakované opakované použití stejných hodnot ID relace může narušit vyrovnávání zatížení požadavků napříč replikami a nepříznivě ovlivnit výkon vyhledávací služby. Hodnota použitá jako sessionId nemůže začínat znakem _. Pokud služba nemá žádné repliky, nemá tento parametr žádný vliv na výkon ani konzistenci skóre.
$skip	integer	Nepovinný parametr. Počet výsledků hledání, které se mají přeskočit. Při zavolání pomocí příkazu POST má tento parametr název skip místo `$skip`. Tato hodnota nesmí být větší než 100 000. Pokud potřebujete skenovat dokumenty postupně, ale nemůžete je kvůli tomuto omezení použít `$skip` , zvažte použití $orderby na pole, které má jedinečné hodnoty pro každý dokument v indexu (například klíč dokumentu) a $filter místo toho s dotazem na rozsah.
$top	integer	Nepovinný parametr. Počet výsledků hledání, které se mají načíst. Výchozí hodnota je 50. Při zavolání pomocí post se tento parametr jmenuje top místo `$top`. Pokud zadáte hodnotu větší než 1000 a existuje více než 1 000 výsledků, vrátí se pouze prvních 1 000 výsledků spolu s odkazem na další stránku výsledků (viz @odata.nextLink následující příklad). Azure AI Search používá stránkování na straně serveru , aby dotazy najednou načítá příliš mnoho dokumentů. Výchozí velikost stránky je 50, zatímco maximální velikost stránky je 1000. To znamená, že ve výchozím nastavení vrátí funkce Hledat v dokumentech maximálně 50 výsledků, pokud nezadáte `$top`. Pokud existuje více než 50 výsledků, odpověď obsahuje informace pro načtení další stránky s maximálně 50 výsledky (viz "@odata.nextLink" a "@search.nextPageParameters" v následujících příkladech . Podobně pokud zadáte hodnotu větší než 1000 pro `$top` a existuje více než 1 000 výsledků, vrátí se pouze prvních 1000 výsledků spolu s informacemi o načtení další stránky maximálně 1 000 výsledků.

Odpověď

Stavový kód: Pro úspěšnou odpověď se vrátí hodnota 200 OK.

  {
    "@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říklady

Další příklady najdete v tématu Syntaxe výrazů OData pro Azure AI Search.

Prohledejte index seřazený sestupně podle data:

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

Při fasetovém hledání prohledávejte index a načítejte omezující vlastnosti kategorií, hodnocení, značek a položek s baseRate v konkrétních rozsahech.
```
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" ]  
    }  
```
Všimněte si, že poslední omezující vlastnost je na dílčím poli. Omezující vlastnosti počítají nadřazený dokument (Hotely) a ne zprostředkující vnořené dokumenty (Pokoje), takže odpověď určuje počet hotelů, které mají v každém cenovém kbelíku libovolné místnosti.

Pomocí filtru zúžíte výsledek předchozího fasetového dotazu poté, co uživatel vybere Hodnocení 3 a kategorii Motel.

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

Při fasetovém hledání nastavte horní limit jedinečných termínů vrácených v dotazu. Výchozí hodnota je 10, ale tuto hodnotu můžete zvýšit nebo snížit pomocí parametru count v atributu omezující vlastnosti. Tento příklad vrátí omezující vlastnosti pro město omezené na 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" ]  
    }  
```

Prohledejte index v konkrétních polích (například v poli jazyka):

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

Prohledávejte index ve více polích. Můžete například ukládat a dotazovat prohledávatelná pole ve více jazycích, a to vše v rámci stejného indexu. Pokud ve stejném dokumentu společně existují anglické a francouzské popisy, můžete ve výsledcích dotazu vrátit libovolný nebo všechny:
```
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"
    }  
```
Dotazovat se můžete jenom na index najednou. Nevytvovávejte více indexů pro každý jazyk, pokud neplánujete dotazovat jeden po druhém.

Stránkování – získání první stránky položek (velikost stránky je 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  
    }

Stránkování – získání druhé stránky položek (velikost stránky je 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  
    }

Načtení konkrétní sady polí:

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

Načtení dokumentů odpovídajících konkrétnímu výrazu filtru:

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

Prohledejte index a vracejte fragmenty se zvýrazněnými výsledky:

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

Prohledejte index a vracejte dokumenty seřazené od bližšího po vzdálenější od referenčního umístění:

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

Prohledejte index za předpokladu, že existuje bodovací profil s názvem "geo" se dvěma funkcemi bodování vzdálenosti, jedna definující parametr s názvem "currentLocation" a druhá definující parametr s názvem "lastLocation". V následujícím příkladu má "currentLocation" oddělovač jedné pomlčky (-). Následuje souřadnice zeměpisné délky a šířky, kde zeměpisná délka je záporná hodnota.

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

Dokumenty v indexu můžete najít pomocí jednoduché syntaxe dotazu. Tento dotaz vrátí hotely, ve kterých prohledávatelná pole obsahují termíny "comfort" a "location", ale ne "motel":
```
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"  
    }  
```
Tip

Použití nástroje searchMode=all přepíše výchozí hodnotu searchMode=any, což -motel znamená "A NE" místo "NEBO NE". Bez searchMode=allpříkazu se zobrazí text "NEBO NE", který rozšiřuje místo omezení výsledků hledání, což může být pro některé uživatele neintuitivní.
Najděte dokumenty v indexu pomocí syntaxe dotazu Lucene). Tento dotaz vrátí hotely, ve kterých pole kategorie obsahuje termín "rozpočet" a všechna prohledávatelná pole obsahující frázi "nedávno zrekonstruované". Dokumenty obsahující frázi "nedávno renovované" jsou seřazeny výš v důsledku výrazu boost value (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"  
}  
```
Vyhledejte dokumenty v indexu a upřednostňujte konzistentní bodování před nižší latencí. Tento dotaz vypočítá četnost dokumentů v celém indexu a vynačuje maximální úsilí o cílení na stejnou repliku pro všechny dotazy v rámci stejné "relace", což pomáhá generovat stabilní a reprodukovatelné pořadí.
```
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"
    }  
```

Sdílet prostřednictvím