Partager via


Rechercher des documents (API REST en préversion)

s’applique à: 2023-07-01-Preview. Cette version n’est plus prise en charge. mettre à niveau immédiatement vers une version plus récente.

Important

2023-07-01-Preview ajoute :

  • « vecteurs » paramètre de requête spécifiant les requêtes de vecteurs. Chaque objet doit contenir la représentation vectorielle de la requête, « k » nombre de voisins les plus proches à retourner dans les résultats et les champs vectoriels à utiliser pendant l’exécution de la requête.

2021-04-30-Preview ajoute :

  • « semanticConfiguration » prend en charge le classement sémantique d’étendue sur des champs spécifiques.
  • « légendes » retourne des expressions extraites des passages clés dans les documents les plus classés sémantiquement.

2020-06-30-Preview ajoute :

  • « queryType=semantic » prend en charge la reranking sémantique et les réponses.
  • « searchFields » dans une requête sémantique établit l’ordre de priorité des champs utilisés pour formuler des légendes et des réponses. Cette approche a été remplacée par « semanticConfiguration » en 2021-04-30-Preview et est désormais obsolète.
  • « orthographique » active la correction orthographique sur l’entrée de requête.
  • « queryLanguage » est nécessaire pour « queryType=semantic » et « speller ».
  • « featuresMode » décompresse un score de recherche, signale la fréquence de terme par champ, le score de similarité par champ et le nombre de correspondances uniques par champ.

Une requête cible la collection de documents d’un index unique sur un service de recherche. Il inclut des paramètres qui définissent les critères de correspondance et les paramètres qui forment la réponse. Vous pouvez également utiliser un alias d’index pour cibler un index particulier au lieu d’utiliser le nom d’index lui-même.

Vous pouvez utiliser GET ou POST pour la plupart des requêtes, mais vous devez utiliser POST pour la recherche vectorielle, car les paramètres de requête vectorielle ne correspondent pas à un URI. paramètres de requête sont spécifiés sur la chaîne de requête pour les requêtes GET et dans le corps de la requête pour les requêtes POST.

GET https://[service name].search.windows.net/indexes/[index name]/docs?[query parameters] 
  Content-Type: application/json   
  api-key: [admin or query key]  

Si vous utilisez POST, ajoutez l’action « search » en tant que paramètre d’URI.

POST https://[service name].search.windows.net/indexes/[index name]/docs/search?api-version=[api-version]  
  Content-Type: application/json  
  api-key: [admin or query key]  

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 suffisante pour la plupart des applications. Toutefois, certaines applications produisent des requêtes 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 volumineux que GET.

Avec POST, le nombre de clauses d’un filtre est le facteur de limitation, et non la taille de la chaîne de filtre brute, car la limite de taille de requête pour POST est d’environ 16 Mo. Même si la limite de taille de requête POST est importante, les expressions de filtre ne peuvent pas être arbitrairement complexes. Pour plus d’informations sur les limitations de complexité des filtres, consultez syntaxe d’expression OData pour azure AI Search.

Paramètres d’URI

Paramètre Description
nom du service Obligatoire. Définissez ce nom sur le nom unique défini par l’utilisateur de votre service de recherche.
nom/docs d’index Obligatoire. Spécifie la collection de documents d’un index nommé. Le nom d’un alias d’index peut également être utilisé à la place du nom de l’index.
paramètres de requête Les paramètres de requête sont spécifiés sur l’URI des requêtes GET et dans le corps de la requête pour les requêtes POST.
api-version Obligatoire. Consultez versions de l’API pour plus de versions.

Recommandations d’encodage d’URL

N’oubliez pas de encodez l’URL paramètres de requête spécifiques lors de l’appel direct de l’API REST GET. Pour une opération Rechercher des documents, l’encodage d’URL peut être nécessaire pour les paramètres de requête suivants :

  • rechercher
  • $filter
  • facette
  • highlightPreTag
  • highlightPostTag

L’encodage d’URL est recommandé uniquement pour les paramètres individuels. Si vous encodez par inadvertance url la chaîne de requête entière (tout après le ?), les requêtes s’interrompent.

En outre, l’encodage d’URL est nécessaire uniquement lors de l’appel de l’API REST directement à l’aide de GET. Aucun encodage d’URL n’est nécessaire lors de l’utilisation de POST, ou lors de l’utilisation de la bibliothèque cliente .NET recherche Azure AI Search, qui gère l’encodage pour vous.

En-têtes de requête

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

Champs Description
Type de contenu Obligatoire. Définissez cette valeur sur « application/json »
api-key Facultatif si vous utilisez rôles Azure et qu’un jeton du 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 requête 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 :

{  
     "answers": "none" (default) | "extractive", 
     "count": true | false (default),
     "captions": "none" (default) | "extractive",
     "facets": [ "facet_expression_1", "facet_expression_2", ... ],  
     "featuresMode" : "disabled" (default) | "enabled",
     "filter": "odata_filter_expression",  
     "highlight": "highlight_field_1, highlight_field_2, ...",  
     "highlightPreTag": "pre_tag",  
     "highlightPostTag": "post_tag",  
     "minimumCoverage": # (% of index that must be covered to declare query successful; default 100),  
     "orderby": "orderby_expression",
     "queryLanguage": "en-us" (default) | (a supported language code), 
     "queryType": "simple" (default) | "full" | "semantic",
     "scoringParameters": [ "scoring_parameter_1", "scoring_parameter_2", ... ],  
     "scoringProfile": "scoring_profile_name",  
     "scoringStatistics" : "local" (default) | "global",
     "search": "simple_query_expression",  
     "searchFields": "field_name_1, field_name_2, ...",  
     "searchMode": "any" (default) | "all",  
     "select": "field_name_1, field_name_2, ...",  
     "semanticConfiguration": "semantic_configuration_name",
     "sessionId" : "session_id",
     "skip": # (default 0), 
     "speller": "none" (default) | "lexicon",  
     "top": #,
     "vectors": [
      {
        "value": "a vector representation of the query",
        "k": an integer (number of nearest neighbors to return as top results),
        "fields": "a comma-delimited list of vector fields to use in the query"
      }
     ]
   }  

continuation des réponses de recherche partielles

Parfois, Azure AI Search ne peut pas retourner tous les résultats demandés dans une seule réponse de recherche. Une réponse partielle peut se produire pour différentes raisons, par exemple lorsque la requête retourne trop de documents en ne spécifiant pas $top, ou en spécifiant une valeur pour $ top trop volumineuse. Dans ce cas, Azure AI Search inclut l’annotation @odata.nextLink dans le corps de la réponse, et également @search.nextPageParameters s’il s’agissait d’une requête POST. Vous pouvez utiliser les valeurs de ces annotations pour formuler une autre requête de recherche pour obtenir la partie suivante de la réponse de recherche. Ce comportement est appelé de continuation de la requête de recherche d’origine, et les annotations sont appelées jetons de continuation. Consultez l’exemple de la section Réponse pour plus d’informations sur la syntaxe de ces annotations et leur emplacement dans le corps de la réponse.

Les raisons pour lesquelles Azure AI Search peut retourner des jetons de continuation sont spécifiques à l’implémentation et susceptibles de changer. Les clients robustes doivent toujours être prêts à gérer les cas où moins de documents que prévu sont retournés et un jeton de continuation est inclus pour continuer à récupérer des documents. Notez également que vous devez utiliser la même méthode HTTP que la requête d’origine pour continuer. Par exemple, si vous avez envoyé une requête GET, toutes les demandes de continuation que vous envoyez doivent également utiliser GET (et de même pour POST).

Note

L’objectif de @odata.nextLink et de @search.nextPageParameters est de protéger le service contre les requêtes qui demandent trop de résultats, et non de fournir un mécanisme général pour la pagination. Si vous souhaitez parcourir les résultats, utilisez $top et $skip ensemble. Par exemple, si vous souhaitez des pages de taille 10, votre première demande doit avoir $top=10 et $skip=0, la deuxième demande doit avoir $top=10 et $skip=10, la troisième demande doit avoir $top=10 et $skip=20, et ainsi de suite.

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 notées dans le tableau suivant.

Nom Type Description
réponses (préversion) corde Optionnel. Les valeurs valides sont « none » et « extractif ». La valeur par défaut est « none ». Ce paramètre est valide uniquement si le type de requête est « sémantique ». Lorsqu’elle est définie sur « extractif », la requête formule et retourne des réponses des passages clés dans les documents classés sémantiquement les plus élevés. La valeur par défaut est une réponse, mais vous pouvez spécifier jusqu’à 10 en ajoutant un nombre. Par exemple, « réponses » : « extractif|count-3 » retourne trois réponses. Pour qu’une réponse soit retournée, il doit y avoir du contenu détaillé dans le champ ciblé qui ressemble à une réponse. Les modèles de langage utilisés pour les réponses sont formés pour reconnaître les réponses, et ne les génèrent pas. En outre, la requête elle-même doit ressembler à une question.
api-version corde 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, la version de l’API est spécifiée en tant que paramètre d’URI, que vous appeliez Documents de recherche avec GET ou POST.
légendes (préversion) corde Optionnel. Les valeurs valides sont « none » et « extractif ». La valeur par défaut est « none ». Ce paramètre est valide uniquement si le type de requête est « sémantique ». Lorsqu’elle est définie sur « extractif », la requête retourne des légendes extraites des passages clés dans les documents classés les plus élevés. Lorsque les légendes sont définies sur « extractifs », la mise en surbrillance est activée par défaut et peut être configurée en ajoutant le caractère de canal « | » suivi de l’option « highlight-<true/false>», telle que « extractif|highlight-true ».
$count booléen Optionnel. Les valeurs valides sont « true » ou « false ». La valeur par défaut est « false ». Lorsqu’il est appelé avec POST, ce paramètre est nommé au lieu de $count. Spécifie s’il faut extraire le nombre total de résultats. Cette valeur est le nombre de tous les documents qui correspondent aux paramètres de recherche et de $filter, ignorant $top et $skip. La définition de cette valeur sur « true » peut dégrader les performances. Le nombre est précis si l’index est stable, mais sous ou sur-rapporte tous les documents qui sont activement ajoutés, mis à jour ou supprimés. Si vous souhaitez obtenir uniquement le nombre sans documents, vous pouvez utiliser $top=0.
facettes ou facettes corde Optionnel. Champ à facettes, où le champ est attribué en tant que « facetable ». Lorsqu’elle est appelée avec GET, facet est un champ (facet: field1). Lorsqu’il est appelé avec POST, ce paramètre est nommé facets au lieu de facet et il est spécifié en tant que tableau (facets: [field1, field2, field3]). La chaîne peut contenir des paramètres pour personnaliser la facette, exprimée sous forme de paires nom-valeur séparées par des virgules.

Valeurs valides sont « count », « sort », « values », « interval » et « timeoffset ».

« count » est le nombre maximal de termes de facette ; la valeur par défaut est 10. Il n’existe aucune limite supérieure quant au nombre de termes, mais des valeurs plus élevées dégradent les performances, en particulier si le champ à facettes contient un grand nombre de termes uniques. Par exemple, « facet=category,count :5 » obtient les cinq premières catégories dans les résultats de facette. Si le paramètre count est inférieur au nombre de termes uniques, les résultats peuvent ne pas être exacts. Cela est dû à la façon dont les requêtes de facette sont distribuées entre les partitions. Pour obtenir un nombre précis sur toutes les partitions, vous pouvez définir le nombre sur zéro ou sur une valeur supérieure ou égale au nombre de valeurs uniques dans le champ facetable. L’inconvénient est une latence accrue.

« tri » peut être défini sur « count », « -count », « value », « -value ». Utilisez le nombre pour trier l’ordre décroissant par nombre. Utilisez -count pour trier l’ordre croissant par nombre. Utilisez la valeur pour trier par ordre croissant par valeur. Utilisez -value pour trier l’ordre décroissant par valeur (par exemple, « facet=category,count :3,sort :count » obtient les trois premières catégories dans les résultats de facette dans l’ordre décroissant par le nombre de documents portant le nom de la ville). Si les trois premières catégories sont Budget, Motel et Luxe, et Budget a cinq succès, Motel a six, et Luxe a quatre, alors les compartiments sont dans l’ordre Motel, Budget, Luxe. Pour -value, « facet=rating,sort :-value » produit des compartiments pour toutes les évaluations possibles, dans l’ordre décroissant par valeur (par exemple, si les évaluations sont comprises entre 1 et 5, les compartiments sont classés 5, 4, 3, 2, 1, quel que soit le nombre de documents correspondant à chaque évaluation).

« values » peut définir les valeurs numériques délimitées par un canal ou Edm.DateTimeOffset spécifiant un ensemble dynamique de valeurs d’entrée de facette (par exemple, « facet=baseRate,values :10 | 20 " produit trois compartiments : un pour le taux de base 0 jusqu’à 10, un pour 10 jusqu’à 20 et un pour 20 et plus). Une chaîne « facet=lastRenovationDate,values :2010-02-01T00:00:00Z » produit deux compartiments : un pour les hôtels rénovés avant février 2010 et un pour les hôtels rénovés le 1er février 2010 ou version ultérieure. Les valeurs doivent être répertoriées dans un ordre séquentiel croissant pour obtenir les résultats attendus.

« interval » est un intervalle entier supérieur à 0 pour les nombres, ou minute, heure, jour, semaine, mois, trimestre, année pour les valeurs d’heure de date. Par exemple, « facet=baseRate,interval :100 » produit des compartiments en fonction des plages de taux de base de taille 100. Si les tarifs de base sont compris entre 60 et 600 $, il y aura des compartiments pour 0-100, 100-200, 200-300, 300-400, 400-500 et 500-600. La chaîne « facet=lastRenovationDate,interval :year » produit un compartiment pour chaque année lorsque les hôtels ont été rénovés.

« timeoffset » peut être défini sur ([+-]hh :mm, [+-]hhmm ou [+-]hhh). S’il est utilisé, le paramètre timeoffset doit être combiné à l’option d’intervalle, et uniquement lorsqu’il est appliqué à un champ de type Edm.DateTimeOffset. La valeur spécifie le décalage horaire UTC à prendre en compte dans la définition des limites de temps. Par exemple : « facet=lastRenovationDate,interval :day,timeoffset :-01:00 » utilise la limite de jour qui commence à 01:00:00 UTC (minuit dans le fuseau horaire cible).

nombre et tri peuvent être combinés dans la même spécification de facette, mais ils ne peuvent pas être combinés avec des intervalles ou des valeurs, et l’intervalle et les valeurs ne peuvent pas être combinés.

facettes d’intervalle sur l’heure de date sont calculées en fonction de l’heure UTC si le décalage horaire n’est pas spécifié. Par exemple : pour « facet=lastRenovationDate,interval :day », la limite de jour commence à 00:00:00 UTC.
featuresMode (préversion) booléen Optionnel. Les valeurs valides sont « activées » et « désactivées ». La valeur par défaut est « disabled ». Valeur qui spécifie si les résultats doivent inclure fonctionnalités de résultat de requête, utilisée pour calculer le score de pertinence d’un document par rapport à la requête, par exemple par similarité de champ. Utilisez « activé » pour exposer davantage de fonctionnalités de résultat de requête : score de similarité par champ, fréquence de terme de champ et nombre de jetons uniques mis en correspondance. Pour plus d’informations, consultez Similarité etde scoring .
$filter corde Optionnel. Expression de recherche structurée dans la syntaxe OData standard. Seuls les champs filtrables peuvent être utilisés dans un filtre. Lorsqu’il est appelé avec POST, ce paramètre est nommé filtre au lieu de $filter. Consultez syntaxe d’expression OData pour recherche Azure AI pour plus d’informations sur le sous-ensemble de la grammaire d’expression OData prise en charge par Azure AI Search.
souligner corde Optionnel. Ensemble de noms de champs séparés par des virgules utilisés pour les surbrillances d’accès. Seuls les champs pouvant faire l’objet d’une recherche peuvent être utilisés pour la mise en surbrillance des accès. Par défaut, Azure AI Search retourne jusqu’à cinq surbrillances par champ. La limite est configurable par champ en ajoutant « -<nombre maximal de surbrillances>» en suivant le nom du champ. Par exemple, « highlight=title-3, description-10 » retourne jusqu’à trois hits mis en surbrillance à partir du champ de titre et jusqu’à 10 hits du champ de description. Le nombre maximal de surbrillances doit être un entier compris entre 1 et 1 000 inclus.
highlightPostTag corde Optionnel. La valeur par défaut est "</em>". 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 encodés en pourcentage (par exemple, %23 au lieu de #).
highlightPreTag corde Optionnel. La valeur par défaut est "</em>". Balise de chaîne qui s’ajoute au terme mis en surbrillance. Doit être défini avec highlightPostTag. Les caractères réservés dans l’URL doivent être encodés en pourcentage (par exemple, %23 au lieu de #).
minimumCoverage entier Optionnel. Les valeurs valides sont un nombre compris entre 0 et 100, indiquant le pourcentage de l’index qui doit être disponible pour le service de la requête avant de pouvoir être signalé comme un succès. La valeur par défaut est « 100 ».

Une couverture de cent pour cent signifie que toutes les partitions ont répondu à la demande (ni les problèmes d’intégrité du service ni les activités de maintenance ont réduit la couverture). Sous le paramètre par défaut, une couverture inférieure à complète retourne le code d’état HTTP 503.

Réduire minimumCoverage peut être utile si des erreurs 503 se produisent et que vous souhaitez augmenter la probabilité de réussite des requêtes, en particulier pour les services configurés pour un réplica. Si vous définissez minimumCoverage et La recherche réussit, elle retourne HTTP 200 et inclut une valeur @search.coverage dans la réponse indiquant le pourcentage de l’index inclus dans la requête. Dans ce scénario, tous les documents correspondants ne sont pas assurés d’être présents dans les résultats de recherche, mais si la disponibilité de la recherche est plus importante que le rappel, la réduction de la couverture peut être une stratégie d’atténuation viable.
$orderby corde Optionnel. Liste d’expressions séparées par des virgules pour trier les résultats. Lorsqu’il est appelé avec POST, ce paramètre est nommé orderby au lieu de $orderby. Chaque expression peut être un nom de champ ou un appel à la fonction geo.distance(). Chaque expression peut être suivie de « asc » pour indiquer croissant et « desc » pour indiquer la décroissante. S’il existe des valeurs Null dans le champ de tri, les valeurs Null apparaissent en premier dans l’ordre croissant et la dernière dans 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 existe une limite de 32 clauses pour $orderby.
queryLanguage (préversion) corde Optionnel. Les valeurs valides sont une langue prise en charge. La valeur par défaut est «en-us». Ce paramètre doit être défini si vous utilisez speller=lexicon ou queryType=semantic. Le langage spécifié dans queryLanguage est utilisé à la fois pour la vérification orthographique et par les modèles sémantiques qui reclassent les résultats et extraient une légende ou une réponse. Les bibliothèques utilisées pour queryLanguage sont indépendantes d’autres attributs de champ basés sur des paramètres régionaux, tels que analyseurs de langage utilisés pour l’indexation et la recherche en texte intégral.
queryType corde Optionnel. Les valeurs valides sont « simple », « full » ou « semantic » (préversion). La valeur par défaut est « simple ». Cette valeur est ignorée pour la recherche vectorielle, mais s’applique à la recherche de texte dans les scénarios hybrides.

« simple » interprète les chaînes de requête à l’aide de la syntaxe de requête simple qui permet des symboles tels que +, *et "". Les requêtes sont évaluées sur tous les champs pouvant faire l’objet d’une recherche (ou des champs indiqués dans searchFields) dans chaque document par défaut.

« full » interprète les chaînes de requête à l’aide de la syntaxe de requête Lucene complète complète qui permet des recherches spécifiques au champ et pondérées. La recherche de plages dans le langage de requête Lucene n’est pas prise en charge en faveur de $filter, qui offre des fonctionnalités similaires.

« sémantique » améliore la précision des résultats de recherche en reclassant les 50 premières correspondances à l’aide d’un modèle de classement formé sur le corpus Bing pour les requêtes exprimées en langage naturel par opposition aux mots clés. Si vous définissez le type de requête sur sémantique, vous devez également définir queryLanguage et semanticConfiguration. Vous pouvez éventuellement définir des réponses si vous souhaitez également renvoyer les 3 premières réponses si l’entrée de requête a été formulée en langage naturel (« qu’est-ce qu’un ...), et vous pouvez éventuellement définir des légendes pour extraire les passages clés des documents classés les plus élevés.
scoringParameter corde Optionnel. Indique les valeurs de chaque paramètre défini dans une fonction de scoring (par exemple, referencePointParameter) au format « name-value1,value2,... » Lorsqu’il est appelé avec POST, ce paramètre est nommé scoringParameters au lieu de scoringParameter. En outre, vous spécifiez-le en tant que tableau JSON de chaînes où chaque chaîne est une paire nom-valeurs distincte.

Pour les profils de scoring qui incluent une fonction, séparez la fonction de sa liste d’entrée par un caractère -. Par exemple, une fonction appelée "mylocation" serait «&scoringParameter=mylocation---122.2,44.8 ». Le premier tiret sépare le nom de la fonction de la liste des valeurs, tandis que le deuxième tiret fait partie de la première valeur (longitude dans cet exemple).

Pour les paramètres de scoring tels que l’amélioration des balises qui peuvent contenir des virgules, vous pouvez échapper à toutes ces valeurs dans la liste à l’aide de guillemets simples. Si les valeurs elles-mêmes contiennent des guillemets simples, vous pouvez les échapper en doublant. Supposons que vous disposez d’un paramètre d’amélioration de balise appelé "mytag" et que vous souhaitez augmenter les valeurs de balise « Hello, O’Brien » et « Smith », l’option de chaîne de requête serait alors «&scoringParameter=mytag-'Hello, O’Brien', Smith ». Les guillemets sont obligatoires uniquement pour les valeurs qui contiennent des virgules.
scoringProfile corde Optionnel. Nom d’un profil de scoring pour évaluer les scores de correspondance pour les documents correspondants afin de trier les résultats.
scoringStatistics corde Optionnel. Les valeurs valides sont « locales » ou « globales ». La valeur par défaut est « local ». Spécifiez s’il faut calculer des statistiques de scoring, telles que la fréquence de document, globalement (sur toutes les partitions) pour un scoring plus cohérent ou localement (sur la partition actuelle) pour une latence inférieure. Consultez statistiques de scoring dans azure AI Search. Les statistiques de scoring sont toujours calculées localement pour les termes qui utilisent recherche approximative ('~').
rechercher corde Optionnel. Texte à rechercher. Cette valeur est ignorée pour la recherche vectorielle, mais s’applique à la recherche de texte dans les scénarios hybrides. Dans les API REST, tous les champs pouvant faire l’objet d’une recherche sont recherchés par défaut, sauf si searchFields est spécifié. Dans l’index, le texte d’un champ pouvant faire l’objet d’une recherche est tokenisé, de sorte que plusieurs termes peuvent être séparés par un espace blanc (par exemple : « search=hello world »). Pour correspondre à n’importe quel terme, utilisez * (cela peut être utile pour les requêtes de filtre booléenne). L’omission de ce paramètre a le même effet que la définition de ce paramètre sur *. Consultez syntaxe de requête simple pour plus d’informations sur la syntaxe de recherche.

Résultats peut parfois être surprenant lors de l’interrogation de champs pouvant faire l’objet d’une recherche. Le tokenizer inclut une logique pour gérer les cas communs au texte anglais, comme les apostrophes, les virgules en nombres, etc. Par exemple, « search=123,456 » correspond à un seul terme « 123 456 » plutôt que les termes individuels « 123 » et « 456 », car les virgules sont utilisées comme séparateurs de milliers pour les grands nombres en anglais. Pour cette raison, nous vous recommandons d’utiliser de l’espace blanc plutôt que de la ponctuation pour séparer les termes dans le paramètre de recherche.
searchMode corde Optionnel. Les valeurs valides sont « any » ou « all » Par défaut sur « any ». Spécifie si l’un ou l’ensemble des termes de recherche doivent être mis en correspondance pour compter le document comme correspondance.
searchFields corde Optionnel. Liste des noms de champs séparés par des virgules pour rechercher le texte spécifié. Les champs cibles doivent être marqués comme pouvant faire l’objet d’une recherche dans le schéma d’index et doivent être de type Edm.String, Edm.ComplexTypeou Collection(Edm.String).
$select corde Optionnel. Liste des champs séparés par des virgules à inclure dans le jeu de résultats. Seuls les champs marqués comme récupérables peuvent être inclus dans cette clause. S’il n’est pas spécifié ou défini sur *, tous les champs marqués comme récupérables dans le schéma sont inclus dans la projection. Lorsqu’il est appelé avec POST, ce paramètre est nommé select au lieu de $select.
semanticConfiguration (préversion) corde Optionnel. Obligatoire si queryType="semantic ». Nom de la configuration sémantique qui répertorie les champs à utiliser pour le classement sémantique, les légendes, les mises en surbrillance et les réponses. Pour plus d’informations, consultez Créer une requête sémantique.
sessionId corde Optionnel. L’utilisation de sessionId permet d’améliorer la cohérence du score de pertinence pour les services de recherche avec plusieurs réplicas. Dans les configurations multi-réplicas, il peut y avoir de légères différences entre les scores de pertinence des documents individuels pour la même requête. Lorsqu’un ID de session est fourni, le service effectue un meilleur effort pour acheminer une demande donnée vers le même réplica pour cette session. Soyez prudent que la réutilisation des mêmes valeurs d’ID de session à plusieurs reprises peut interférer avec l’équilibrage de charge des requêtes entre les réplicas et affecter négativement les performances du service de recherche. La valeur utilisée en tant que sessionId ne peut pas commencer par un caractère '_'. Si un service n’a pas de réplicas, ce paramètre n’a aucun effet sur les performances ou la cohérence du score.
$skip entier Optionnel. Nombre de résultats de recherche à ignorer. Lorsqu’il est appelé avec POST, ce paramètre est nommé skip au lieu de $skip. Cette valeur ne peut pas être supérieure à 100 000. Si vous devez analyser des documents en séquence, mais que vous ne pouvez pas utiliser $skip en raison de cette limitation, envisagez d’utiliser $orderby sur un champ qui a des valeurs uniques pour chaque document dans l’index (comme la clé de document, par exemple) et $filter avec une requête de plage à la place.
orthographique (préversion) Corde Optionnel. Les valeurs valides sont « none » et « lexicon ». La valeur par défaut est « none ». Améliorez le rappel en corrigeant les termes de requête de recherche individuels. Vous pouvez l’utiliser sur des types de requêtes simples, complets et sémantiques. S’il est utilisé, le paramètre orthographique nécessite queryLanguage. Pour plus d’informations et d’exemples, consultez Ajouter une vérification orthographique aux requêtes.
$top entier Optionnel. Nombre de résultats de recherche à récupérer. Cette valeur par défaut est 50. Lorsqu’il est appelé avec POST, ce paramètre est nommé en haut au lieu de $top. Si vous spécifiez une valeur supérieure à 1 000 et qu’il y a plus de 1 000 résultats, seuls les 1000 premiers résultats sont retournés, ainsi qu’un lien vers la page suivante des résultats (voir « @odata.nextLink » dans l’exemple ci-dessous).

Recherche Azure AI utilise de pagination côté serveur pour empêcher les requêtes de récupérer trop de documents en même temps. La taille de page par défaut est 50, tandis que la taille maximale de la page est de 1 000. Cela signifie que par défaut, Recherche de documents retourne au maximum 50 résultats si vous ne spécifiez pas $top. S’il existe plus de 50 résultats, la réponse inclut des informations pour récupérer la page suivante d’au plus 50 résultats (voir « @odata.nextLink » et « @search.nextPageParameters » dans les exemples ci-dessous. De même, si vous spécifiez une valeur supérieure à 1 000 pour $top et qu’il y a plus de 1 000 résultats, seuls les 1 000 premiers résultats sont retournés, ainsi que des informations pour récupérer la page suivante d’au plus 1 000 résultats.
vectors (préversion) tableau Optionnel. Le type d’objet dans le tableau est une requête vectorielle. Paramètres de requête pour les requêtes vectorielles.

« valeur » est la représentation vectorielle d’une requête de recherche. Cette représentation doit être formée en externe. Azure AI Search ne crée pas d’incorporations.

« k » est un entier spécifiant le nombre de voisins les plus proches à retourner en tant que meilleurs résultats. La valeur par défaut est 50. Le minimum est 1 et le maximum est de 10 000.

« fields » est un nom de champ de liste délimité par des virgules contenant des données vectorielles. Seuls les champs de type Collection(Edm.Single) peuvent être inclus dans la liste « champs ».

Réponse

Code d’état : 200 OK est retourné pour une réponse réussie. Il existe deux exemples de réponses dans cet article, une pour la recherche sémantique et featuresMode.

Exemple de réponse pour la requête sémantique

Le premier exemple montre la réponse complète pour le résultat le plus élevé de la requête sémantique « how do clouds form ».

  • « @search.answers » s’affiche lorsque vous spécifiez le paramètre réponses, et lorsque la requête et les champs ciblés de l’index contiennent du contenu qui peut être reconnu comme une réponse. Tableau @search.answers qui a une clé, du texte et des surbrillances. Le score est un indicateur de la force de la réponse.

  • « value » est le corps de la réponse. Le @search.rerankerScore est attribué par l’algorithme de classement sémantique et est utilisé pour classer les résultats (@search.score provient de l’algorithme de similarité BM25, utilisé lors du scoring des résultats initiaux). Les légendes incluent du texte brut et des versions mises en surbrillance. Cet exemple a été créé à l’aide des compétences ocr et de reconnaissance d’entité. Les champs du contenu extrait et fusionné sont inclus dans la réponse.

{
    "@search.answers": [
        {
            "key": "aHR0cHM6Ly9oZWlkaXN0YmxvYnN0b3JhZ2UuYmxvYi5jb3JlLndpbmRvd3MubmV0L25hc2EtZWJvb2stMS01MC9wYWdlLTQ1LnBkZg2",
            "text": "Sunlight heats the land all day, warming that moist air and causing it to rise high into the atmosphere until it cools and condenses into water droplets. Clouds generally form where air is ascending (over land in this case),   but not where it is descending (over the river).",
            "highlights": "Sunlight heats the land all day, warming that moist air and causing it to rise high into the   atmosphere until it cools and condenses into water droplets. Clouds generally form<em> where air is ascending</em> (over land in this case),   but not where it is<em> descending</em> (over the river).",
            "score": 0.94639826
        }
    ],
    "value": [
        {
            "@search.score": 0.5479723,
            "@search.rerankerScore": 1.0321671911515296,
            "@search.captions": [
                {
                    "text": "Like all clouds, it forms when the air reaches its dew point—the temperature at which an air mass is cool enough for its water vapor to condense into liquid droplets. This false-color image shows valley fog, which is common in the Pacific Northwest of North America.",
                    "highlights": "Like all<em> clouds</em>, it<em> forms</em> when the air reaches its dew point—the temperature at    which an air mass is cool enough for its water vapor to condense into liquid droplets. This false-color image shows valley<em> fog</em>, which is common in the Pacific Northwest of North America."
                }
            ],
            "content": "\nA\nT\n\nM\nO\n\nS\nP\n\nH\nE\n\nR\nE\n\nE\nA\n\nR\nT\n\nH\n\n34\n\nValley Fog\nCanada\n\nFog is essentially a cloud lying on the ground. Like all clouds, it forms when the air reaches its dew point—the temperature at  \n\nwhich an air mass is cool enough for its water vapor to condense into liquid droplets.\n\nThis false-color image shows valley fog, which is common in the Pacific Northwest of North America. On clear winter nights, the \n\nground and overlying air cool off rapidly, especially at high elevations. Cold air is denser than warm air, and it sinks down into the \n\nvalleys. The moist air in the valleys gets chilled to its dew point, and fog forms. If undisturbed by winds, such fog may persist for \n\ndays. The Terra satellite captured this image of foggy valleys northeast of Vancouver in February 2010.\n\n\n",
            "metadata_storage_path": "aHR0cHM6Ly9oZWlkaXN0YmxvYnN0b3JhZ2UuYmxvYi5jb3JlLndpbmRvd3MubmV0L25hc2EtZWJvb2stMS01MC9wYWdlLTQxLnBkZg2",
            "people": [],
            "locations": [
                "Pacific Northwest",
                "North America",
                "Vancouver"
            ],
            "merged_content": "\nA\nT\n\nM\nO\n\nS\nP\n\nH\nE\n\nR\nE\n\nE\nA\n\nR\nT\n\nH\n\n34\n\nValley Fog\nCanada\n\nFog is essentially a cloud lying on the ground. Like all clouds, it forms when the air reaches its dew point—the temperature at  \n\nwhich an air mass is cool enough for its water vapor to condense into liquid droplets.\n\nThis false-color image shows valley fog, which is common in the Pacific Northwest of North America. On clear winter nights, the \n\nground and overlying air cool off rapidly, especially at high elevations. Cold air is denser than warm air, and it sinks down into the \n\nvalleys. The moist air in the valleys gets chilled to its dew point, and fog forms. If undisturbed by winds, such fog may persist for \n\ndays. The Terra satellite captured this image of foggy valleys northeast of Vancouver in February 2010.\n\n\n",
            "text": [],
            "layoutText": []
        }
    ]
}

Exemple de réponse pour featuresMode

Cet exemple montre la sortie « @search.features » d’une requête qui inclut featuresMode.

  {
    "@odata.count": # (if $count=true was provided in the query),
    "@search.coverage": # (if minimumCoverage was provided in the query),
    "@search.facets": { (if faceting was specified in the query)
      "facet_field": [
        {
          "value": facet_entry_value (for non-range facets),
          "from": facet_entry_value (for range facets),
          "to": facet_entry_value (for range facets),
          "count": number_of_documents
        }
      ],
      ...
    },
    "@search.nextPageParameters": { (request body to fetch the next page of results if not all results could be returned in this response and Search was called with POST)
      "count": ... (value from request body if present),
      "facets": ... (value from request body if present),
      "featuresMode" : ... (value from request body if present),
      "filter": ... (value from request body if present),
      "highlight": ... (value from request body if present),
      "highlightPreTag": ... (value from request body if present),
      "highlightPostTag": ... (value from request body if present),
      "minimumCoverage": ... (value from request body if present),
      "orderby": ... (value from request body if present),
      "scoringParameters": ... (value from request body if present),
      "scoringProfile": ... (value from request body if present),
      "scoringStatistics": ... (value from request body if present),
      "search": ... (value from request body if present),
      "searchFields": ... (value from request body if present),
      "searchMode": ... (value from request body if present),
      "select": ... (value from request body if present),
      "sessionId" : ... (value from request body if present),
      "skip": ... (page size plus value from request body if present),
      "top": ... (value from request body if present minus page size),
    },
    "value": [
      {
        "@search.score": document_score (if a text query was provided),
        "@search.highlights": {
          field_name: [ subset of text, ... ],
          ...
        },
        "@search.features": {
          "field_name": {
            "uniqueTokenMatches": feature_score,
            "similarityScore": feature_score,
            "termFrequency": feature_score,
          },
          ...
        },
        key_field_name: document_key,
        field_name: field_value (retrievable fields or specified projection),
        ...
      },
      ...
    ],
    "@odata.nextLink": (URL to fetch the next page of results if not all results could be returned in this response; Applies to both GET and POST)
  }

Exemples

Vous trouverez d’autres exemples dans syntaxe d’expression OData pour azure AI Search.

exemple : de recherche simple

Recherchez des documents dans l’index à l’aide de la syntaxe de requête simple. Cette requête retourne les hôtels où les champs pouvant faire l’objet d’une recherche contiennent les termes « confort » et « location », mais pas « motel » :

Get /indexes/hotels/docs?search=comfort +location –motel&searchMode=all&api-version=2021-04-30-Preview
POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "comfort +location -motel",  
      "searchMode": "all"  
    }  

Pourboire

L’utilisation de searchMode=all remplace la valeur par défaut de searchMode=any, ce qui garantit que -motel signifie « AND NOT » au lieu de « OR NOT ». Sans searchMode=all, vous obtenez « OR NOT » qui s’étend au lieu de restreindre les résultats de recherche, et cela peut être contre-intuitif pour certains utilisateurs.

exemple : de recherche Lucene complète

Recherchez des documents dans l’index à l’aide de la syntaxe de requête Lucene (consultez syntaxe de requête Lucene dans recherche Azure AI). Cette requête retourne les hôtels où le champ catégorie contient le terme « budget » et tous les champs pouvant faire l’objet d’une recherche contenant l’expression « récemment rénové ». Les documents contenant l’expression « récemment rénové » sont classés plus hauts en raison de la valeur d’augmentation du terme (3)

GET /indexes/hotels/docs?search=Category:budget AND \"recently renovated\"^3&searchMode=all&api-version=2021-04-30-Preview&querytype=full`
POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "Category:budget AND \"recently renovated\"^3",  
      "queryType": "full",  
      "searchMode": "all"  
}  

exemple : de recherche sémantique

Appelez le modèle de classement sémantique avec des réponses, des légendes et du contenu mis en surbrillance. La réponse de cette requête se trouve dans la section précédente.

POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
{
  "search": "how do clouds form",
  "queryType": "semantic",
  "semanticConfiguration": "my-semantic-config",
  "queryLanguage": "en-us",
  "answers": "extractive",
  "captions": "extractive",
  "count": "true"
}

exemple : de recherche vectorielle

Pour un index qui a des champs de type Collection(Edm.Single) et une configuration vectorielle, vous pouvez spécifier des paramètres de requête vectorielle. Les paramètres de requête vectorielle incluent les champs vectoriels qui sont dans l’étendue de la requête, le nombre « k » de correspondances principales à retourner et une représentation vectorielle de l’entrée de requête.

L’ajout d’un paramètre « select » est utile si l’index inclut des champs de texte. La correspondance et la pertinence sont basées sur des vecteurs, mais les champs contenant du contenu lisible par l’homme sont plus utiles à quelqu’un qui lit les résultats. Vous pouvez également écrire du code qui convertit les données vectorielles dans vos résultats de recherche en texte.

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version={{api-version}}
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "search": (this parameter is ignored in vector search),
    "vectors": [{
        "value": [
            -0.009154141,
            0.018708462,
            . . . 
            -0.02178128,
            -0.00086512347
        ],
        "fields": "contentVector",
        "k": 5
    }],
    "select": "title, content, category"
}

exemple : orderby

Recherchez l’index et retournez les résultats triés par date dans l’ordre décroissant.

GET /indexes/hotels/docs?search=*&$orderby=LastRenovationDate desc&api-version=2021-04-30-Preview
POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "*",  
      "orderby": "LastRenovationDate desc"
    }  

Exemple : filtrer à l’aide d’une expression OData

Récupérer des documents correspondant à une expression de filtre spécifique :

GET /indexes/hotels/docs?$filter=(Rooms/BaseRate ge 60 and Rooms/BaseRate lt 300) or HotelName eq 'Fancy Stay'&api-version=2021-04-30-Preview
POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "filter": "(Rooms/BaseRate ge 60 and Rooms/BaseRate lt 300) or HotelName eq 'Fancy Stay'"  
    }  

exemple : de recherche à facettes

Dans une recherche à facettes, recherchez l’index et récupérez des facettes pour les catégories, les évaluations, les balises, ainsi que les éléments avec baseRate dans des plages spécifiques.

GET /indexes/hotels/docs?search=*&facet=Category&facet=Rating&facet=Tags&facet=Rooms/BaseRate,values:80|150|220&api-version=2021-04-30-Preview
POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "test",  
      "facets": [ "Category", "Rating", "Tags", "Rooms/BaseRate,values:80|150|220" ]  
    }  

Notez que la dernière facette se trouve sur un sous-champ. Les facettes comptent le document parent (Hôtels) et non les sous-documents intermédiaires (Chambres), de sorte que la réponse détermine le nombre d’hôtels qui ont des chambres dans chaque compartiment de prix.

exemple : Affiner une requête à facettes

À l’aide d’un filtre, limitez le résultat de la requête à facettes précédente après que l’utilisateur sélectionne l’évaluation 3 et la catégorie « Motel ».

GET /indexes/hotels/docs?search=*&facet=tags&facet=Rooms/BaseRate,values:80|150|220&$filter=Rating eq 3 and Category eq 'Motel'&api-version=2021-04-30-Preview  
POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview 
    {  
      "search": "test",  
      "facets": [ "tags", "Rooms/BaseRate,values:80|150|220" ],  
      "filter": "Rating eq 3 and Category eq 'Motel'"  
    }  

Exemple : recherche à facettes avec des limites pour chaque catégorie

Dans une recherche à facettes, définissez une limite supérieure sur les termes uniques retournés dans une requête. La valeur par défaut est 10, mais vous pouvez augmenter ou diminuer cette valeur à l’aide du paramètre count sur l’attribut de facette. Cet exemple retourne des facettes pour la ville, limitée à 5.

GET /indexes/hotels/docs?search=*&facet=Address/City,count:5&api-version=2021-04-30-Preview
POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "test",  
      "facets": [ "Address/City,count:5" ]  
    }  

exemple : de recherche dans le champ

Recherchez l’index dans des champs spécifiques (par exemple, un champ de langue)

GET /indexes/hotels/docs?search=hôtel&searchFields=Description_fr&api-version=2021-04-30-Preview
POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "hôtel",  
      "searchFields": "Description_fr"
    }  

Recherchez l’index sur plusieurs champs. Par exemple, vous pouvez stocker et interroger des champs pouvant faire l’objet d’une recherche dans plusieurs langues, dans le même index. Si les descriptions anglaises et françaises coexistent dans le même document, vous pouvez renvoyer tout ou partie des résultats de la requête :

GET /indexes/hotels/docs?search=hotel&searchFields=Description,Description_fr&api-version=2021-04-30-Preview
POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "hotel",  
      "searchFields": "Description, Description_fr"
    }  

Vous ne pouvez interroger qu’un seul index à la fois. Ne créez pas plusieurs index pour chaque langue, sauf si vous envisagez d’en interroger un à la fois.

exemple : pagination des résultats

Obtenez la première page des éléments (la taille de la page est 10) :

GET /indexes/hotels/docs?search=*&$skip=0&$top=10&api-version=2021-04-30-Preview
POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "*",  
      "skip": 0,  
      "top": 10  
    }  

Obtenez la deuxième page d’éléments (la taille de la page est de 10) :

GET /indexes/hotels/docs?search=*&$skip=10&$top=10&api-version=2021-04-30-Preview
POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "*",  
      "skip": 10,  
      "top": 10  
    }  

exemple : limiter les champs d’un jeu de résultats

Récupérez un ensemble spécifique de champs :

GET /indexes/hotels/docs?search=*&$select=HotelName,Description&api-version=2021-04-30-Preview
POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "*",  
      "select": "HotelName, Description"
    }  

exemple : mise en surbrillance des résultats dans les résultats

Recherchez l’index et retournez des fragments avec des surbrillances d’accès :

GET /indexes/hotels/docs?search=something&highlight=Description&api-version=2021-04-30-Preview
POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "something",  
      "highlight": "Description"  
    }  

exemple : de recherche géospatiale

Recherchez l’index et retournez des documents triés de plus près d’un emplacement de référence :

GET /indexes/hotels/docs?search=something&$orderby=geo.distance(Location, geography'POINT(-122.12315 47.88121)')&api-version=2021-04-30-Preview
POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "something",  
      "orderby": "geo.distance(Location, geography'POINT(-122.12315 47.88121)')"
    }  

Exemple : « trouver par moi » (améliorer la pertinence des emplacements proches

Recherchez l’index en supposant qu’il existe un profil de scoring appelé « geo » avec deux fonctions de scoring de distance, l’une définissant un paramètre appelé « currentLocation » et l’autre définissant un paramètre appelé « lastLocation ». Dans l’exemple suivant, « currentLocation » a un délimiteur d’un tiret unique (-). Elle est suivie des coordonnées longitude et latitude, où la longitude est une valeur négative.

GET /indexes/hotels/docs?search=something&scoringProfile=geo&scoringParameter=currentLocation--122.123,44.77233&scoringParameter=lastLocation--121.499,44.2113&api-version=2021-04-30-Preview
POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "something",  
      "scoringProfile": "geo",  
      "scoringParameters": [ "currentLocation--122.123,44.77233", "lastLocation--121.499,44.2113" ]  
    }  

Exemple : interroger sur l’index complet au lieu de partitions

Recherchez des documents dans l’index tout en favorisant le scoring cohérent sur une latence inférieure. Cette requête calcule les fréquences de document sur l’index entier et fait un meilleur effort pour cibler le même réplica pour toutes les requêtes au sein de la même « session », ce qui permet de générer un classement stable et reproductible.

GET /indexes/hotels/docs?search=hotel&sessionId=mySessionId&scoringStatistics=global&api-version=2021-04-30-Preview
POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "hotel",  
      "sessionId": "mySessionId",
      "scoringStatistics" :"global"
    }  

Exemple : statistiques de scoring (featuresMode)

Recherchez des documents dans l’index et retournez une liste des fonctionnalités de récupération d’informations pour chaque résultat décrivant le scoring entre le document correspondant et la requête. La requête calcule également les fréquences de document sur l’index entier pour produire un scoring plus cohérent.

GET /indexes/hotels/docs?search=hotel&featuresMode=enabled&scoringStatistics=global&api-version=2021-04-30-Preview
POST /indexes/hotels/docs/search?api-version=2021-04-30-Preview
    {  
      "search": "hotel",  
      "featuresMode": "enabled",
      "scoringStatistics" :"global"
    }  

Voici un exemple de réponse qui inclut search.features ressemble à ce qui suit :

    "@search.score": 0.91875637,
    "@search.features": {
        "Description": {
            "uniqueTokenMatches": 1,
            "similarityScore": 0.2917966,
            "termFrequency": 2
        },
        "HotelName": {
            "uniqueTokenMatches": 1,
            "similarityScore": 0.44458693,
            "termFrequency": 1
        }
      . . .

Définitions

Cette section fournit des détails sur les paramètres trop complexes à couvrir dans la table principale.

Lien Description
queryLanguage Liste des langues prises en charge pour la recherche orthographique et sémantique.

queryLanguage

Les valeurs valides pour le paramètre queryLanguage sont fournies dans le tableau suivant, dans la colonne « queryLanguage » et ne respectent pas la casse. La valeur par défaut du paramètre dans son ensemble est «en-us». Dans chaque langue, il existe une variante par défaut pour chaque code de langue à deux caractères. Par exemple, si vous spécifiez « es », «es-us» est utilisé par défaut. Le paramètre queryLanguage est requis pour une requête qui inclut « queryType=semantic » ou « speller=lexicon ». Il n’existe qu’une seule valeur queryLanguage pour l’ensemble de la requête, et cette valeur sera utilisée pour le classement sémantique, les légendes, les réponses et l’orthographique (il n’existe aucun remplacement pour les fonctionnalités individuelles).

À ce stade, la prise en charge linguistique varie selon la fonctionnalité. Seuls l’anglais, l’espagnol, le français et l’allemand sont pris en charge pour l’ensemble complet des fonctionnalités, mais notez que la vérification orthographique implémente moins de variantes.

Si vous spécifiez un code de langue qui n’est pas pris en charge par une fonctionnalité donnée, par exemple EN-GB avec l’orthographique, le service retourne HTTP 400.

Pour plus d’informations sur l’utilisation de chaque fonctionnalité, consultez Activer le classement sémantique et les légendes, renvoyer une réponse sémantiqueet Ajouter une vérification orthographique aux requêtes.

La désignation « (préversion) » indique que le test de validation sur toutes les fonctionnalités (classement sémantique, légendes, réponses et vérification orthographique) est en cours ou en attente. Nous encourageons l’utilisation de toutes les variantes de langue dans le tableau suivant, mais vous recommandons de tester davantage les langues d’aperçu pour vous assurer que les résultats sont valides pour votre contenu. Les langues avec une coche et aucune désignation en préversion n’ont été validées à l’aide de jeux de données équivalents, avec un gain mesurable en pertinence.

Langue queryLanguage Classement sémantique et légendes Réponse sémantique Speller
Anglais [en] en, en-US (valeur par défaut), en-GB, en-IN, en-CA, en-AU ✔️ ✔️ ✔️ (en, en-US)
Français [fr] fr, fr-FR (valeur par défaut), fr-CA ✔️ ✔️ ✔️ (fr, fr-FR)
Allemand [de] de, de-DE (par défaut) ✔️ ✔️ ✔️ (de, de-DE)
Espagnol [es] es, es-ES (valeur par défaut), es-MX ✔️ ✔️ ✔️ (es, es-ES)
Italien [it] it, it-IT (par défaut) ✔️ ✔️
Japonais [ja] ja, ja-JP (par défaut) ✔️ ✔️ (préversion)
Chinois [zh] zh, zh-CN (valeur par défaut), zh-TW ✔️ ✔️ (préversion)
Portugais [pt] pt, pt-BR (valeur par défaut), pt-PT ✔️ ✔️ (préversion)
Néerlandais [nl] nl, nl-BE, nl-NL (par défaut) ✔️ (préversion) ✔️ (préversion) ✔️ (nl, nl-NL)
Arabe [ar] ar, ar-SA (valeur par défaut), ar-EG, ar-MA, ar-KW, ar-JO ✔️ (préversion) ✔️ (préversion)
Arménien hy-AM (par défaut) ✔️ (préversion) ✔️ (préversion)
Bangla bn-IN (par défaut) ✔️ (préversion) ✔️ (préversion)
Basque eu-ES (par défaut) ✔️ (préversion) ✔️ (préversion)
Bulgare [bg] bg, bg-BG (par défaut) ✔️ (préversion) ✔️ (préversion)
Catalan [ca] ca, ca-ES (par défaut) ✔️ (préversion) ✔️ (préversion)
Croate [hr] hr, hr-HR (valeur par défaut), hr-BA ✔️ (préversion) ✔️ (préversion)
Tchèque [cs] cs, cs-CZ (par défaut) ✔️ (préversion) ✔️ (préversion)
Danois [da] da, da-DK (par défaut) ✔️ (préversion) ✔️ (préversion)
Estonien [et] et, et-EE (par défaut) ✔️ (préversion) ✔️ (préversion)
Finnois [fi] fi, fi-FI (par défaut) ✔️ (préversion) ✔️ (préversion)
Galicien gl-ES (par défaut) ✔️ (préversion) ✔️ (préversion)
Grec [el] el, el-GR (par défaut) ✔️ (préversion) ✔️ (préversion)
Gujarâtî gu-IN (par défaut) ✔️ (préversion) ✔️ (préversion)
Hébreu he-IL (par défaut) ✔️ (préversion) ✔️ (préversion)
Hindi [hi] hi, hi-IN (par défaut) ✔️ (préversion) ✔️ (préversion)
Hongrois [hu] hu, hu-HU (par défaut) ✔️ (préversion) ✔️ (préversion)
Islandais [is] is, is-IS (par défaut) ✔️ (préversion) ✔️ (préversion)
Indonésien [id] id, id-ID (par défaut) ✔️ (préversion) ✔️ (préversion)
Irlandais ga-IE (par défaut) ✔️ (préversion) ✔️ (préversion)
Canara kn-IN (par défaut) ✔️ (préversion) ✔️ (préversion)
Coréen [ko] ko, ko-KR (par défaut) ✔️ (préversion) ✔️ (préversion)
Letton [lv] lv, lv-LV (par défaut) ✔️ (préversion) ✔️ (préversion)
Lituanien [lt] lt, lt-LT (par défaut) ✔️ (préversion) ✔️ (préversion)
Malayalam ml-IN (par défaut) ✔️ (préversion) ✔️ (préversion)
Malaisien [ms] ms, ms-MY (valeur par défaut), ms-BN ✔️ (préversion) ✔️ (préversion)
Marathi mr-IN (par défaut) ✔️ (préversion) ✔️ (préversion)
Norvégien [no] non, no-NO (valeur par défaut), nb-NO ✔️ (préversion) ✔️ (préversion)
Perse fa-AE (par défaut) ✔️ (préversion) ✔️ (préversion)
Polonais [pl] pl, pl-PL (par défaut) ✔️ (préversion) ✔️ (préversion)
Punjabi pa-IN (par défaut) ✔️ (préversion) ✔️ (préversion)
Roumain [ro] ro, ro-RO (par défaut) ✔️ (préversion) ✔️ (préversion)
Russe [ru] ru, ru-RU (par défaut) ✔️ (préversion) ✔️ (préversion)
Serbe [sr] (cyrillique ou latin) sr, sr-BA (valeur par défaut), sr-ME, sr-RS ✔️ (préversion) ✔️ (préversion)
Slovaque [sk] sk, sk-SK (par défaut) ✔️ (préversion) ✔️ (préversion)
Slovène [sl] sl, sl-SL (par défaut) ✔️ (préversion) ✔️ (préversion)
Tamoul [ta] ta, ta-IN (par défaut) ✔️ (préversion) ✔️ (préversion)
Suédois [sv] sv, sv-SE (par défaut) ✔️ (préversion) ✔️ (préversion)
Telugu te-IN (par défaut) ✔️ (préversion) ✔️ (préversion)
Thaï [th] th, th-TH (par défaut) ✔️ (préversion) ✔️ (préversion)
Turc [tr] tr, tr-TR (par défaut) ✔️ (préversion) ✔️ (préversion)
Ukrainien [uk] uk, uk-UA (par défaut) ✔️ (préversion) ✔️ (préversion)
Urdu ur-PK (par défaut) ✔️ (préversion) ✔️ (préversion)
Vietnamien [va] va, vi-VN (par défaut) ✔️ (préversion) ✔️ (préversion)

Voir aussi