Documents - Suggest Post

Service:: Search Service

Version d'API:: 2026-04-01

Suggère des documents dans l’index qui correspondent au texte de requête partiel donné.

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

Paramètres URI

Nom	Dans	Obligatoire	Type	Description
endpoint	path	True	string (uri)	URL du point de terminaison du service de recherche.
indexName	path	True	string	Nom de l’index.
api-version	query	True	string minLength: 1	Version de l’API à utiliser pour cette opération.

En-tête de la demande

Nom	Obligatoire	Type	Description
Accept		Accept	L’en-tête Accept.
x-ms-client-request-id		string (uuid)	Identificateur de chaîne opaque, globalement unique et généré par le client pour la requête.

Corps de la demande

Nom	Obligatoire	Type	Description
search	True	string	Texte de recherche à utiliser pour suggérer des documents. Doit comporter au moins 1 caractère et pas plus de 100 caractères.
suggesterName	True	string	Nom du suggesteur tel que spécifié dans la collection suggesteurs qui fait partie de la définition d’index.
filter		string	Expression OData qui filtre les documents pris en compte pour les suggestions.
fuzzy		boolean	Valeur indiquant s’il faut utiliser la correspondance approximative pour la requête de suggestion. La valeur par défaut est false. Lorsqu’elle est définie sur true, la requête trouvera des suggestions même s’il y a un caractère substitué ou manquant dans le texte de recherche. Bien que cela offre une meilleure expérience dans certains scénarios, cela a un coût en termes de performances, car les recherches de suggestions floues sont plus lentes et consomment plus de ressources.
highlightPostTag		string	Balise de chaîne ajoutée aux surbrillances d’accès. Doit être défini avec highlightPreTag. En cas d’omission, la mise en surbrillance des suggestions est désactivée.
highlightPreTag		string	Balise de chaîne qui est précédée de mises en surbrillance. Doit être défini avec highlightPostTag. En cas d’omission, la mise en surbrillance des suggestions est désactivée.
minimumCoverage		number (double)	Nombre compris entre 0 et 100 indiquant le pourcentage de l’index qui doit être couvert par une requête de suggestion pour que la requête soit déclarée comme réussie. Ce paramètre peut être utile pour garantir la disponibilité de la recherche même pour les services avec un seul réplica. La valeur par défaut est 80.
orderby		string	Liste des expressions OData $orderby séparées par des virgules permettant de trier les résultats. Chaque expression peut être un nom de champ ou un appel aux fonctions geo.distance() ou search.score(). Chaque expression peut être suivie d’asc pour indiquer l’ordre croissant ou desc pour indiquer l’ordre décroissant. La valeur par défaut est l’ordre croissant. Les liens seront rompus par les scores de correspondance des documents. Si aucune $orderby n’est spécifiée, l’ordre de tri par défaut descend par score de correspondance de document. Il peut y avoir au maximum 32 clauses $orderby.
searchFields		string	Liste de noms de champs séparés par des virgules pour rechercher le texte de recherche spécifié. Les champs cibles doivent être inclus dans le suggesteur spécifié.
select		string	Liste des champs à récupérer, séparés par des virgules. S’il n’est pas spécifié, seul le champ clé sera inclus dans les résultats.
top		integer (int32)	Le nombre de suggestions à récupérer. Il doit s’agir d’une valeur comprise entre 1 et 100. La valeur par défaut est 5.

Réponses

Nom	Type	Description
200 OK	SuggestDocumentsResult	La demande a réussi.
Other Status Codes	ErrorResponse	Réponse d’erreur inattendue.

Sécurité

api-key

Type: apiKey
Dans: header

OAuth2Auth

Type: oauth2
Flux: implicit
URL d’autorisation: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Étendues

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

Exemples

SearchIndexSuggestDocumentsPost

Exemple de requête

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
}

Exemple de réponse

Code d’état:: 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"
    }
  ]
}

Définitions

Nom	Description
Accept	L’en-tête Accept.
ErrorAdditionalInfo	Informations supplémentaires sur l’erreur de gestion des ressources.
ErrorDetail	Détail de l’erreur.
ErrorResponse	Réponse à l’erreur courante pour toutes les API Azure Resource Manager afin de renvoyer les détails d’erreur pour les opérations ratées. (Cela suit également le format de réponse d’erreur OData.).
SuggestDocumentsResult	Réponse contenant des résultats de requête de suggestion à partir d’un index.
SuggestRequest	Paramètres pour le filtrage, le tri, la correspondance approximative et d’autres comportements de requête de suggestions.
SuggestResult	Résultat contenant un document trouvé par une requête de suggestion, ainsi que des métadonnées associées.

Accept

Énumération

L’en-tête Accept.

Valeur	Description
application/json;odata.metadata=none

ErrorAdditionalInfo

Objet

Informations supplémentaires sur l’erreur de gestion des ressources.

Nom	Type	Description
info		Informations supplémentaires.
type	string	Type d’informations supplémentaire.

ErrorDetail

Objet

Détail de l’erreur.

Nom	Type	Description
additionalInfo	ErrorAdditionalInfo[]	Informations supplémentaires sur l’erreur.
code	string	Code d’erreur.
details	ErrorDetail[]	Détails de l’erreur.
message	string	Message d’erreur.
target	string	Cible d’erreur.

ErrorResponse

Objet

Réponse à l’erreur courante pour toutes les API Azure Resource Manager afin de renvoyer les détails d’erreur pour les opérations ratées. (Cela suit également le format de réponse d’erreur OData.).

Nom	Type	Description
error	ErrorDetail	Objet d’erreur.

SuggestDocumentsResult

Objet

Réponse contenant des résultats de requête de suggestion à partir d’un index.

Nom	Type	Description
@search.coverage	number (double)	Valeur indiquant le pourcentage de l’index inclus dans la requête, ou null si minimumCoverage n’a pas été défini dans la demande.
value	SuggestResult[]	Séquence de résultats retournés par la requête.

SuggestRequest

Objet

Paramètres pour le filtrage, le tri, la correspondance approximative et d’autres comportements de requête de suggestions.

Nom	Type	Description
filter	string	Expression OData qui filtre les documents pris en compte pour les suggestions.
fuzzy	boolean	Valeur indiquant s’il faut utiliser la correspondance approximative pour la requête de suggestion. La valeur par défaut est false. Lorsqu’elle est définie sur true, la requête trouvera des suggestions même s’il y a un caractère substitué ou manquant dans le texte de recherche. Bien que cela offre une meilleure expérience dans certains scénarios, cela a un coût en termes de performances, car les recherches de suggestions floues sont plus lentes et consomment plus de ressources.
highlightPostTag	string	Balise de chaîne ajoutée aux surbrillances d’accès. Doit être défini avec highlightPreTag. En cas d’omission, la mise en surbrillance des suggestions est désactivée.
highlightPreTag	string	Balise de chaîne qui est précédée de mises en surbrillance. Doit être défini avec highlightPostTag. En cas d’omission, la mise en surbrillance des suggestions est désactivée.
minimumCoverage	number (double)	Nombre compris entre 0 et 100 indiquant le pourcentage de l’index qui doit être couvert par une requête de suggestion pour que la requête soit déclarée comme réussie. Ce paramètre peut être utile pour garantir la disponibilité de la recherche même pour les services avec un seul réplica. La valeur par défaut est 80.
orderby	string	Liste des expressions OData $orderby séparées par des virgules permettant de trier les résultats. Chaque expression peut être un nom de champ ou un appel aux fonctions geo.distance() ou search.score(). Chaque expression peut être suivie d’asc pour indiquer l’ordre croissant ou desc pour indiquer l’ordre décroissant. La valeur par défaut est l’ordre croissant. Les liens seront rompus par les scores de correspondance des documents. Si aucune $orderby n’est spécifiée, l’ordre de tri par défaut descend par score de correspondance de document. Il peut y avoir au maximum 32 clauses $orderby.
search	string	Texte de recherche à utiliser pour suggérer des documents. Doit comporter au moins 1 caractère et pas plus de 100 caractères.
searchFields	string	Liste de noms de champs séparés par des virgules pour rechercher le texte de recherche spécifié. Les champs cibles doivent être inclus dans le suggesteur spécifié.
select	string	Liste des champs à récupérer, séparés par des virgules. S’il n’est pas spécifié, seul le champ clé sera inclus dans les résultats.
suggesterName	string	Nom du suggesteur tel que spécifié dans la collection suggesteurs qui fait partie de la définition d’index.
top	integer (int32)	Le nombre de suggestions à récupérer. Il doit s’agir d’une valeur comprise entre 1 et 100. La valeur par défaut est 5.

SuggestResult

Objet

Résultat contenant un document trouvé par une requête de suggestion, ainsi que des métadonnées associées.

Nom	Type	Description
@search.text	string	Le texte du résultat de la suggestion.