Partager via

Documents - Suggest Post

Service:
Search Service
Version d'API:
2025-09-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=2025-09-01

Paramètres URI

Nom Dans Obligatoire Type Description
endpoint
 path True

string

URL du point de terminaison du service de recherche.
indexName
 path True

string

Nom de l’index.
api-version
 query True

string

Version de l’API cliente.

En-tête de la demande

Nom Obligatoire Type Description
x-ms-client-request-id

string (uuid)

ID de suivi envoyé avec la demande pour aider au débogage.

Corps de la demande

Nom Obligatoire Type Description
search True

string

Le 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 qu’il est spécifié dans la collection de suggesteurs qui fait partie de la définition de l’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

Une balise de chaîne qui est ajoutée aux points forts des hits. Doit être défini avec highlightPreTag. En cas d’omission, la mise en surbrillance des suggestions est désactivée.
highlightPreTag

string

Une balise de chaîne qui est ajoutée pour frapper les points forts. 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 ne comportant qu’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 soit un nom de champ, soit un appel aux fonctions geo.distance() ou search.score(). Chaque expression peut être suivie de asc pour indiquer l’ascendant, ou de desc pour indiquer la descendance. La valeur par défaut est l’ordre croissant. Les égalités seront brisées par les scores de match des documents. Si aucun $orderby n’est spécifié, l’ordre de tri par défaut est décroissant en fonction du score de correspondance du document. Il peut y avoir au plus 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

Réponse contenant des documents suggérés qui correspondent à l’entrée partielle.
Other Status Codes

ErrorResponse

Réponse d’erreur.

Exemples

SearchIndexSuggestDocumentsPost

Exemple de requête

POST https://stableexampleservice.search.windows.net/indexes('stable-test')/docs/search.post.suggest?api-version=2025-09-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
ErrorAdditionalInfo

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

Détail de l’erreur.
ErrorResponse

Réponse d’erreur
SuggestDocumentsResult

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

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

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

ErrorAdditionalInfo

Object

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

Nom Type Description
info

object

Informations supplémentaires.
type

string

Type d’informations supplémentaire.

ErrorDetail

Object

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

Object

Réponse d’erreur

Nom Type Description
error

ErrorDetail

Objet d’erreur.

SuggestDocumentsResult

Object

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 des résultats renvoyés par la requête.

SuggestRequest

Object

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

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

Une balise de chaîne qui est ajoutée aux points forts des hits. Doit être défini avec highlightPreTag. En cas d’omission, la mise en surbrillance des suggestions est désactivée.
highlightPreTag

string

Une balise de chaîne qui est ajoutée pour frapper les points forts. 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 ne comportant qu’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 soit un nom de champ, soit un appel aux fonctions geo.distance() ou search.score(). Chaque expression peut être suivie de asc pour indiquer l’ascendant, ou de desc pour indiquer la descendance. La valeur par défaut est l’ordre croissant. Les égalités seront brisées par les scores de match des documents. Si aucun $orderby n’est spécifié, l’ordre de tri par défaut est décroissant en fonction du score de correspondance du document. Il peut y avoir au plus 32 clauses $orderby.
search

string

Le 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 qu’il est spécifié dans la collection de suggesteurs qui fait partie de la définition de l’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

Object

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

Nom Type Description
@search.text

string

Le texte du résultat de la suggestion.