Effectuer une mise à niveau vers la dernière API REST dans Recherche Azure AI

Utilisez cet article pour migrer vers des versions plus récentes des API REST du service de recherche et les API REST de gestion de la recherche pour les opérations de plan de données et de plan de contrôle .

Voici les versions les plus récentes des API REST :

Les instructions de mise à niveau se concentrent sur les modifications de code qui vous permettent de franchir les changements bloquants des versions précédentes, afin que le code existant fonctionne comme auparavant, tout en utilisant la version plus récente de l'API. Une fois votre code en ordre de travail, vous pouvez décider s’il faut adopter des fonctionnalités plus récentes. Pour en savoir plus sur les nouvelles fonctionnalités, consultez Nouveautés de Recherche Azure AI.

Nous vous recommandons de mettre à niveau les versions d'API successivement, en travaillant chaque version jusqu'à ce que vous atteigniez la plus récente.

2023-07-01-preview était la première API REST pour la prise en charge des vecteurs. N’utilisez pas cette version d’API. Il est désormais déconseillé et vous devez migrer vers des API REST stables ou plus récentes immédiatement.

Quand mettre à niveau

Recherche Azure AI interrompt la compatibilité descendante en dernier recours. La mise à niveau est nécessaire lorsque :

• Votre code fait référence à une version d'API obsolète ou non prise en charge et est soumis à un ou plusieurs changements incompatibles.

• Votre code échoue lorsque les propriétés non reconnues sont retournées dans une réponse d’API. Comme meilleure pratique, votre application doit ignorer les propriétés qu’elle ne comprend pas.

• Votre code conserve les demandes d’API et tente de les renvoyer à la nouvelle version de l’API. Par exemple, cela peut se produire si votre application conserve les jetons de continuation retournés par l’API de recherche (pour plus d’informations, recherchez @search.nextPageParameters dans la référence de l’API de recherche).

Guide pratique pour mettre à niveau

1. Si vous mettez à niveau une version du plan de données, passez en revue ce qui a été publié dans la nouvelle version de l’API .

2. Mettez à jour le api-version paramètre, spécifié dans l’en-tête de requête, vers une version plus récente.

   Dans votre code d’application qui effectue des appels directs aux API REST, recherchez toutes les instances de la version existante, puis remplacez-la par la nouvelle version. Pour plus d’informations sur la structuration d’un appel REST, consultez Démarrage rapide : Recherche en texte intégral à l’aide de REST.

   Si vous utilisez un Kit de développement logiciel (SDK) Azure, chaque package cible une version spécifique de l'API REST. Pour déterminer la version de l’API REST prise en charge par votre package, passez en revue son journal des modifications. Effectuez une mise à jour vers la dernière version du package pour accéder aux dernières fonctionnalités et améliorations de l’API.

3. Si vous mettez à jour une version du plan de données, consultez les modifications susceptibles de provoquer des dysfonctionnements documentées dans cet article et appliquez les solutions de contournement. Commencez par la version utilisée par votre code et résolvez les changements cassants pour chaque version d’API plus récente jusqu’à ce que vous obteniez la dernière version stable ou préliminaire.

Modifications majeures

Les modifications régressives suivantes s’appliquent aux opérations de données.

Changements critiques pour la récupération par agents

2026-04-01 est la première version stable de l’API REST pour la récupération agentique. Il introduit les changements cassants suivants à partir de 2025-11-01-preview :

• La synthèse des réponses, la planification des requêtes et l’effort de raisonnement configurable sont supprimés. La récupération retourne uniquement du contenu extractif et ancré.

• La forme de requête de récupération change : messages est remplacée par intents, et plusieurs paramètres sont renommés ou supprimés.

• Le filtrage des autorisations au niveau du document pour les sources de connaissances Blob et OneLake n’est pas pris en charge.

Pour obtenir la liste complète des modifications au niveau des propriétés et des étapes de migration, consultez Migrer votre code de récupération agentique.

Modifications majeures pour les agents de connaissances

Les agents de connaissances ont été introduits dans 2025-05-01-preview. Dans 2025-08-01-preview, targetIndexes a été remplacé par un nouvel objet source de connaissances et defaultMaxDocsForReranker a été remplacé par d’autres API. D'autres modifications importantes ont été introduites dans 2025-11-01-preview.

Pour obtenir la liste complète des modifications au niveau des propriétés et des étapes de migration, consultez Migrer votre code de récupération agentique.

Changements cassants pour le code client qui lit les informations de connexion

À compter du 29 mars 2024 et applicable à toutes les API REST prises en charge :

• GET Skillset, GET Index et GET Indexer ne retournent plus de clés ou de propriétés de connexion dans une réponse. Il s’agit d’une modification critique si vous avez du code en aval qui lit des clés ou des connexions (données sensibles) depuis une réponse GET.

• Si vous devez récupérer des clés API d’administrateur ou de requête pour votre service de recherche, utilisez les API REST de gestion de la recherche.

• Si vous devez récupérer des chaînes de connexion d’une autre ressource Azure comme stockage Azure ou Azure Cosmos DB, utilisez les API de cette ressource et des conseils publiés pour obtenir les informations.

Modifications majeures pour l'algorithme de classement sémantique

Le ranker sémantique est devenu généralement disponible en 2023-11-01. Voici les changements cassants des versions antérieures :

• Dans toutes les versions après 2020-06-01-preview: semanticConfiguration remplace searchFields comme mécanisme pour spécifier les champs à utiliser pour le classement L2.

• Pour toutes les versions de l’API, les mises à jour du 14 juillet 2023 des modèles sémantiques hébergés par Microsoft ont rendu le classificateur sémantique indépendant de la langue, désactivant efficacement la propriété queryLanguage. Il n'y a pas de « changement disruptif » dans le code, mais la propriété est ignorée.

Consultez Migrer à partir de la préversion pour passer de votre code à utiliser semanticConfiguration.

Mises à niveau du plan de données

Les conseils de mise à niveau supposent la mise à niveau à partir de la version précédente la plus récente. Si votre code est basé sur une ancienne version d’API, nous vous recommandons de procéder à la mise à niveau via chaque version successive pour accéder à la version la plus récente.

Mise à niveau vers le 01-04-2026

2026-04-01 est la dernière version de l’API REST stable. Il favorise la récupération proactive, la sélection de sources de connaissances et plusieurs compétences et fonctionnalités accessibles à tous.

Avant de procéder à la mise à niveau, vérifiez si des modifications de rupture suivantes 2026-04-01 s'appliquent à votre code :

• Six propriétés sont supprimées de la définition de la compétence Invite GenAI : httpMethod, timeout, batchSize, degreeOfParallelism, httpHeaders, et authResourceId. Supprimez ces propriétés avant de procéder à la mise à niveau. Les définitions qui incluent toujours ces propriétés retournent une 400 Bad Request erreur.

• La récupération agentique nécessite désormais son propre consentement de facturation. Si vous disposez semanticSearch=standardactuellement, vous devez définir knowledgeRetrieval=standard explicitement avant la mise à niveau. Pour plus d’informations, consultez Activer ou désactiver la facturation de récupération agentique.

• Si votre code de récupération agentique cible le 2025-11-01-preview, 2026-04-01 supprime plusieurs fonctionnalités d’aperçu et normalise la récupération autour de l’intention d’entrée, de la sortie extractive et du raisonnement minimal. Pour plus d'informations, consultez Migration de votre code de récupération agentique.

Pour toutes les autres API existantes, aucun changement de comportement n’est apporté. Vous pouvez échanger dans la nouvelle version de l’API, et votre code s’exécute comme avant.

Mise à niveau vers la version préliminaire de 2025-11-01

2025-11-01-preview introduit les modifications majeures aux processus d'extraction agentique tel qu'implémenté dans le 2025-08-01-preview éléments suivants :

• Remplace agents par knowledgebases. Plusieurs propriétés liées aux sources de connaissances ont été déplacées hors de la définition de la base de connaissances et de l’action de récupération.

• Les propriétés de la source de connaissances sont refactorisées, implémentant un nouvel ingestionParameters objet pour les sources de connaissances qui génèrent un pipeline d’indexeur.

Pour obtenir la liste complète des modifications au niveau des propriétés et des étapes de migration, consultez Migrer votre code de récupération agentique.

Pour toutes les autres API existantes, aucun changement de comportement n’est apporté. Vous pouvez échanger dans la nouvelle version de l’API, et votre code s’exécute comme avant.

Mise à niveau vers le 01-09-2025

2025-09-01 est une version stable de l’API REST qui ajoute une disponibilité générale pour l’indexeur OneLake, la compétence Disposition du document et d’autres API.

Aucun changement incompatible n’est apporté si vous effectuez une mise à niveau depuis 2024-07-01 et que vous n’utilisez aucune fonctionnalité d’aperçu. Pour utiliser la nouvelle version stable, modifiez la version de l’API et testez votre code.

Mise à niveau vers 2025-08-01-preview

2025-08-01-preview présente les changements significatifs suivants apportés aux agents de connaissances créés à l’aide de 2025-05-01-preview :

• Remplace targetIndexes par knowledgeSources.
• Supprime defaultMaxDocsForReranker sans remplacement.

Sinon, il n’existe aucune modification de comportement sur les API existantes. Vous pouvez échanger dans la nouvelle version de l’API, et votre code s’exécute comme avant.

Mise à jour vers la version 2025-05-01-preview

2025-05-01-preview fournit de nouvelles fonctionnalités, mais il n’existe aucune modification de comportement sur les API existantes. Vous pouvez échanger dans la nouvelle version de l’API, et votre code s’exécute comme avant.

Mise à niveau vers 2025-03-01-preview

2025-03-01-preview fournit de nouvelles fonctionnalités, mais il n’existe aucune modification de comportement sur les API existantes. Vous pouvez échanger dans la nouvelle version de l’API, et votre code s’exécute comme avant.

Mise à niveau vers la version préliminaire 2024-11-01

2024-11-01-preview réécriture des requêtes techniques, fonctionnalité de mise en page de document, facturation sans utilisation de clé pour le traitement des compétences, mode d'analyse Markdown et options de rescoring pour les vecteurs compressés.

Si vous effectuez une mise à niveau à partir de 2024-09-01-preview, vous pouvez passer à la nouvelle version de l’API, et votre code s’exécute comme avant.

Toutefois, la nouvelle version introduit des modifications de syntaxe pour vectorSearch.compressions:

• Remplace rerankWithOriginalVectors par enableRescoring
• Déplacement defaultOversampling vers un nouvel rescoringOptions objet de propriété

La compatibilité descendante est conservée en raison d’un mappage d’API interne, mais nous vous recommandons de modifier la syntaxe si vous adoptez la nouvelle version en préversion. Pour une comparaison de la syntaxe, consultez Compresser des vecteurs à l’aide de quantisation scalaire ou binaire.

Mettre à jour vers la version d'aperçu du 01/09/2024

2024-09-01-preview ajoute la compression Matryoshka Representation Learning (MRL) pour les modèles text-embedding-3, le filtrage de vecteurs ciblé pour des requêtes hybrides, les détails du sous-score vectoriel pour le débogage et le découpage en jetons pour la compétence de fractionnement de texte.

Si vous effectuez une mise à niveau depuis 2024-05-01-preview, vous pouvez remplacer par la nouvelle version de l'API, et votre code s'exécutera comme avant.

Mise à niveau vers le 01-07-2024

2024-07-01 est une version publique. Les anciennes fonctionnalités de préversion sont désormais en disponibilité générale : segmentation intégrée et vectorisation (compétence Fractionnement de texte, compétence AzureOpenAIEmbedding), vectoriseur de requête basé sur AzureOpenAIEmbedding, compression vectorielle (quantisation scalaire, quantisation binaire, propriété stockée, types de données étroits).

Il n’y a pas de changements cassants si vous effectuez une mise à niveau vers 2024-05-01-preview une version stable. Pour utiliser la nouvelle version stable, modifiez la version de l’API et testez votre code.

Il y a des changements majeurs si vous effectuez une mise à niveau directement depuis 2023-11-01. Suivez les étapes décrites pour chaque préversion plus récente afin de migrer de 2023-11-01 à 2024-07-01.

Mise à niveau vers la version 2024-05-01-aperçu

2024-05-01-preview ajoute un indexeur pour Microsoft OneLake, les vecteurs binaires et d’autres modèles d’incorporation.

Si vous effectuez une mise à niveau à partir de 2024-03-01-preview, la compétence AzureOpenAIEmbedding nécessite désormais un nom de modèle et une propriété de dimensions.

1. Recherchez les références AzureOpenAIEmbedding dans votre base de code.

2. Définissez modelName sur « text-embedding-ada-002 » et dimensions sur « 1536 ».

Mise à niveau vers la version préliminaire 2024-03-01

2024-03-01-preview ajoute des types de données étroits, une quantisation scalaire et des options de stockage vectoriel.

Si vous effectuez une mise à niveau à partir de 2023-10-01-preview, il n’y a pas de changements cassants. Toutefois, il existe une différence de comportement : pour 2023-11-01 et les préversions plus récentes, la vectorFilterMode valeur par défaut est passée du postfilter au préfiltre pour les expressions de filtre.

1. Recherchez dans votre base de code des références vectorFilterMode.

2. Si la propriété est définie explicitement, aucune action n’est requise. Si vous vous appuyez sur la valeur par défaut, le nouveau comportement par défaut consiste à filtrer avant l’exécution de la requête. Pour conserver l'ancien comportement, si vous souhaitez le filtrage après requête, définissez explicitement vectorFilterMode sur postfilter.

Mise à niveau vers 2023-11-01

2023-11-01 est une version publique. Les anciennes fonctionnalités de préversion sont désormais en disponibilité générale : classement sémantique et prise en charge des vecteurs.

Il n’y a pas de modifications majeures de 2023-10-01-preview, mais il y a plusieurs modifications majeures de 2023-07-01-preview à 2023-11-01. Pour plus d’informations, consultez Mise à niveau à partir de 2023-07-01-preview.

Pour utiliser la nouvelle version stable, modifiez la version de l’API et testez votre code.

Mise à jour vers 2023-10-01-preview

2023-10-01-preview a été la première version préliminaire pour ajouter la segmentation et la vectorisation de données intégrées pendant l’indexation et la vectorisation de requête intégrée. Il prend également en charge l’indexation vectorielle et les requêtes de la version précédente.

Si vous effectuez une mise à niveau à partir de la version précédente, la section suivante comporte les étapes.

Amélioration depuis la version préliminaire du 2023-07-01

N’utilisez pas cette version d’API. Il implémente une syntaxe de requête vectorielle incompatible avec une version plus récente de l’API.

2023-07-01-preview est désormais déconseillé, vous ne devez donc pas baser de nouveau code sur cette version, ni mettre à niveau vers cette version dans n’importe quelle circonstance. Cette section explique le chemin de migration de 2023-07-01-preview vers une version plus récente de l’API.

Mise à niveau du portail pour les index vectoriels

Le portail Azure prend en charge un parcours de mise à niveau en un seul clic pour les index 2023-07-01-preview. Il détecte les champs vectoriels et fournit un bouton Migrer .

• Le chemin de migration est de 2023-07-01-preview vers 2024-05-01-preview.
• Les mises à jour sont limitées aux définitions de champ vectoriel et aux configurations d’algorithmes de recherche vectorielle.
• Les mises à jour sont unidirectionnelles. Vous ne pouvez pas inverser la mise à niveau. Une fois l’index mis à niveau, vous devez utiliser 2024-05-01-preview ou une version ultérieure pour interroger l’index.

Il n’existe aucune migration du portail pour la mise à niveau de la syntaxe de requête vectorielle. Consultez les mises à niveau de code pour connaître les modifications de syntaxe des requêtes.

Avant de sélectionner Migrer, sélectionnez Modifier JSON pour passer en revue le schéma mis à jour en premier. Vous devez trouver un schéma conforme aux modifications décrites dans la section mise à niveau du code . La migration du portail gère uniquement les index avec une configuration d’algorithme de recherche vectorielle. Il crée un profil par défaut qui est mappé à l’algorithme de 2023-07-01-preview recherche vectorielle. Les index avec plusieurs configurations de recherche vectorielle nécessitent une migration manuelle.

Mise à niveau du code pour les index vectoriels et les requêtes

La prise en charge de la recherche vectorielle a été introduite dans Create or Update Index (2023-07-01-preview).

La mise à niveau de 2023-07-01-preview vers une version plus récente, qu'elle soit stable ou préliminaire, nécessite :

• Renommage et restructuration de la configuration vectorielle dans l’index
• Réécriture de vos requêtes vectorielles

Utilisez les instructions de cette section pour migrer les champs vectoriels, la configuration et les requêtes à partir de 2023-07-01-preview.

1. Appelez Get Index pour récupérer la définition existante.

2. Modifiez la configuration de recherche vectorielle. 2023-11-01 et les versions ultérieures introduisent le concept de profils vectoriels qui regroupent des configurations vectorielles sous un nom. Les versions plus récentes renommement algorithmConfigurations en algorithms.

   • algorithmConfigurations Renommez en algorithms. Il s’agit uniquement d’un changement de nom du tableau. Le contenu est rétrocompatible. Cela signifie que vos paramètres de configuration HNSW existants peuvent être utilisés.

   • Ajoutez profiles, en donnant un nom et une configuration d’algorithme pour chacun d’eux.

   Avant la migration (2023-07-01-preview) :

     "vectorSearch": {
       "algorithmConfigurations": [
           {
               "name": "myHnswConfig",
               "kind": "hnsw",
               "hnswParameters": {
                   "m": 4,
                   "efConstruction": 400,
                   "efSearch": 500,
                   "metric": "cosine"
               }
           }
       ]}
   

   Après la migration (2023-11-01) :

     "vectorSearch": {
       "algorithms": [
         {
           "name": "myHnswConfig",
           "kind": "hnsw",
           "hnswParameters": {
             "m": 4,
             "efConstruction": 400,
             "efSearch": 500,
             "metric": "cosine"
           }
         }
       ],
       "profiles": [
         {
           "name": "myHnswProfile",
           "algorithm": "myHnswConfig"
         }
       ]
     }
   

3. Modifiez les définitions de champ vectoriel, en remplaçant vectorSearchConfiguration par vectorSearchProfile. Assurez-vous que le nom du profil corresponde à une nouvelle définition de profil vectoriel et non au nom de configuration d’algorithme. Les autres propriétés de champ vectoriel restent inchangées. Par exemple, ils ne peuvent pas être filtrables, triables ou facetables, ni utiliser des analyseurs ou des normaliseurs ou des mappages de synonymes.

   Avant (2023-07-01-preview) :

     {
         "name": "contentVector",
         "type": "Collection(Edm.Single)",
         "key": false,
         "searchable": true,
         "retrievable": true,
         "filterable": false,  
         "sortable": false,  
         "facetable": false,
         "analyzer": "",
         "searchAnalyzer": "",
         "indexAnalyzer": "",
         "normalizer": "",
         "synonymMaps": "", 
         "dimensions": 1536,
         "vectorSearchConfiguration": "myHnswConfig"
     }
   

   Après (2023-11-01) :

     {
       "name": "contentVector",
       "type": "Collection(Edm.Single)",
       "searchable": true,
       "retrievable": true,
       "filterable": false,  
       "sortable": false,  
       "facetable": false,
       "analyzer": "",
       "searchAnalyzer": "",
       "indexAnalyzer": "",
       "normalizer": "",
       "synonymMaps": "", 
       "dimensions": 1536,
       "vectorSearchProfile": "myHnswProfile"
     }
   

4. Appelez Créer ou mettre à jour l’index pour publier les modifications.

5. Modifiez search POST pour modifier la syntaxe de la requête. Cette modification d’API permet la prise en charge des types de requêtes vectorielles polymorphes.

   • vectors Renommez en vectorQueries.
   • Pour chaque requête vectorielle, ajouter kind, en la définissant à vector.
   • Pour chaque requête vectorielle, renommez value en vector.
   • Vous pouvez éventuellement ajouter vectorFilterMode si vous utilisez des expressions de filtre. La valeur par défaut est le préfiltre pour les index créés après 2023-10-01. Les index créés avant cette date prennent uniquement en charge le postfilter, quelle que soit la façon dont vous définissez le mode de filtre.

   Avant (2023-07-01-preview) :

   {
       "search": (this parameter is ignored in vector search),
       "vectors": [
         {
           "value": [
               0.103,
               0.0712,
               0.0852,
               0.1547,
               0.1183
           ],
           "fields": "contentVector",
           "k": 5
         }
       ],
       "select": "title, content, category"
   }
   

   Après (2023-11-01) :

   {
     "search": "(this parameter is ignored in vector search)",
     "vectorQueries": [
       {
         "kind": "vector",
         "vector": [
           0.103,
           0.0712,
           0.0852,
           0.1547,
           0.1183
         ],
         "fields": "contentVector",
         "k": 5
       }
     ],
     "vectorFilterMode": "preFilter",
     "select": "title, content, category"
   }
   

Ces étapes effectuent la migration vers une 2023-11-01 version stable de l’API ou des versions plus récentes de l’API en préversion.

Mise à niveau vers 2020-06-30

Dans cette version, il existe une modification majeure et plusieurs variations comportementales. Les fonctionnalités en disponibilité générale sont les suivantes :

• Magasin de connaissances, stockage persistant du contenu enrichi créé par le biais d’ensembles de compétences, créé pour l’analyse et le traitement en aval via d’autres applications. Une base de connaissances est créée via Recherche Azure AI API REST, mais elle réside dans stockage Azure.

Changement cassant

Le code écrit contre les versions antérieures de l’API ne fonctionne pas sur 2020-06-30 et les versions ultérieures si le code inclut les fonctionnalités suivantes :

• Tous Edm.Date les littéraux (date composée d’un jour de l’année, par exemple 2020-12-12) dans les expressions de filtre doivent suivre le Edm.DateTimeOffset format suivant : 2020-12-12T00:00:00Z. Cette modification a été nécessaire pour gérer les résultats de requête erronés ou inattendus en raison des différences de fuseau horaire.

Changements de comportement

• L’algorithme de classement BM25 remplace l’algorithme de classement précédent par une technologie plus récente. Les services créés après 2019 utilisent automatiquement cet algorithme. Pour les services plus anciens, vous devez définir des paramètres pour utiliser le nouvel algorithme.

• Les résultats triés pour les valeurs Null ont changé dans cette version, avec des valeurs Null apparaissant en premier si le tri est asc et le dernier si le tri est desc. Si vous avez écrit du code pour gérer la façon dont les valeurs Null sont triées, tenez compte de cette modification.

Mise à niveau vers 2019-05-06

Les fonctionnalités qui sont devenues généralement disponibles dans cette version de l’API sont les suivantes :

• La saisie semi-automatique est une fonctionnalité typeahead qui termine une entrée de terme partiellement spécifiée.
• Les types complexes prennent en charge nativement les données d’objet structurées dans l’index de recherche.
• JsonLines, les modes d’analyse, qui font partie de l’indexation d’objets blob Azure, créent un document de recherche par entité JSON séparée par une nouvelle ligne.
• L’enrichissement par IA fournit l’indexation en utilisant les moteurs d’enrichissement IA des outils Foundry.

Modifications majeures

Le code écrit pour une version antérieure de l’API ne fonctionne pas sur 2019-05-06 et plus tard s'il contient la fonctionnalité suivante :

1. Propriété type pour Azure Cosmos DB. Pour les indexeurs ciblant une source de données Azure Cosmos DB pour NoSQL API, remplacez "type": "documentdb" par "type": "cosmosdb".

2. Si la gestion des erreurs de votre indexeur inclut des références à la status propriété, vous devez la supprimer. Nous avons supprimé l’état de la réponse d’erreur, car il ne fournit pas d’informations utiles.

3. Les chaînes de connexion des sources de données ne sont plus fournies dans la réponse. À partir des versions 2019-05-06 d’API et 2019-05-06-Preview des versions ultérieures, l’API de source de données ne retourne plus de chaînes de connexion dans la réponse d’une opération REST. Dans les versions précédentes de l’API, pour les sources de données créées à l’aide de POST, Recherche Azure AI a retourné 201 suivi de la réponse OData, qui contenait la chaîne de connexion en texte brut.

4. La compétence cognitive Reconnaissance d’entité nommée est supprimée. Si vous avez appelé la compétence Reconnaissance d’entité de nom dans votre code, l’appel échoue. La fonctionnalité de remplacement est Compétence de Reconnaissance d'Entité (V3). Suivez les recommandations des compétences déconseillées pour migrer vers une compétence prise en charge.

Mise à niveau de types complexes

La version 2019-05-06 de l’API a ajouté une prise en charge formelle des types complexes. Si votre code a implémenté des recommandations précédentes pour l’équivalence de type complexe en 2017-11-11-Preview ou 2016-09-01-Preview, il existe des limites nouvelles et modifiées à partir de la version 2019-05-06 dont vous devez être conscient :

• Les limites relatives à la profondeur des sous-champs et au nombre de collections complexes par index ont été réduites. Si vous avez créé des index qui dépassent ces limites à l’aide des versions d’API en préversion, toute tentative de mise à jour ou de recréation à l’aide de la version 2019-05-06 de l’API échoue. Si vous vous trouvez dans cette situation, vous devez redéfinir votre schéma pour s’adapter aux nouvelles limites, puis reconstruire votre index.

• Il existe une nouvelle limite à compter de la version 2019-05-06 de l’API sur le nombre d’éléments de collections complexes par document. Si vous avez créé des index avec des documents qui dépassent ces limites à l’aide des versions préliminaires d'api, toute tentative de réindexation de ces données à l’aide d’api-version 2019-05-06 échoue. Si vous vous trouvez dans cette situation, vous devez réduire le nombre d’éléments de collection complexes par document avant de réindexer vos données.

Pour plus d’informations, consultez les limites du service Recherche Azure AI.

Comment mettre à niveau une ancienne structure de type complexe

Si votre code utilise des types complexes avec l’une des anciennes versions de l’API en préversion, vous utilisez peut-être un format de définition d’index semblable à ceci :

{
  "name": "hotels",  
  "fields": [
    { "name": "HotelId", "type": "Edm.String", "key": true, "filterable": true },
    { "name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false },
    { "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
    { "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
    { "name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true, "analyzer": "tagsAnalyzer" },
    { "name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true },
    { "name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true },
    { "name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address", "type": "Edm.ComplexType" },
    { "name": "Address/StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true },
    { "name": "Address/City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/Country", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Location", "type": "Edm.GeographyPoint", "filterable": true, "sortable": true },
    { "name": "Rooms", "type": "Collection(Edm.ComplexType)" }, 
    { "name": "Rooms/Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene" },
    { "name": "Rooms/Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.lucene" },
    { "name": "Rooms/Type", "type": "Edm.String", "searchable": true },
    { "name": "Rooms/BaseRate", "type": "Edm.Double", "filterable": true, "facetable": true },
    { "name": "Rooms/BedOptions", "type": "Edm.String", "searchable": true },
    { "name": "Rooms/SleepsCount", "type": "Edm.Int32", "filterable": true, "facetable": true },
    { "name": "Rooms/SmokingAllowed", "type": "Edm.Boolean", "filterable": true, "facetable": true },
    { "name": "Rooms/Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "facetable": true, "analyzer": "tagsAnalyzer" }
  ]
}  

Un format d’arborescence plus récent pour la définition des champs d’index a été introduit dans la version 2017-11-11-Previewde l’API. Dans le nouveau format, chaque champ complexe a une collection de champs où ses sous-champs sont définis. Dans API version 2019-05-06, ce nouveau format est utilisé exclusivement et toute tentative de création ou de mise à jour d’un index à l’aide de l’ancien format échoue. Si vous avez créé des index à l’aide de l’ancien format, vous devez utiliser la version 2017-11-11-Preview de l’API pour les mettre à jour au nouveau format avant de pouvoir être gérés à l’aide de la version d’API 2019-05-06.

Vous pouvez mettre à jour les index plats au nouveau format avec les étapes suivantes à l’aide de la version 2017-11-11-Previewde l’API :

1. Effectuez une requête GET pour récupérer votre index. Si c’est déjà dans le nouveau format, vous avez terminé.

2. Traduisez l’index du format plat au nouveau format. Vous devez écrire du code pour cette tâche, car il n’existe aucun exemple de code disponible au moment de cette écriture.

3. Effectuez une requête PUT pour mettre à jour l’index au nouveau format. Évitez de modifier d’autres détails de l’index, tels que la possibilité de recherche/filtrage des champs, car les modifications qui affectent l’expression physique de l’index existant ne sont pas autorisées par l’API Update Index.

Mises à niveau du plan de contrôle

S’applique à :2014-07-31-Preview, 2015-02-28et 2015-08-19

La listQueryKeys requête GET sur les anciennes versions de l’API Gestion de la recherche est désormais déconseillée. Nous vous recommandons de migrer vers la version de l’API de plan de contrôle stable la plus récente pour utiliser la listQueryKeys requête POST.

1. Dans le code existant, remplacez le api-version paramètre par la version la plus récente (2025-05-01).

2. Reformuler la requête de GET à POST :

   POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Search/searchServices/{searchServiceName}/listQueryKeys?api-version=2025-05-01
   Authorization: Bearer {{token}}
   

3. Si vous utilisez un Kit de développement logiciel (SDK) Azure, nous vous recommandons d'effectuer une mise à niveau vers la dernière version.

Étapes suivantes

Consultez la documentation de référence de l’API REST de recherche. Si vous rencontrez des problèmes, demandez-nous de l’aide sur Stack Overflow ou contactez le support technique.