Documents - Suggest Post

Servizio:: Search Service

Versione API:: 2026-04-01

Suggerisce i documenti nell'indice che corrispondono al testo della query parziale specificato.

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

Parametri dell'URI

Nome	In	Necessario	Tipo	Descrizione
endpoint	path	True	string (uri)	URL dell'endpoint del servizio di ricerca.
indexName	path	True	string	Nome dell'indice.
api-version	query	True	string minLength: 1	Versione dell'API da usare per questa operazione.

Intestazione della richiesta

Nome	Necessario	Tipo	Descrizione
Accept		Accept	L'intestazione Accetta.
x-ms-client-request-id		string (uuid)	Identificatore di stringa opaco, univoco a livello globale e generato dal client per la richiesta.

Corpo della richiesta

Nome	Necessario	Tipo	Descrizione
search	True	string	Testo di ricerca da usare per suggerire documenti. Deve essere almeno 1 carattere e non più di 100 caratteri.
suggesterName	True	string	Nome del suggerimento come specificato nell'insieme di suggerimenti che fa parte della definizione dell'indice.
filter		string	Espressione OData che filtra i documenti considerati per i suggerimenti.
fuzzy		boolean	Valore che indica se utilizzare la corrispondenza fuzzy per la query di suggerimento. Il valore predefinito è false. Se impostata su true, la query troverà suggerimenti anche se è presente un carattere sostituito o mancante nel testo di ricerca. Sebbene ciò offra un'esperienza migliore in alcuni scenari, ha un costo in termini di prestazioni poiché le ricerche di suggerimenti fuzzy sono più lente e consumano più risorse.
highlightPostTag		string	Tag stringa aggiunto per l'evidenziazione dei riscontri. Deve essere impostato con highlightPreTag. Se omesso, l'evidenziazione dei suggerimenti è disabilitata.
highlightPreTag		string	Tag stringa anteporto all'evidenziazione dei riscontri. Deve essere impostato con highlightPostTag. Se omesso, l'evidenziazione dei suggerimenti è disabilitata.
minimumCoverage		number (double)	Un numero compreso tra 0 e 100 che indica la percentuale dell'indice che deve essere coperta da una query di suggerimento affinché la query venga segnalata come riuscita. Questo parametro può essere utile per garantire la disponibilità della ricerca anche per i servizi con una sola replica. Il valore predefinito è 80.
orderby		string	L'elenco delimitato da virgole di OData $orderby espressioni in base alle quali ordinare i risultati. Ogni espressione può essere un nome di campo o una chiamata alle funzioni geo.distance() o search.score(). Ogni espressione può essere seguita da asc per indicare un valore crescente o desc per indicare la decrescente. Il valore predefinito è crescente. I legami verranno interrotti dai punteggi di corrispondenza dei documenti. Se non viene specificato alcun $orderby, l'ordinamento predefinito è decrescente in base al punteggio di corrispondenza del documento. Possono essere presenti al massimo 32 clausole $orderby.
searchFields		string	Elenco delimitato da virgole dei nomi dei campi per la ricerca del testo di ricerca specificato. I campi di destinazione devono essere inclusi nel suggerimento specificato.
select		string	L'elenco delimitato da virgole dei campi da recuperare. Se non specificato, nei risultati verrà incluso solo il campo chiave.
top		integer (int32)	Il numero di suggerimenti da recuperare. Deve essere un valore compreso tra 1 e 100. L'impostazione predefinita è 5.

Risposte

Nome	Tipo	Descrizione
200 OK	SuggestDocumentsResult	La richiesta ha avuto esito positivo.
Other Status Codes	ErrorResponse	Risposta di errore imprevista.

Sicurezza

api-key

Tipo: apiKey
In: header

OAuth2Auth

Tipo: oauth2
Flow: implicit
URL di autorizzazione: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Ambiti

Nome	Descrizione
https://search.azure.com/.default

Esempio

SearchIndexSuggestDocumentsPost

Esempio di richiesta

HTTP

POST https://exampleservice.search.windows.net/indexes('example-index')/docs/search.post.suggest?api-version=2026-04-01


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

Risposta di esempio

Codice di stato:: 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"
    }
  ]
}

Definizioni

Nome	Descrizione
Accept	L'intestazione Accetta.
ErrorAdditionalInfo	Informazioni aggiuntive sull'errore di gestione delle risorse.
ErrorDetail	Dettagli dell'errore.
ErrorResponse	Risposta di errore comune per tutte le API di Azure Resource Manager per restituire i dettagli dell'errore per le operazioni non riuscite. Questo segue anche il formato di risposta di errore OData.
SuggestDocumentsResult	Risposta contenente i risultati della query di suggerimento da un indice.
SuggestRequest	Parametri per il filtro, l'ordinamento, la corrispondenza fuzzy e altri comportamenti di query di suggerimenti.
SuggestResult	Risultato contenente un documento trovato da una query di suggerimento, oltre ai metadati associati.

Accept

Enumerazione

L'intestazione Accetta.

Valore	Descrizione
application/json;odata.metadata=none

ErrorAdditionalInfo

Oggetto

Informazioni aggiuntive sull'errore di gestione delle risorse.

Nome	Tipo	Descrizione
info		Informazioni aggiuntive.
type	string	Tipo di informazioni aggiuntive.

ErrorDetail

Oggetto

Dettagli dell'errore.

Nome	Tipo	Descrizione
additionalInfo	ErrorAdditionalInfo[]	Informazioni aggiuntive sull'errore.
code	string	Codice di errore.
details	ErrorDetail[]	Dettagli dell'errore.
message	string	Messaggio di errore.
target	string	Destinazione dell'errore.

ErrorResponse

Oggetto

Risposta di errore comune per tutte le API di Azure Resource Manager per restituire i dettagli dell'errore per le operazioni non riuscite. Questo segue anche il formato di risposta di errore OData.

Nome	Tipo	Descrizione
error	ErrorDetail	Oggetto error.

SuggestDocumentsResult

Oggetto

Risposta contenente i risultati della query di suggerimento da un indice.

Nome	Tipo	Descrizione
@search.coverage	number (double)	Valore che indica la percentuale dell'indice inclusa nella query oppure null se minimumCoverage non è stato impostato nella richiesta.
value	SuggestResult[]	Sequenza di risultati restituiti dalla query.

SuggestRequest

Oggetto

Parametri per il filtro, l'ordinamento, la corrispondenza fuzzy e altri comportamenti di query di suggerimenti.

Nome	Tipo	Descrizione
filter	string	Espressione OData che filtra i documenti considerati per i suggerimenti.
fuzzy	boolean	Valore che indica se utilizzare la corrispondenza fuzzy per la query di suggerimento. Il valore predefinito è false. Se impostata su true, la query troverà suggerimenti anche se è presente un carattere sostituito o mancante nel testo di ricerca. Sebbene ciò offra un'esperienza migliore in alcuni scenari, ha un costo in termini di prestazioni poiché le ricerche di suggerimenti fuzzy sono più lente e consumano più risorse.
highlightPostTag	string	Tag stringa aggiunto per l'evidenziazione dei riscontri. Deve essere impostato con highlightPreTag. Se omesso, l'evidenziazione dei suggerimenti è disabilitata.
highlightPreTag	string	Tag stringa anteporto all'evidenziazione dei riscontri. Deve essere impostato con highlightPostTag. Se omesso, l'evidenziazione dei suggerimenti è disabilitata.
minimumCoverage	number (double)	Un numero compreso tra 0 e 100 che indica la percentuale dell'indice che deve essere coperta da una query di suggerimento affinché la query venga segnalata come riuscita. Questo parametro può essere utile per garantire la disponibilità della ricerca anche per i servizi con una sola replica. Il valore predefinito è 80.
orderby	string	L'elenco delimitato da virgole di OData $orderby espressioni in base alle quali ordinare i risultati. Ogni espressione può essere un nome di campo o una chiamata alle funzioni geo.distance() o search.score(). Ogni espressione può essere seguita da asc per indicare un valore crescente o desc per indicare la decrescente. Il valore predefinito è crescente. I legami verranno interrotti dai punteggi di corrispondenza dei documenti. Se non viene specificato alcun $orderby, l'ordinamento predefinito è decrescente in base al punteggio di corrispondenza del documento. Possono essere presenti al massimo 32 clausole $orderby.
search	string	Testo di ricerca da usare per suggerire documenti. Deve essere almeno 1 carattere e non più di 100 caratteri.
searchFields	string	Elenco delimitato da virgole dei nomi dei campi per la ricerca del testo di ricerca specificato. I campi di destinazione devono essere inclusi nel suggerimento specificato.
select	string	L'elenco delimitato da virgole dei campi da recuperare. Se non specificato, nei risultati verrà incluso solo il campo chiave.
suggesterName	string	Nome del suggerimento come specificato nell'insieme di suggerimenti che fa parte della definizione dell'indice.
top	integer (int32)	Il numero di suggerimenti da recuperare. Deve essere un valore compreso tra 1 e 100. L'impostazione predefinita è 5.

SuggestResult

Oggetto

Risultato contenente un documento trovato da una query di suggerimento, oltre ai metadati associati.

Nome	Tipo	Descrizione
@search.text	string	Il testo del risultato del suggerimento.