Documents - Suggest Post

Služba:: Search Service

Verze rozhraní API:: 2026-08-01-preview

Navrhne dokumenty v indexu, které odpovídají danému částečnému textu dotazu.

POST {endpoint}/indexes('{indexName}')/docs/search.post.suggest?api-version=2026-08-01-preview

Parametry identifikátoru URI

Name	V	Vyžadováno	Typ	Description
endpoint	path	True	string (uri)	Adresa URL koncového bodu vyhledávací služby.
indexName	path	True	string	Název indexu.
api-version	query	True	string minLength: 1	Verze rozhraní API, která se má použít pro tuto operaci.

Hlavička požadavku

Name	Vyžadováno	Typ	Description
Accept		Accept	Hlavička Accept.
x-ms-client-request-id		string (uuid)	Neprůzrný globálně jedinečný identifikátor řetězce vygenerovaný klientem pro požadavek.

Text požadavku

Name	Vyžadováno	Typ	Description
search	True	string	Hledaný text, který se má použít k návrhu dokumentů. Musí mít alespoň 1 znak a nesmí být delší než 100 znaků.
suggesterName	True	string	Název navrhujícího, jak je uvedeno v kolekci pro návrhy, která je součástí definice indexu.
filter		string	Výraz OData, který filtruje dokumenty zvažované pro návrhy.
fuzzy		boolean	Hodnota označující, zda se má pro dotaz návrhu použít přibližná shoda. Výchozí hodnota je nastavená na false. Pokud je nastavená hodnota true, dotaz najde návrhy i v případě, že ve vyhledávaném textu je nahrazený nebo chybějící znak. I když to v některých scénářích poskytuje lepší prostředí, je to za cenu nákladů na výkon, protože vyhledávání přibližných návrhů je pomalejší a spotřebovává více prostředků.
highlightPostTag		string	Značka řetězce, která se připojí k zvýraznění. Je nutné nastavit zvýrazněníPreTag. Pokud je vynechán, zvýraznění návrhů je zakázáno.
highlightPreTag		string	Značka řetězce, která je předem zvýrazněná. Musí být nastavena značka highlightPostTag. Pokud je vynechán, zvýraznění návrhů je zakázáno.
minimumCoverage		number (double)	Číslo mezi 0 a 100 označující procento indexu, které musí být pokryto dotazem na návrh, aby byl dotaz hlášen jako úspěšný. Tento parametr může být užitečný pro zajištění dostupnosti vyhledávání i pro služby s jedinou replikou. Výchozí hodnota je 80.
orderby		string	Seznam OData oddělených čárkami $orderby výrazy, podle kterých se mají výsledky seřadit. Každý výraz může být buď název pole, nebo volání funkce geo.distance() nebo search.score(). Za každým výrazem může následovat asc, který označuje vzestupně, nebo desc označují sestupně. Výchozí hodnota je vzestupné pořadí. Vazby budou přerušeny skóre shody dokumentů. Pokud není zadán žádný $orderby, výchozí pořadí řazení je sestupné podle skóre shody dokumentu. Může existovat maximálně 32 $orderby klauzulí.
searchFields		string	Seznam názvů polí oddělených čárkami pro vyhledání zadaného hledaného textu. Cílová pole musí být zahrnuta v určeném modulu pro návrhy.
select		string	Seznam polí oddělených čárkami, která se mají načíst. Pokud není zadáno, bude do výsledků zahrnuto pouze klíčové pole.
top		integer (int32)	Počet návrhů k načtení. Musí to být hodnota mezi 1 a 100. Výchozí hodnota je 5.

Odpovědi

Name	Typ	Description
200 OK	SuggestDocumentsResult	Požadavek byl úspěšný.
Other Status Codes	ErrorResponse	Neočekávaná chybová odpověď

Zabezpečení

api-key

Typ: apiKey
V: header

OAuth2Auth

Typ: oauth2
Tok: implicit
URL autorizace: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Rozsahy

Name	Description
https://search.azure.com/.default

Příklady

SearchIndexSuggestDocumentsPost

Ukázkový požadavek

HTTP

POST https://typespecpreviewexampleservice.search.windows.net/indexes('preview-test')/docs/search.post.suggest?api-version=2026-08-01-preview



{
  "search": "p",
  "suggesterName": "sg",
  "filter": "ownerId eq 'sam' and id lt '15'",
  "fuzzy": true,
  "highlightPostTag": "</em>",
  "highlightPreTag": "<em>",
  "minimumCoverage": 80,
  "orderby": "id desc",
  "searchFields": "category",
  "select": "id,name,category,ownerId",
  "top": 10
}

Ukázková odpověď

Stavový kód:: 200

{
  "@search.coverage": 100,
  "value": [
    {
      "@search.text": "<em>pu</em>rple",
      "id": "14",
      "name": "test",
      "category": "purple",
      "ownerId": "sam"
    },
    {
      "@search.text": "<em>pu</em>rple",
      "id": "13",
      "name": "test",
      "category": "purple",
      "ownerId": "sam"
    },
    {
      "@search.text": "<em>pu</em>rple",
      "id": "11",
      "name": "test",
      "category": "purple",
      "ownerId": "sam"
    },
    {
      "@search.text": "<em>pu</em>rple",
      "id": "1",
      "name": "test",
      "category": "purple",
      "ownerId": "sam"
    }
  ]
}

Definice

Name	Description
Accept	Hlavička Accept.
ErrorAdditionalInfo	Další informace o chybě při správě prostředků
ErrorDetail	Podrobnosti o chybě.
ErrorResponse	Běžná chybová odpověď pro všechna rozhraní API Azure Resource Manageru pro vrácení podrobností o chybě pro neúspěšné operace (To se také řídí formátem odpovědi na chybu OData.)
SuggestDocumentsResult	Odpověď obsahující výsledky návrhového dotazu z indexu
SuggestRequest	Parametry pro filtrování, řazení, přibližné porovnávání a další návrhy chování dotazů.
SuggestResult	Výsledek obsahující dokument nalezený dotazem návrhu a přidruženými metadaty.

Accept

Výčet

Hlavička Accept.

Hodnota	Description
application/json;odata.metadata=none

ErrorAdditionalInfo

Objekt

Další informace o chybě při správě prostředků

Name	Typ	Description
info		Další informace.
type	string	Další typ informací.

ErrorDetail

Objekt

Podrobnosti o chybě.

Name	Typ	Description
additionalInfo	ErrorAdditionalInfo[]	Další informace o chybě.
code	string	Kód chyby.
details	ErrorDetail[]	Podrobnosti o chybě.
message	string	Chybová zpráva.
target	string	Cíl chyby.

ErrorResponse

Objekt

Běžná chybová odpověď pro všechna rozhraní API Azure Resource Manageru pro vrácení podrobností o chybě pro neúspěšné operace (To se také řídí formátem odpovědi na chybu OData.)

Name	Typ	Description
error	ErrorDetail	Objekt chyby.

SuggestDocumentsResult

Objekt

Odpověď obsahující výsledky návrhového dotazu z indexu

Name	Typ	Description
@search.coverage	number (double)	Hodnota označující procento indexu, který byl zahrnut do dotazu, nebo null, pokud v požadavku nebylo nastaveno minimumCoverage.
value	SuggestResult[]	Posloupnost výsledků vrácených dotazem.

SuggestRequest

Objekt

Parametry pro filtrování, řazení, přibližné porovnávání a další návrhy chování dotazů.

Name	Typ	Description
filter	string	Výraz OData, který filtruje dokumenty zvažované pro návrhy.
fuzzy	boolean	Hodnota označující, zda se má pro dotaz návrhu použít přibližná shoda. Výchozí hodnota je nastavená na false. Pokud je nastavená hodnota true, dotaz najde návrhy i v případě, že ve vyhledávaném textu je nahrazený nebo chybějící znak. I když to v některých scénářích poskytuje lepší prostředí, je to za cenu nákladů na výkon, protože vyhledávání přibližných návrhů je pomalejší a spotřebovává více prostředků.
highlightPostTag	string	Značka řetězce, která se připojí k zvýraznění. Je nutné nastavit zvýrazněníPreTag. Pokud je vynechán, zvýraznění návrhů je zakázáno.
highlightPreTag	string	Značka řetězce, která je předem zvýrazněná. Musí být nastavena značka highlightPostTag. Pokud je vynechán, zvýraznění návrhů je zakázáno.
minimumCoverage	number (double)	Číslo mezi 0 a 100 označující procento indexu, které musí být pokryto dotazem na návrh, aby byl dotaz hlášen jako úspěšný. Tento parametr může být užitečný pro zajištění dostupnosti vyhledávání i pro služby s jedinou replikou. Výchozí hodnota je 80.
orderby	string	Seznam OData oddělených čárkami $orderby výrazy, podle kterých se mají výsledky seřadit. Každý výraz může být buď název pole, nebo volání funkce geo.distance() nebo search.score(). Za každým výrazem může následovat asc, který označuje vzestupně, nebo desc označují sestupně. Výchozí hodnota je vzestupné pořadí. Vazby budou přerušeny skóre shody dokumentů. Pokud není zadán žádný $orderby, výchozí pořadí řazení je sestupné podle skóre shody dokumentu. Může existovat maximálně 32 $orderby klauzulí.
search	string	Hledaný text, který se má použít k návrhu dokumentů. Musí mít alespoň 1 znak a nesmí být delší než 100 znaků.
searchFields	string	Seznam názvů polí oddělených čárkami pro vyhledání zadaného hledaného textu. Cílová pole musí být zahrnuta v určeném modulu pro návrhy.
select	string	Seznam polí oddělených čárkami, která se mají načíst. Pokud není zadáno, bude do výsledků zahrnuto pouze klíčové pole.
suggesterName	string	Název navrhujícího, jak je uvedeno v kolekci pro návrhy, která je součástí definice indexu.
top	integer (int32)	Počet návrhů k načtení. Musí to být hodnota mezi 1 a 100. Výchozí hodnota je 5.

SuggestResult

Objekt

Výsledek obsahující dokument nalezený dotazem návrhu a přidruženými metadaty.

Name	Typ	Description
@search.text	string	Text výsledku návrhu.