Suggestions (API REST Azure AI Search)

  • Article

Une demande de suggestions est une requête de recherche en tant que type qui recherche des valeurs correspondantes dans les champs prenant en charge les suggesteur et retourne des documents qui contiennent une correspondance. Par exemple, si vous activez les suggestions sur un champ de ville , la saisie de « mer » génère des documents contenant « Seattle », « Sea Tac » et « Seaside » (tous les noms de ville réels) pour ce champ.

La réponse est un contenu provenant d’un document correspondant et de la clé de document. Contrairement à la saisie semi-automatique, qui retourne un terme ou une expression terminé utilisé dans une requête secondaire, cette requête retourne des informations qui sont résolues en documents réels. Si les termes ou expressions correspondants sont identiques d’un document à l’autre, le contenu correspondant est répété. Pour améliorer la structure des résultats, envisagez d’utiliser le $select filtre pour retourner des champs supplémentaires qui fournissent plus de différenciation et de contexte.

Le protocole HTTPS est requis pour les requêtes de service. La requête Suggest peut être construite à l’aide des méthodes GET ou 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]

Contrairement à une demande de recherche dans les documents , vous pouvez lier un appel de suggestions à une entrée clavier, tandis qu’un appel de recherche peut être lié à un événement click.

Lorsqu’elle est appelée avec GET, la longueur de l’URL de la requête ne peut pas dépasser 8 Ko. Cette longueur est généralement suffisante pour la plupart des applications. Toutefois, certaines applications produisent des requêtes très volumineuses, en particulier lorsque des expressions de filtre OData sont utilisées. Pour ces applications, HTTP POST est un meilleur choix, car il autorise des filtres plus grands que GET.

Avec POST, le nombre de clauses dans un filtre est le facteur limitant, pas la taille de la chaîne du filtre brut, car la limite de la taille de la requête POST est proche de 16 Mo. Bien que la limite de la taille de la requête POST est très importante, les expressions de filtre ne peuvent pas être arbitrairement complexes. Pour plus d’informations sur les limitations de complexité des filtres, consultez Syntaxe des expressions OData pour Azure AI Search.

Paramètres URI

Paramètre Description
[nom du service] Obligatoire. Définissez cette valeur sur le nom unique défini par l’utilisateur de votre service de recherche.
[nom de l’index]/docs Obligatoire. Spécifie la collection de documents d’un index nommé.
api-version Obligatoire. La version stable actuelle est api-version=2020-06-30. Pour plus d’informations sur les versions, consultez Versions de l’API . Pour les requêtes, api-version est toujours spécifié en tant que paramètre d’URI pour GET et POST.

Recommandations relatives à l’encodage d’URL

N’oubliez pas d’encoder des paramètres de requête spécifiques à l’URL lors de l’appel direct de l’API REST GET. Pour les opérations Suggestions , cela inclut :

  • recherche
  • $filter
  • highlightPreTag
  • highlightPostTag

L’encodage d’URL est recommandé uniquement pour des paramètres individuels. Si vous avez involontairement codé par URL la chaîne de requête entière (tout ce qui suit le signe ?), les demandes s'interrompent.

En outre, l'encodage des URL est nécessaire uniquement lors de l'appel direct de l'API REST à l'aide de GET. Aucun encodage d’URL n’est nécessaire lors de l’appel de Suggestions à l’aide de POST, ou lorsque la bibliothèque cliente .NET Recherche Azure AI gère l’encodage d’URL pour vous.

En-têtes de requête

Le tableau suivant décrit les en-têtes de demande obligatoires et facultatifs.

Champs Description
Content-Type Obligatoire. À définir avec la valeur application/json
api-key Facultatif si vous utilisez des rôles Azure et qu’un jeton de porteur est fourni sur la demande, sinon une clé est requise. Une clé API est une chaîne unique générée par le système qui authentifie la demande auprès de votre service de recherche. Les demandes de requête sur la collection de documents peuvent spécifier une clé d’administration ou une clé de requête comme clé API. La clé de requête est utilisée pour les opérations en lecture seule sur la collection de documents. Pour plus d’informations, consultez Se connecter à Azure AI Search à l’aide de l’authentification par clé .

Corps de la demande

Pour GET : aucun.

Pour 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)  
}

Paramètres de requête

Une requête accepte plusieurs paramètres sur l’URL lorsqu’elle est appelée avec GET, et en tant que propriétés JSON dans le corps de la requête lorsqu’elle est appelée avec POST. La syntaxe de certains paramètres est légèrement différente entre GET et POST. Ces différences sont indiquées comme applicable ci-dessous.

Nom Type Description
api-version string Obligatoire. Version de l’API REST utilisée pour la requête. Pour obtenir la liste des versions prises en charge, consultez Versions d’API. Pour cette opération, api-version est spécifié en tant que paramètre de requête dans l’URL, que vous appeliez l’API avec GET ou POST.
$filter string facultatif. Expression qui filtre les documents pris en considération pour les suggestions. Seuls les champs filtrables peuvent être utilisés dans un filtre. Les expressions de filtre « search.ismatch » et « search.ismatchscoring* » ne sont pas prises en charge dans l’API de saisie semi-automatique. Lorsqu’il est appelé avec POST, ce paramètre est nommé filter au lieu de $filter. Pour plus d’informations sur le sous-ensemble de la grammaire d’expression OData prise en charge par Azure AI Search, consultez Syntaxe d’expression OData pour Azure AI Search .
Floue boolean facultatif. La valeur par défaut est false. Lorsqu’elle est définie sur true, cette API recherche des suggestions même s’il existe un caractère remplacé ou manquant dans le texte de recherche. La distance de modification est de 1 par chaîne de requête. Si la chaîne de requête est composée de plusieurs termes, il ne peut y avoir qu’un seul caractère manquant, supplémentaire, substitué ou transpose dans l’ensemble de la chaîne. L’activation de la correspondance approximative peut être une meilleure expérience dans certains scénarios. Elle a un coût de performances, car les recherches de suggestions approximatives sont plus lentes et consomment plus de ressources.
highlightPostTag string facultatif. La valeur par défaut est une chaîne vide. Balise de chaîne qui ajoute au terme mis en surbrillance. Doit être défini avec highlightPreTag. Les caractères réservés dans l'URL doivent être codés en pourcentage (par exemple, %23 au lieu de #). Lorsqu’il est appelé à l’aide de GET, les caractères réservés dans l’URL doivent être encodés en pourcentage (par exemple, %23 au lieu de #).
highlightPreTag string facultatif. Par défaut, une chaîne vide. Balise de chaîne qui est ajoutée au terme mis en surbrillance. Doit être défini avec highlightPostTag. Lorsqu’elle est appelée à l’aide de GET, les caractères réservés de l’URL doivent être encodés en pourcentage (par exemple, %23 au lieu de #).
$orderby string facultatif. Liste séparée par des virgules des expressions sur la base desquelles trier les résultats. Chaque expression peut être un nom de champ ou un appel à la fonction geo.distance() . Chaque expression peut être suivie de « asc » (croissant) ou « desc » (décroissant). La valeur par défaut est l'ordre croissant. Il existe une limite de 32 clauses pour $orderby. Lorsqu’il est appelé avec POST, ce paramètre est nommé ordre au lieu de $orderby.
minimumCoverage entier facultatif. La valeur par défaut est 80. Nombre compris entre 0 et 100 indiquant le pourcentage de l’index qui doit être disponible pour traiter la requête avant qu’elle puisse être signalée en tant que réussite.

La valeur par défaut reflète un biais vers la vitesse et l’efficacité par rapport à la couverture complète. La réduction de la couverture limite l’expansion des requêtes, ce qui permet aux résultats de revenir plus rapidement. Il permet également à la requête de réussir en cas de disponibilité partielle de l’index, même si une partition est lente à répondre ou indisponible en raison de problèmes d’intégrité du service ou de maintenance d’index.

Quelle que soit la valeur de minimumCoverage, ce pourcentage de l’index doit être disponible ou Suggestions retourne le code HTTP status 503. Si les suggestions réussissent au niveau minimalCoverage, elles retournent HTTP 200 et incluent une @search.coverage valeur dans la réponse indiquant le pourcentage de l’index disponible lors de la maintenance de la requête.

La réduction de cette valeur peut être utile si des erreurs 503 se produisent. Sinon, vous pouvez envisager d’augmenter la valeur si la réponse fournit des correspondances insuffisantes.
recherche string Obligatoire. Texte recherché à utiliser pour suggérer des requêtes. Doit comprendre 1 caractère au minimum et 100 caractères au maximum. Il ne peut pas contenir d’opérateurs, de syntaxe de requête ou d’expressions entre guillemets.
searchFields string facultatif. Liste séparée par des virgules des noms de champ dans lesquels rechercher le texte spécifié. Les champs cibles doivent être répertoriés dans la définition suggesteurs de l’index.
$select string facultatif. Liste séparée par des virgules des champs à récupérer. S’il n’est pas spécifié, seuls la clé de document et le texte de suggestion sont retournés. Vous pouvez demander explicitement tous les champs en définissant ce paramètre avec la valeur *. Lorsque vous appelez avec POST, ce paramètre est nommé select au lieu de $select.
suggesterName string Obligatoire. Nom du suggesteur tel que spécifié dans la collection Suggesters qui fait partie de la définition d’index. Un suggesteur détermine quels champs sont analysés pour rechercher les termes de requête suggérés.
$top entier facultatif. La valeur par défaut est 5). Nombre de suggestions de saisie automatique à récupérer. La valeur doit être un nombre compris entre 1 et 100. Lorsque vous appelez avec POST, ce paramètre est nommé top au lieu de $top.

response

Code d’état : « 200 OK » est retourné pour une réponse réussie.

{  
  "@search.coverage": # (if minimumCoverage was provided in the query),  
  "value": [  
    {  
      "@search.text": "...",  
      "<key field>": "..."  
    },  
    ...  
  ]  
}

Si l'option de projection est utilisée pour récupérer des champs, ceux-ci sont inclus dans chaque élément du tableau :

{  
  "value": [  
    {  
      "@search.text": "...",  
      "<key field>": "..."  
      <other projected data fields>  
    },  
    ...  
  ]  
}

Exemples

Récupérer 5 suggestions où l'entrée de recherche partielle est « 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"  
    }

Notez que suggesterName est requis dans une opération Suggestions.

Voir aussi