Saisie semi-automatique (API REST Azure AI Search)

Article
02/28/2024

L’API De saisie semi-automatique termine une entrée de requête partiellement typée à l’aide de termes existants dans l’index de recherche à utiliser dans une requête secondaire. Par exemple, si l’entrée de requête est "medic", l’API autocomplétion retourne "medicare", "medicaid", "medicine" si ces termes se trouvent dans l’index. En interne, le moteur de recherche recherche des termes correspondants dans les champs pour lequel un suggesteur est configuré.

Le protocole HTTPS est requis pour les requêtes de service. La demande de saisie semi-automatique peut être construite à l’aide des méthodes GET ou POST.

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

POST https://[service name].search.windows.net/indexes/[index name]/docs/autocomplete?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 très volumineuses, en particulier lorsque des expressions de filtre OData sont utilisées. Pour ces applications, HTTP POST est un meilleur choix, car il autorise des filtres plus grands que GET.

Avec POST, le nombre de clauses dans un filtre est le facteur limitant, pas la taille de la chaîne du filtre brut, car la limite de la taille de la requête POST est proche de 16 Mo. Même si la limite de taille de requête POST est très é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é.
api-version	Obligatoire. Consultez Versions d’API pour obtenir la liste des versions prises en charge. 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 la saisie semi-automatique, l’encodage d’URL peut être nécessaire pour les paramètres de requête suivants :

recherche
$filter
highlightPreTag
highlightPostTag

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

En outre, l'encodage des URL est nécessaire uniquement lors de l'appel direct de l'API REST à l'aide de GET. Aucun encodage d’URL n’est nécessaire lors de l’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éfinir avec la valeur application/json

api-key Facultatif si vous utilisez des rôles Azure et qu’un jeton de porteur est fourni sur la demande, sinon une clé est requise. Les demandes de requête sur la docs collection peuvent spécifier une clé d’administration ou une clé de requête en tant que api-key. La clé de requête est utilisée pour les opérations en lecture seule sur une collection de documents d’index. Pour plus d’informations, consultez Se connecter à Azure AI Search à l’aide de l’authentification par clé .

Champs	Description
Content-Type	Obligatoire. À définir avec la valeur `application/json`
api-key	Facultatif si vous utilisez des rôles Azure et qu’un jeton de porteur est fourni sur la demande, sinon une clé est requise. Les demandes de requête sur la `docs` collection peuvent spécifier une clé d’administration ou une clé de requête en tant que `api-key`. La clé de requête est utilisée pour les opérations en lecture seule sur une collection de documents d’index. 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 :

{  
  "autocompleteMode": "oneTerm" (default) | "twoTerms" | "oneTermWithContext",
  "filter": "odata_filter_expression",
  "fuzzy": true | false (default),  
  "highlightPreTag": "pre_tag",  
  "highlightPostTag": "post_tag",  
  "minimumCoverage": # (% of index that must be covered to declare query successful; default 80),
  "search": "partial_search_input",  
  "searchFields": "field_name_1, field_name_2, ...",
  "suggesterName": "suggester_name",  
  "top": # (default 5)  
}

Paramètres de requête

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

Nom	Type	Description
api-version	string	Obligatoire. Version de l’API REST utilisée pour la requête. Pour obtenir la liste des versions prises en charge, consultez Gestion des versions des API. Pour cette opération, api-version est spécifié en tant que paramètre URI, que vous appeliez autocomplétion avec GET ou POST.
autocompleteMode	string	facultatif. La valeur par défaut est oneTerm. Les valeurs valides sont oneTerm, twoTerms, oneTermWithContext. oneTerm retourne un seul terme. Si la requête comporte deux termes, seul le dernier terme est terminé. Par exemple, étant donné `"washington medic"`, la réponse peut être l’un des termes suivants : `"medicaid"`, `"medicare"`, . `"medicine"` twoTerms correspond à des expressions à deux termes dans l’index. Par exemple, étant donné `"medic"`, la réponse peut être `"medicare coverage"`, ou `"medical assistant"`. Dans de nombreux cas, les termes `"medicare"` uniques ou `"medical"` ne seraient pas retournés, car la préférence est donnée aux expressions à deux termes qui correspondent. oneTermWithContext termine le dernier terme d’une requête avec au moins deux termes, où les deux derniers termes sont une expression qui existe dans l’index. Par exemple, étant donné `"washington medic"`, la réponse peut être `"washington medicaid"`, `"washington medical"`.
$filter	string	facultatif. Expression de recherche structurée dans la syntaxe OData standard qui filtre les documents considérés pour produire les suggestions de terme terminées. Les expressions de filtre « search.ismatch » et « search.ismatchscoring* » ne sont pas prises en charge dans l’API de saisie semi-automatique. Seuls les champs filtrables peuvent être utilisés dans un filtre. Lorsqu’il est appelé avec POST, ce paramètre est nommé filter au lieu de $filter. Pour plus d’informations sur le sous-ensemble de la grammaire d’expression OData prise en charge par Azure AI Search, consultez Syntaxe d’expression OData pour Azure AI Search .
Floue	boolean	facultatif. La valeur par défaut est false. Lorsqu’elle est définie sur true, cette API recherche des suggestions même s’il existe un caractère remplacé ou manquant dans le texte de recherche ^(1). Cela offre une meilleure expérience dans certains scénarios, mais cela a un coût en termes de performances, car les recherches de suggestions approximatives sont plus lentes et consomment plus de ressources.
highlightPostTag	string	facultatif. La valeur par défaut est une chaîne vide. Balise de chaîne qui ajoute au terme mis en surbrillance. Doit être défini avec highlightPreTag. Les caractères réservés dans l'URL doivent être codés en pourcentage (par exemple, %23 au lieu de #). Lorsqu’elle est appelée à l’aide de GET, les caractères réservés de l’URL doivent être encodés en pourcentage (par exemple, %23 au lieu de #).
highlightPreTag	string	facultatif. Par défaut, une chaîne vide. Balise de chaîne qui est ajoutée au terme mis en surbrillance. Doit être défini avec highlightPostTag. Lorsqu’elle est appelée à l’aide de GET, les caractères réservés de l’URL doivent être encodés en pourcentage (par exemple, %23 au lieu de #).
minimumCoverage	entier	facultatif. La valeur par défaut est 80. Nombre compris entre 0 et 100 indiquant le pourcentage de l’index qui doit être disponible pour traiter la requête avant qu’elle puisse être signalée en tant que réussite. La valeur par défaut reflète un biais vers la vitesse et l’efficacité par rapport à la couverture complète. La réduction de la couverture limite l’expansion des requêtes, ce qui permet aux résultats de revenir plus rapidement. Il permet également à la requête de réussir en cas de disponibilité partielle de l’index, même si une partition est lente à répondre ou indisponible en raison de problèmes d’intégrité du service ou de maintenance d’index. Quelle que soit la valeur de minimumCoverage, ce pourcentage de l’index doit être disponible ou la saisie semi-automatique retourne le code HTTP status 503. Si la saisie semi-automatique réussit au niveau minimal Deoverage, elle retourne HTTP 200 et inclut une @search.coverage valeur dans la réponse indiquant le pourcentage de l’index disponible lors de la maintenance de la requête. La réduction de cette valeur peut être utile si des erreurs 503 se produisent. Sinon, vous pouvez envisager d’augmenter la valeur si la réponse fournit des correspondances insuffisantes.
recherche	string	Obligatoire. Texte à rechercher. Texte de recherche à terminer. Doit comprendre 1 caractère au minimum et 100 caractères au maximum. Il ne peut pas contenir d’opérateurs, de syntaxe de requête ou d’expressions entre guillemets.
searchFields	string	facultatif. Liste séparée par des virgules des noms de champ dans lesquels rechercher le texte spécifié. Les champs cibles doivent être répertoriés dans la définition suggesteurs de l’index.
suggesterName	string	Obligatoire. Nom du suggesteur tel que spécifié dans la collection Suggesters qui fait partie de la définition d’index. Un suggesteur détermine quels champs sont analysés pour rechercher les termes de requête suggérés.
$top	entier	facultatif. La valeur par défaut est 5. Nombre de suggestions de saisie automatique à récupérer. La valeur doit être un nombre compris entre 1 et 100. Lorsqu’il est appelé avec POST, ce paramètre est nommé top au lieu de $top.

(1) Limitations du flou dans la saisie semi-automatique :

Tout d’abord, la distance d’édition est limitée à une seule différence de caractères par jeton, contrairement au paramètre flou dans la recherche. Le fait de limiter la distance de modification à un caractère signifie que toutes les correspondances de candidats ne sont pas trouvées, mais que la limite est nécessaire pour garantir un niveau de performances acceptable.

Deuxièmement, l’étape approximative se produit après l’expansion partielle du jeton et seuls les termes de la même partition d’index sont pris en compte pour les correspondances approximatives. Cette contrainte augmente les performances de l’API de saisie semi-automatique en éliminant l’agrégation de correspondances approximatives sur toutes les partitions. Cette contrainte devient moins perceptible à mesure que d’autres termes sont ajoutés à l’index, ce qui entraîne une distribution de termes similaire pour chaque partition. Comme les termes sont distribués uniformément, les correspondances approximatives au sein d’une partition sont une bonne approximation des correspondances approximatives dans l’index entier. Toutefois, les résultats peuvent être inférieurs si l’index a moins de termes, par exemple dans un index de test ou de prototype, ce qui entraîne une représentation inégale entre les partitions. Pour plus d’informations sur la façon dont les index sont divisés en partitions, consultez partition et combinaisons de réplica.

response

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

La charge utile de réponse a deux propriétés.

Propriété	Description
"text"	Terme ou expression terminé
« queryPlusText »	Entrée de requête initiale plus le terme ou l’expression terminé

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

Exemples

Exemple 1 : Récupérez trois suggestions de saisie semi-automatique où l’entrée de recherche partielle est 'washington medic' en mode par défaut (oneTerm) :

GET /indexes/insurance/docs/autocomplete?search=washington%20medic&$top=3&suggesterName=sg&api-version=2020-06-30

POST /indexes/insurance/docs/autocomplete?api-version=2020-06-30
{  
  "search": "washington medic",
  "filter": "search.in(roleId, 'admin,manager')",
  "top": 3,
  "suggesterName": "sg"  
}

Réponse :

{    
  "value": [
    {
      "text": "medicaid",
      "queryPlusText": "washington medicaid"
    },
    {
      "text": "medicare",
      "queryPlusText": "washington medicare"
    },
    {
      "text": "medicine",
      "queryPlusText": "washington medicine"
    }
  ]
}

Exemple 2 : Récupérer trois suggestions de saisie semi-automatique où l’entrée de recherche partielle est 'washington medic' et autocompleteMode=twoTerms:

GET /indexes/insurance/docs/autocomplete?search=washington%20medic&$top=3&suggesterName=sg&autocompleteMode=twoTerms&api-version=2020-06-30

POST /indexes/insurance/docs/autocomplete?api-version=2020-06-30
{  
  "search": "washington medic",  
  "autocompleteMode": "twoTerms",
  "filter": "planDuration ge 1",
  "top": 3,  
  "suggesterName": "sg"  
}

Réponse :

{    
  "value": [
    {
      "text": "medicaid insurance",
      "queryPlusText": "washington medicaid insurance"
    },
    {
      "text": "medicare plan",
      "queryPlusText": "washington medicare plan"
    },
    {
      "text": "medicine book",
      "queryPlusText": "washington medicine book"
    }
  ]
}

Notez que suggesterName est requis dans une opération de saisie semi-automatique.

Partager via