Návrhy (rozhraní REST API služby Azure AI Search)
Žádost Návrhy je vyhledávací dotaz, který hledá odpovídající hodnoty v polích s návrhem a vrací dokumenty, které obsahují shodu. Pokud například povolíte návrhy pro pole města , zadáním "moře" se vytvoří dokumenty obsahující "Seattle", "Sea Tac" a "Seaside" (všechny skutečné názvy měst) pro toto pole.
Odpověď je obsah z odpovídajícího dokumentu plus klíč dokumentu. Na rozdíl od funkce Automatické dokončování, která vrací dokončený termín nebo frázi použitou v sekundárním dotazu, tento požadavek vrátí informace, které se přeloží na skutečné dokumenty. Pokud jsou shodná slova nebo fráze v různých dokumentech identické, odpovídající obsah se opakuje. Pokud chcete zlepšit strukturu výsledků, zvažte použití $select filtru k vrácení dalších polí, která poskytují větší rozlišení a kontext.
Pro žádosti o služby se vyžaduje https. Požadavek Suggest lze vytvořit pomocí metod GET nebo POST.
GET https://[service name].search.windows.net/indexes/[index name]/docs/suggest?[query parameters]
Content-Type: application/json
api-key: [admin or query key]
POST https://[service name].search.windows.net/indexes/[index name]/docs/suggest?api-version=[api-version]
Content-Type: application/json
api-key: [admin or query key]
Na rozdíl od požadavku Hledat v dokumentech můžete vytvořit vazbu volání Návrhy na zadávání pomocí klávesnice, zatímco volání hledání může být svázané s událostí kliknutí.
Při volání pomocí příkazu 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í velmi 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 velmi velký, výrazy filtru nemohou 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. |
| 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. U operací Návrhy to zahrnuje:
- search
- $filter
- 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 volání návrhů pomocí POST nebo při použití klientské knihovny Azure AI Search .NET , která zpracovává kódování url 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 . |
Text požadavku
Pro GET: Žádné.
Pro POST:
{
"filter": "odata_filter_expression",
"fuzzy": true | false (default),
"highlightPreTag": "pre_tag",
"highlightPostTag": "post_tag",
"minimumCoverage": # (% of index that must be covered to declare query successful; default 80),
"orderby": "orderby_expression",
"search": "partial_search_input",
"searchFields": "field_name_1, field_name_2, ...",
"select": "field_name_1, field_name_2, ...",
"suggesterName": "suggester_name",
"top": # (default 5)
}
Parametry dotazů
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 dotazu v adrese URL zadává api-version bez ohledu na to, jestli voláte rozhraní API pomocí příkazu GET nebo POST. |
| $filter | řetězec | Nepovinný parametr. Výraz, který filtruje dokumenty, které se považují za návrhy. Ve filtru lze použít pouze filtrovatelná pole. Rozhraní API automatického dokončování nepodporuje výrazy filtru search.ismatchscoring a search.ismatchscoring*. Při zavolá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. |
| Fuzzy | boolean | Nepovinný parametr. Výchozí hodnota je false. Pokud je nastavená hodnota true, toto rozhraní API najde návrhy i v případě, že ve hledaném textu chybí nebo je nahrazovaný znak. Délka úprav je 1 na řetězec dotazu. Pokud je řetězcem dotazu více termínů, může v celém řetězci chybět pouze jeden znak, navíc, nahrazený nebo transponovaný znak. Povolení přibližné shody může být v některých scénářích lepším prostředím, ale má náklady na výkon, protože vyhledávání přibližných návrhů je pomalejší a spotřebovávají více prostředků. |
| highlightPostTag | řetězec | Nepovinný parametr. Výchozí hodnota je prázdný řetězec. 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 #). Při volání pomocí funkce GET musí být rezervované znaky v adrese URL zakódované v procentech (například %23 místo #). |
| highlightPreTag | řetězec | Nepovinný parametr. Výchozí hodnota je prázdný řetězec. Značka řetězce, která se předeznamuje zvýrazněným termínem. Musí být nastaven pomocí highlightPostTag. Při volání pomocí funkce GET musí být rezervované znaky v adrese URL zakódované v procentech (například %23 místo #). |
| $orderby | řetězec | Nepovinný parametr. Seznam výrazů oddělených čárkami, podle které se mají výsledky seřadit. Každý výraz může být buď názvem pole, nebo voláním geo.distance() funkce. Za každým výrazem může následovat "asc" (vzestupně) nebo "desc" (sestupně). Výchozí hodnota je vzestupné pořadí. Pro $orderby platí omezení 32 klauzulí. Při zavolání pomocí POST se tento parametr nazývá order místo $orderby. |
| minimumCoverage | integer | Nepovinný parametr. Výchozí hodnota je 80. Číslo mezi 0 a 100 označující procento indexu, které musí být k dispozici pro obsluhu dotazu, aby bylo možné hlásit úspěch.
Výchozí hodnota odráží sklon k rychlosti a efektivitě oproti plnému pokrytí. Omezení pokrytí omezuje rozšíření dotazů, což umožňuje rychlejší vrácení výsledků. Umožňuje také úspěšně provést dotaz při částečné dostupnosti indexu, a to i v případě, že jeden horizontální oddíl reaguje pomalu nebo není k dispozici kvůli problémům se stavem služby nebo údržbě indexu. Bez ohledu na hodnotu minimumCoverage musí být toto procento indexu k dispozici nebo návrhy vrátí stavový kód HTTP 503. Pokud návrhy uspěje na úrovni minimumCoverage, vrátí http 200 a do odpovědi zahrne @search.coverage hodnotu označující procento indexu, které bylo k dispozici při údržbě dotazu. Snížení této hodnoty může být užitečné, pokud dochází k chybám 503. V opačném případě můžete zvážit zvýšení hodnoty, pokud odpověď neposkytuje dostatečné shody. |
| search | řetězec | Povinná hodnota. Hledaný text, který se má použít k navrhování dotazů. Musí mít alespoň 1 znak a nesmí být delší než 100 znaků. Nemůže obsahovat operátory, syntaxi dotazu ani uvozované fráze. |
| searchFields | řetězec | Nepovinný parametr. Seznam názvů polí oddělených čárkami pro vyhledání zadaného hledaného textu. Cílová pole musí být uvedená v definici Návrhy v indexu. |
| $select | řetězec | Nepovinný parametr. Seznam polí oddělených čárkami, která se mají načíst. Pokud není zadáno, vrátí se pouze klíč dokumentu a text návrhu. Nastavením tohoto parametru na *hodnotu můžete explicitně požádat o všechna pole. Při volání s post má tento parametr název select místo $select. |
| suggesterName | řetězec | Povinná hodnota. Název návrhu zadaný v kolekci Návrhy, která je součástí definice indexu. Předpona určuje, která pole se kontrolují pro navrhované termíny dotazu. |
| $top | integer | Nepovinný parametr. Výchozí hodnota je 5). Počet automaticky dokončovaných návrhů, které se mají načíst. Hodnota musí být číslo mezi 1 a 100. Při volání pomocí post se tento parametr jmenuje top místo $top. |
Odpověď
Pro úspěšnou odpověď se vrátí stavový kód 200 OK.
{
"@search.coverage": # (if minimumCoverage was provided in the query),
"value": [
{
"@search.text": "...",
"<key field>": "..."
},
...
]
}
Pokud se k načtení polí použije možnost projekce, jsou zahrnuta v každém prvku pole:
{
"value": [
{
"@search.text": "...",
"<key field>": "..."
<other projected data fields>
},
...
]
}
Příklady
Načtěte 5 návrhů, ve kterých je částečný vstup hledání "lux":
GET /indexes/hotels/docs/suggest?search=lux&$top=5&suggesterName=sg&api-version=2020-06-30
POST /indexes/hotels/docs/suggest?api-version=2020-06-30
{
"search": "lux",
"top": 5,
"suggesterName": "sg"
}
Všimněte si, že v operaci Návrhy se vyžaduje názevseznamu .