Rechercher dans des documents (API REST Azure AI Search)

Article
11/13/2023

Une demande de 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 des paramètres qui façonnent la réponse. À compter de la version 2021-04-30-Preview de l’API, 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. Les 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 « rechercher » 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 généralement 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 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. Même si la limite de taille de requête POST est élevée, 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é.
[paramètres de requête]	Les paramètres de requête sont spécifiés dans l’URI des requêtes GET et dans le corps de la requête pour les requêtes POST.
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 une opération de recherche de documents , l’encodage d’URL peut être nécessaire pour les paramètres de requête suivants :

recherche
$filter
facet
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’utilisation de POST, ou lors de l’utilisation de la bibliothèque cliente .NET recherche Azure AI, qui gère l’encodage 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éfinissez ce paramètre sur « 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é .

Champs

Description

Content-Type

Obligatoire. Définissez ce paramètre sur « 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 :

{  
     "count": true | false (default),  
     "facets": [ "facet_expression_1", "facet_expression_2", ... ],  
     "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",  
     "queryType": "simple" (default) | "full",
     "scoringParameters": [ "scoring_parameter_1", "scoring_parameter_2", ... ],  
     "scoringProfile": "scoring_profile_name",  
     "scoringStatistics" : "local" | "global",
     "search": "simple_query_expression",  
     "searchFields": "field_name_1, field_name_2, ...",  
     "searchMode": "any" (default) | "all",  
     "select": "field_name_1, field_name_2, ...",  
     "sessionId" : "session_id",
     "skip": # (default 0),  
     "top": #  
   }

Continuation des réponses de recherche partielle

Parfois, Azure AI Search ne peut pas retourner tous les résultats demandés dans une seule réponse de recherche. Cela peut se produire pour différentes raisons, par exemple lorsque la requête nécessite un trop grand nombre de documents en ne spécifiant pas $top ou en spécifiant une valeur pour $top qui est trop grande. Dans ce cas, Azure AI Search inclut l’annotation @odata.nextLink dans le corps de la réponse, ainsi @search.nextPageParameters que s’il s’agissait d’une requête POST. Vous pouvez utiliser les valeurs de ces annotations pour formuler une autre demande de recherche afin d’obtenir la partie suivante de la réponse de recherche. Il s’agit d’une continuation de la demande de recherche d’origine et les annotations sont généralement appelées jetons de continuation. Consultez l’exemple dans Réponse ci-dessous 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 d’être modifiées. Les clients puissants doivent toujours être prêts à traiter des cas où des documents plus moins nombreux que prévu sont renvoyés et un jeton de continuation est inclus pour poursuivre la récupération des documents. Notez également que vous devez utiliser la même méthode HTTP que pour la demande d’origine pour pouvoir poursuivre. Par exemple, si vous avez envoyé une demande GET, toutes les demandes de continuation que vous envoyez doivent également utiliser GET (y compris pour POST).

Notes

L’objectif de et @search.nextPageParameters est de @odata.nextLink 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 requête doit avoir $top=10 et $skip=0, la deuxième requête doit avoir $top=10 et $skip=10, la troisième requête doit avoir $top=10 et , et $skip=20ainsi 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 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 URI, que vous appeliez rechercher des documents avec GET ou POST.
`$count`	boolean	facultatif. 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é count au lieu de `$count`. Spécifie s'il faut extraire le nombre total de résultats. Il s’agit du nombre de tous les documents qui correspondent aux paramètres de recherche et de $filter, en `$top` ignorant 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 qu’il sous-signale ou sur-signale 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.
facette ou facettes	string	facultatif. Champ à facettes par, où le champ est attribué comme « facetable ». Lorsqu’il est appelé 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 les facettes, exprimées sous forme de paires nom-valeur séparées par des virgules. Les paramètres 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 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 la facette. Si le paramètre count est inférieur au nombre de termes uniques, les résultats peuvent ne pas être exacts. Cela s'explique par la manière dont les requêtes de facettes sont distribuées entre les partitions. Vous pouvez définir nombre sur zéro ou sur une valeur supérieure ou égale au nombre de valeurs uniques dans le champ facetable pour obtenir un nombre précis sur toutes les partitions. Le compromis est une latence accrue. « sort » peut être défini sur « count », « -count », « value », « -value ». Utilisez count pour trier la décroissante par nombre. Utilisez -count pour trier l’ordre croissant par nombre. Utilisez la valeur pour trier l’ordre croissant par valeur. Utilisez -value pour trier décroissant par valeur (par exemple, « facet=category,count :3,sort :count » obtient les trois premières catégories dans les résultats de la facette dans l’ordre décroissant par nombre de documents avec chaque nom de ville). Si les trois premières catégories sont Budget, Motel et Luxe, et Budget a 5 hits, Motel en a 6 et Luxe a 4, 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 être défini sur des valeurs numériques délimitées par le canal ou des valeurs 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 : l’un pour les hôtels rénovés avant février 2010 et l’autre pour les hôtels rénovés le 1er février 2010 ou une 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 date-heure. Par exemple, « facet=baseRate,interval :100 » produit des compartiments basés sur des plages de débit de base de taille 100. Si les tarifs de base sont tous 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 où les hôtels ont été rénovés. « timeoffset » peut être défini sur ([+-]hh :mm, [+-]hhmm ou [+-]hh). S’il est utilisé, le paramètre timeoffset doit être combiné avec 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 lors de 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). le nombre et le 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 ensemble. Les facettes d’intervalle sur la date heure sont calculées en fonction de l’heure UTC si timeoffset n’est pas spécifié. Par exemple : pour « facet=lastRenovationDate,interval :day », la limite du jour commence à 00 :00 :00 UTC.
$filter	string	facultatif. Expression de recherche structurée dans une syntaxe d'OData standard. Seuls les champs filtrables peuvent être utilisés dans un filtre. Lorsque vous appelez 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 .
highlight	string	facultatif. Ensemble de noms de champ séparés par des virgules, utilisés pour les surlignages de correspondances. 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, Recherche Ai Azure retourne jusqu’à 5 mises en évidence par champ. La limite est configurable par champ en ajoutant « -<max # of highlights> » en suivant le nom du champ. Par exemple, « highlight=title-3,description-10 » renvoie jusqu’à 3 accès en surbrillance à partir du champ de titre et jusqu’à 10 résultats du champ description. Le nombre maximal de surbrillances doit être un entier compris entre 1 et 1000 inclus.
highlightPostTag	string	facultatif. 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 codés en pourcentage (par exemple, %23 au lieu de #).
highlightPreTag	string	facultatif. La valeur par défaut est `"</em>"`. Balise de chaîne qui est ajoutée au terme mis en surbrillance. Doit être défini avec highlightPostTag. Les caractères réservés dans l'URL doivent être codés en pourcentage (par exemple, %23 au lieu de #).
minimumCoverage	entier	facultatif. Les valeurs valides sont un 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 comme une réussite. La valeur par défaut est « 100 ». Une couverture à 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 n’ont réduit la couverture). Sous le paramètre par défaut, une couverture inférieure à complète retourne le code HTTP status 503. La réduction de 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 une réplica. Si vous définissez minimumCoverage et que la recherche réussit, elle retourne HTTP 200 et inclut une @search.coverage valeur dans la réponse indiquant le pourcentage de l’index inclus dans la requête. Dans ce scénario, il n’est pas garanti que tous les documents correspondants soient 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 constituer une stratégie d’atténuation viable.
$orderby	string	facultatif. Liste séparée par des virgules des expressions sur la base desquelles 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 la montée et de « 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 en dernier 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 est décroissant par score de correspondance de document. Il existe une limite de 32 clauses pour $orderby.
queryType	string	facultatif. Les valeurs valides sont « simple » ou « full ». La valeur par défaut est « simple ». « simple » interprète les chaînes de requête à l’aide de la syntaxe de requête simple qui autorise les symboles tels que `+`, `*` et `""`. Les requêtes sont évaluées sur tous les champs pouvant faire l’objet d’une recherche (ou les champs indiqués dans searchFields) de 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 qui permet des recherches spécifiques aux champs et pondérées. La recherche par plage dans le langage de requête Lucene n’est pas prise en charge en faveur de $filter, qui offre des fonctionnalités similaires.
scoringParameter	string	facultatif. Indique les valeurs de chaque paramètre défini dans une fonction de scoring (telle que 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 le spécifiez comme un 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 de 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 pour l’augmentation des balises qui peuvent contenir des virgules, vous pouvez placer ces valeurs dans la liste dans une séquence d’échappement à l’aide de guillemets simples. Si les valeurs elles-mêmes contiennent des guillemets simples, vous pouvez les ignorer en les doublant. Supposons que vous ayez un paramètre de renforcement de balise appelé `"mytag"` et que vous souhaitiez 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 uniquement requis pour les valeurs qui contiennent des virgules.
scoringProfile	string	facultatif. Nom du profil de calcul de score utilisé pour évaluer les scores de correspondance des documents correspondants afin de trier les résultats.
scoringStatistics	string	facultatif. Les valeurs valides sont « local » ou « global ». La valeur par défaut est « local ». Spécifiez s’il faut calculer les statistiques de scoring, telles que la fréquence des documents, globalement (sur toutes les partitions) pour un scoring plus cohérent, ou localement (sur la partition actuelle) pour une latence plus faible. Consultez Statistiques de scoring dans Azure AI Search. Les statistiques de scoring sont toujours calculées localement pour les termes qui utilisent la recherche approximative ('~').
recherche	string	facultatif. Texte à rechercher. 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 faire correspondre n'importe quel terme, utilisez `` (ce qui peut être utile pour les requêtes de filtre booléen). L'omission de ce paramètre a le même effet que s'il est défini avec la valeur ``. Pour plus d’informations sur la syntaxe de recherche, consultez Syntaxe de requête simple . Les résultats peuvent parfois être surprenants lors de l’interrogation de champs pouvant faire l’objet d’une recherche. Le générateur de jetons inclut une logique permettant de gérer les cas couramment rencontrés dans du texte en anglais, tels que les apostrophes, les virgules des nombres, et ainsi de suite. 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 des espaces blancs plutôt que de la ponctuation pour séparer les termes dans le paramètre de recherche.
searchMode	string	facultatif. Les valeurs valides sont « any » ou « all » Par défaut, « any ». Indique si tous les termes recherchés ou l'un d'eux doivent correspondre pour que le document soit considéré comme une correspondance.
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 marqués comme pouvant faire l’objet d’une recherche dans le schéma d’index.
$select	string	facultatif. 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. Si la valeur n'est pas spécifiée ou est `*`, 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.
sessionID	string	facultatif. 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éplica, 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 fait tout son possible pour acheminer une demande donnée vers le même réplica pour cette session. Veillez à ce que la réutilisation répétée des mêmes valeurs d’ID de session puisse interférer avec l’équilibrage de charge des requêtes entre les réplicas et nuire aux performances du service de recherche. La valeur utilisée comme 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	facultatif. 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 dans l’ordre, 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.
$top	entier	facultatif. Nombre de résultats de recherche à récupérer. Par défaut, la valeur est 50. Lorsqu’il est appelé avec POST, ce paramètre est nommé top au lieu de `$top`. Si vous spécifiez une valeur supérieure à 1000 et qu’il y a plus de 1 000 résultats, seuls les 1 000 premiers résultats sont retournés, ainsi qu’un lien vers la page de résultats suivante (voir @odata.nextLink dans l’exemple ci-dessous). Azure AI Search utilise la pagination côté serveur pour empêcher les requêtes de récupérer un trop grand nombre de documents à la fois. La taille de page par défaut est 50, tandis que la taille de page maximale est 1 000. Cela signifie que, par défaut , la recherche dans les documents retourne au plus 50 résultats si vous ne spécifiez `$top`pas . S’il existe plus de 50 résultats, la réponse inclut des informations permettant de 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 les informations permettant de récupérer la page suivante d’au plus 1 000 résultats.

response

Code d'état : 200 OK est retourné pour une réponse correcte.

  {
    "@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),
      "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 Recherche Azure AI.

Rechercher dans l'index trié par ordre décroissant des dates :

GET /indexes/hotels/docs?search=*&$orderby=LastRenovationDate desc&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "*",  
      "orderby": "LastRenovationDate desc"
    }

Dans une recherche à facettes, recherchez l’index et récupérez des facettes pour les catégories, les évaluations, les étiquettes et 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=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "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.

À l’aide d’un filtre, réduisez le résultat de la requête à facettes précédente après que l’utilisateur a sélectionné Rating 3 et 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=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "test",  
      "facets": [ "tags", "Rooms/BaseRate,values:80|150|220" ],  
      "filter": "Rating eq 3 and Category eq 'Motel'"  
    }

Dans une recherche à facettes, définir une limite supérieure sur des termes uniques retournés dans une requête. La valeur par défaut est 10, mais vous pouvez l'augmenter ou la diminuer en utilisant le paramètre count sur l'attribut de facette. Cet exemple renvoie pour Ville des facettes dont le nombre est limité à 5.
```
GET /indexes/hotels/docs?search=*&facet=Address/City,count:5&api-version=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "test",  
      "facets": [ "Address/City,count:5" ]  
    }  
```

Rechercher dans des champs spécifiques de l'index (par exemple, un champ de langue) :

GET /indexes/hotels/docs?search=hôtel&searchFields=Description_fr&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "hôtel",  
      "searchFields": "Description_fr"
    }

Effectuer une recherche dans plusieurs champs de l’index. Par exemple, vous pouvez stocker et interroger des champs pouvant faire l'objet d'une recherche en plusieurs langues, le tout dans le même index. Si les descriptions en anglais et Français coexistent dans le même document, vous pouvez retourner tout ou partie des résultats de la requête :
```
GET /indexes/hotels/docs?search=hotel&searchFields=Description,Description_fr&api-version=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "hotel",  
      "searchFields": "Description, Description_fr"
    }  
```
Vous ne pouvez interroger l’index qu’à la fois. Ne créez pas plusieurs index pour chaque langue, sauf si vous envisagez d’interroger un par un.

Pagination : obtenir la première page d’éléments (la taille de la page est de 10) :

GET /indexes/hotels/docs?search=*&$skip=0&$top=10&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "*",  
      "skip": 0,  
      "top": 10  
    }

Pagination : obtenir 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=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "*",  
      "skip": 10,  
      "top": 10  
    }

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

GET /indexes/hotels/docs?search=*&$select=HotelName,Description&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "*",  
      "select": "HotelName, Description"
    }

Récupérer les 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=2020-06-30

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

Rechercher dans l'index et renvoyer des fragments avec des surlignages de correspondances :

GET /indexes/hotels/docs?search=something&highlight=Description&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "something",  
      "highlight": "Description"  
    }

Rechercher dans l'index et renvoyer des documents triés du plus proche au plus éloigné 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=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "something",  
      "orderby": "geo.distance(Location, geography'POINT(-122.12315 47.88121)')"
    }

Effectuez une recherche dans 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 (-). Il est suivi des coordonnées de longitude et de 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=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "something",  
      "scoringProfile": "geo",  
      "scoringParameters": [ "currentLocation--122.123,44.77233", "lastLocation--121.499,44.2113" ]  
    }  
```
Rechercher des documents dans l'index à l'aide d'une syntaxe de requête simple. Cette requête renvoie les hôtels où les champs pouvant faire l'objet d'une recherche contiennent les termes « confort » et « emplacement », mais pas « motel » :
```
Get /indexes/hotels/docs?search=comfort +location –motel&searchMode=all&api-version=22020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "comfort +location -motel",  
      "searchMode": "all"  
    }  
```
Conseil

L'utilisation de searchMode=all remplace la valeur par défaut de searchMode=any, en s'assurant que -motel signifie « AND NOT » (et pas) plutôt que « OR NOT » (ou pas). Sans searchMode=all, vous obtenez « OU PAS » qui étend au lieu de limiter les résultats de recherche, et cela peut être contraire à l'intuition pour certains utilisateurs.
Recherchez des documents dans l’index à l’aide de la syntaxe de requête Lucene). Cette requête renvoie les hôtels où le champ de 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 mieux classés en raison de la valeur de renforcement du terme (3)
```
GET /indexes/hotels/docs?search=Category:budget AND \"recently renovated\"^3&searchMode=all&api-version=2020-06-30&querytype=full` 
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
     "search": "Category:budget AND \"recently renovated\"^3",  
      "queryType": "full",  
      "searchMode": "all"  
}  
```
Recherchez des documents dans l’index tout en favorisant un scoring cohérent sur une latence plus faible. Cette requête calcule les fréquences de document sur l’ensemble de l’index et s’efforce de 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=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "hotel",  
      "sessionId": "mySessionId",
      "scoringStatistics" :"global"
    }  
```