Upgraden naar de nieuwste REST API in Azure AI Search

Gebruik dit artikel om te migreren naar nieuwere versies van de REST API's van de Search Service en de REST API's van Search Management voor bewerkingen in het gegevensvlak en besturingsvlak .

Hier volgen de meest recente versies van de REST API's:

Upgrade-instructies richten zich op codewijzigingen die u helpen om brekende wijzigingen van eerdere versies aan te pakken, zodat bestaande code hetzelfde blijft functioneren als voorheen, maar dan op de nieuwere API-versie. Zodra uw code in de werkvolgorde is, kunt u beslissen of u nieuwere functies wilt gebruiken. Zie Wat is er nieuw voor meer informatie over nieuwe functies.

We raden u aan API-versies achter elkaar bij te werken, waarbij u elke versie doorloopt totdat u bij de nieuwste versie komt.

2023-07-01-preview was de eerste REST API voor vectorondersteuning. Gebruik deze API-versie niet. Het is nu afgeschaft en u moet onmiddellijk migreren naar stabiele of nieuwere PREVIEW REST API's.

Wanneer moet ik upgraden?

Azure AI Search onderbreekt achterwaartse compatibiliteit als laatste redmiddel. Upgrade is nodig wanneer:

• Uw code verwijst naar een buiten gebruik gestelde of niet-ondersteunde API-versie en is onderhevig aan een of meer belangrijke wijzigingen. U moet belangrijke wijzigingen aanpakken als uw code is gericht op 2025-11-01-preview voor ophalen door agenten, 2025-05-01-preview voor kennisagenten, 2023-07-10-preview voor vectoren, 2020-06-01-preview voor semantische rangschikking en 2019-05-06 voor gedateerde vaardigheden en tijdelijke oplossingen.

• Uw code mislukt wanneer niet-herkende eigenschappen worden geretourneerd in een API-antwoord. Als best practice moet uw toepassing eigenschappen negeren die niet worden begrepen.

• Uw code bewaart API-aanvragen en probeert deze opnieuw te verzenden naar de nieuwe API-versie. Dit kan bijvoorbeeld gebeuren als uw toepassing vervolgtokens opslaat die zijn geretourneerd door de zoek-API (voor meer informatie zoekt u naar @search.nextPageParameters in de referentie van de zoek-API).

Hoe te upgraden

1. Als u een versie van een datavlak bijwerkt, bekijkt u de release-opmerkingen voor de nieuwe API-versie.

2. Werk de api-version parameter, die is opgegeven in de aanvraagheader, bij naar een nieuwere versie.

   Zoek in uw toepassingscode die directe aanroepen naar de REST API's uitvoert, naar alle exemplaren van de bestaande versie en vervang deze door de nieuwe versie. Zie quickstart: Zoeken in volledige tekst met REST voor meer informatie over het structureren van een REST-aanroep.

   Als u een Azure SDK gebruikt, is elk pakket gericht op een specifieke versie van de REST API. Bekijk het wijzigingslogboek om te bepalen welke REST API-versie uw pakket ondersteunt. Werk bij naar de nieuwste pakketversie voor toegang tot de nieuwste functies en API-verbeteringen.

3. Als u een versie van een datavlak bijwerkt, lees dan de belangrijke wijzigingen die in dit artikel worden beschreven en implementeer de tijdelijke oplossingen. Begin met de versie die door uw code wordt gebruikt en los eventuele belangrijke wijzigingen voor elke nieuwere API-versie op totdat u bij de nieuwste stabiele of preview-versie bent.

Wijzigingen die fouten veroorzaken

De volgende belangrijke wijzigingen zijn van toepassing op gegevensbewerkingen.

Belangrijke wijzigingen voor het ophalen van agents

De meest recente 2025-11-01-preview herstructureert de API's voor kennisagenten (bases), kennisbronnen en de actie ophalen. De meest recente 2025-11-01-preview hernoemt kennisagenten naar kennisdatabases en verplaatst verschillende eigenschappen. Verschillende eigenschappen worden vervangen of verplaatst naar andere objecten.

Zie Uw agentische ophaalcode migreren voor hulp bij het verbreken van wijzigingen.

Belangrijke wijzigingen voor kennisagenten

Kennisagenten zijn geïntroduceerd in 2025-05-01-preview. In 2025-08-01-preview, targetIndexes werd vervangen door een nieuw kennisbronobject en defaultMaxDocsForReranker werd vervangen door andere API's. Er worden meer belangrijke wijzigingen geïntroduceerd in 2025-11-01-preview.

Zie Uw agentische ophaalcode migreren voor hulp bij het verbreken van wijzigingen.

Belangrijke wijzigingen voor clientcode die verbindingsgegevens leest

Vanaf 29 maart 2024 en van toepassing op alle ondersteunde REST API's:

• GET Skillset, GET Index en GET Indexer retourneren geen sleutels of verbindingseigenschappen meer in een antwoord. Dit is een belangrijke wijziging als u downstreamcode hebt die sleutels of verbindingen (gevoelige gegevens) leest vanuit een GET-antwoord.

• Als u beheerders- of query-API-sleutels voor uw zoekservice wilt ophalen, gebruikt u de REST API's van Search Management.

• Als u verbindingsreeks van een andere Azure-resource, zoals Azure Storage of Azure Cosmos DB, moet ophalen, gebruikt u de API's van die resource en gepubliceerde richtlijnen om de informatie te verkrijgen.

Belangrijke wijzigingen voor semantische rangschikking

Semantische rangschikking werd algemeen beschikbaar in 2023-11-01. Dit zijn de belangrijke wijzigingen uit eerdere versies:

• In alle versies na 2020-06-01-preview: semanticConfiguration vervangt searchFields als het mechanisme voor het opgeven van de velden die moeten worden gebruikt voor L2-classificatie.

• Voor alle API-versies hebben de updates van 14 juli 2023 aan de semantische modellen die door Microsoft gehost worden, de semantische rangschikking taalagnostisch gemaakt, waardoor de queryLanguage eigenschap effectief buiten gebruik is gesteld. Er is geen 'belangrijke wijziging' in code, maar de eigenschap wordt genegeerd.

Zie Migreren van preview-versie om uw code over te zetten voor gebruik semanticConfiguration.

Upgrades van het gegevensvlak

Upgraderichtlijnen gaan ervan uit dat de upgrade vanaf de recentste vorige versie wordt uitgevoerd. Als uw code is gebaseerd op een oude API-versie, raden we u aan elke volgende versie te upgraden om naar de nieuwste versie te gaan.

Upgraden naar 2025-11-01-preview

2025-11-01-preview introduceert de volgende belangrijke wijzigingen voor het ophalen van agent gebaseerde retrievals zoals geïmplementeerd in het 2025-08-01-preview.

• agents Vervangt door knowledgebases. Verschillende eigenschappen met betrekking tot kennisbronnen zijn verplaatst uit de definitie van de Knowledge Base en naar de actie ophalen.
• Eigenschappen van kennisbronnen worden geherstructureerd en implementeren een nieuw ingestionParameters object voor kennisbronnen die een indexeerpijplijn genereren.

Voor meer informatie over wijzigingen en codemigratie, zie belangrijke wijzigingen in de preview-versie van 2025-11-01 en Hoe te migreren.

Voor alle andere bestaande API's zijn er geen gedragswijzigingen. U kunt wisselen in de nieuwe API-versie en uw code wordt hetzelfde uitgevoerd als voorheen.

Upgraden naar 01-09-2025

2025-09-01 is de nieuwste stabiele REST API-versie en voegt algemene beschikbaarheid toe voor de OneLake-indexeerfunctie, de vaardigheid Documentindeling en andere API's.

Er zijn geen belangrijke wijzigingen als u een upgrade uitvoert van 2024-07-01 en geen preview-functies gebruikt. Als u de nieuwe stabiele release wilt gebruiken, wijzigt u de API-versie en test u uw code.

Upgrade uitvoeren naar 2025-08-01-preview

2025-08-01-preview introduceert de volgende belangrijke wijzigingen in kennisagenten die zijn gemaakt met behulp van 2025-05-01-preview:

• targetIndexes Vervangt door knowledgeSources.
• Verwijdert defaultMaxDocsForReranker zonder vervanging.

Anders zijn er geen gedragswijzigingen voor bestaande API's. U kunt wisselen in de nieuwe API-versie en uw code wordt hetzelfde uitgevoerd als voorheen.

Bijwerken naar 2025-05-01-preview

2025-05-01-preview biedt nieuwe functies, maar er zijn geen gedragswijzigingen voor bestaande API's. U kunt wisselen in de nieuwe API-versie en uw code wordt hetzelfde uitgevoerd als voorheen.

Upgraden naar 2025-03-01-preview

2025-03-01-preview biedt nieuwe functies, maar er zijn geen gedragswijzigingen voor bestaande API's. U kunt wisselen in de nieuwe API-versie en uw code wordt hetzelfde uitgevoerd als voorheen.

Upgrade uitvoeren naar 2024-11-01-preview

2024-11-01-preview query herschrijven, vaardigheid voor documentindeling, sleutelloze facturering voor het verwerken van vaardigheden, de Markdown-parseermodus en het wijzigen van opties voor gecomprimeerde vectoren.

Als u een upgrade uitvoert vanaf 2024-09-01-preview, kunt u de nieuwe API-versie gebruiken en blijft uw code hetzelfde functioneren als voorheen.

De nieuwe versie introduceert echter syntaxiswijzigingen in vectorSearch.compressions:

• rerankWithOriginalVectors Vervangt doorenableRescoring
• Verplaatst defaultOversampling naar een nieuw rescoringOptions eigenschapsobject

Compatibiliteit met eerdere versies blijft behouden vanwege een interne API-toewijzing, maar we raden u aan de syntaxis te wijzigen als u de nieuwe preview-versie gebruikt. Zie Vectoren comprimeren met behulp van scalaire of binaire kwantisatie voor een vergelijking van de syntaxis.

Bijwerken naar versie 2024-09-01-preview

2024-09-01-preview voegt MRL-compressie toe voor tekst-embedding-3 modellen, gerichte vectorfiltering voor hybride query's, vector-subscoredetails voor foutopsporing en tokenchunking voor de Text Split-vaardigheid.

Als u een upgrade uitvoert vanaf 2024-05-01-preview, kunt u de nieuwe API-versie gebruiken en blijft uw code hetzelfde functioneren als voorheen.

Upgraden naar 2024-07-01

2024-07-01 is de algemeen beschikbare release. De voormalige preview-functies zijn nu algemeen beschikbaar: geïntegreerde segmentering en vectorisatie (vaardigheid Tekst splitsen, AzureOpenAIEmbedding vaardigheid), queryvectorizer op basis van AzureOpenAIEmbedding, vectorcompressie (scalaire kwantisatie, binaire kwantisatie, opgeslagen eigenschap, smalle gegevenstypen).

Er zijn geen grote wijzigingen als u een upgrade uitvoert van 2024-05-01-preview naar de stabiele versie. Als u de nieuwe stabiele release wilt gebruiken, wijzigt u de API-versie en test u uw code.

Er zijn belangrijke wijzigingen als u rechtstreeks vanaf een upgrade uitvoert 2023-11-01. Volg de stappen die worden beschreven voor elke nieuwere preview om van 2023-11-01 naar te 2024-07-01migreren.

Upgraden naar 2024-05-01-preview

2024-05-01-preview voegt een indexeerfunctie toe voor Microsoft OneLake, binaire vectoren en meer insluitingsmodellen.

Als u een upgrade uitvoert van 2024-03-01-preview, is voor de vaardigheid AzureOpenAIEmbedding nu een eigenschap voor modelnaam en dimensies vereist.

1. Zoek in uw codebasis naar AzureOpenAIEmbedding-verwijzingen .

2. Stel modelName in op 'text-embedding-ada-002' en stel dimensions in op '1536'.

Upgraden naar versie 2024-03-01-preview

2024-03-01-preview voegt smalle gegevenstypen, scalaire kwantisatie en vectoropslagopties toe.

Als u een upgrade uitvoert, 2023-10-01-previewzijn er geen belangrijke wijzigingen. Er is echter één gedragsverschil: voor 2023-11-01 en nieuwere previews is de vectorFilterMode standaardwaarde gewijzigd van postfilter in prefilter voor filterexpressies.

1. Zoek in uw codebasis naar vectorFilterMode verwijzingen.

2. Als de eigenschap expliciet is ingesteld, is er geen actie vereist. Als u afhankelijk bent van de standaardwaarde, is het nieuwe standaardgedrag om te filteren voordat query's worden uitgevoerd. Als u post-query filtering wilt uitvoeren, stelt u expliciet vectorFilterMode in op postfilter om het oude gedrag te behouden.

Bijwerken naar 2023-11-01

2023-11-01 is de algemeen beschikbare release. De voormalige preview-functies zijn nu algemeen beschikbaar: semantische rangschikking en vectorondersteuning.

Er zijn geen wijzigingen die fouten veroorzaken, 2023-10-01-previewmaar er zijn meerdere wijzigingen die fouten veroorzaken in 2023-07-01-preview2023-11-01. Zie Upgrade van 2023-07-01-preview voor meer informatie.

Als u de nieuwe stabiele release wilt gebruiken, wijzigt u de API-versie en test u uw code.

Upgraden naar 2023-10-01-preview

2023-10-01-preview was de eerste preview-versie om ingebouwde gegevenssegmentering en vectorisatie toe te voegen tijdens het indexeren en ingebouwde queryvectorisatie. Het biedt ook ondersteuning voor vectorindexering en query's uit de vorige versie.

Als u een upgrade uitvoert van de vorige versie, bevat de volgende sectie de stappen.

Upgrade van 2023-07-01-preview

Gebruik deze API-versie niet. Hiermee wordt een vectorquerysyntaxis geïmplementeerd die niet compatibel is met een nieuwere API-versie.

2023-07-01-preview is nu afgeschaft, dus u moet geen nieuwe code baseren op deze versie, noch moet u in geen geval upgraden naar deze versie. In deze sectie wordt het migratiepad uitgelegd van 2023-07-01-preview naar een nieuwere API-versie.

Portalupgrade voor vectorindexen

Azure Portal ondersteunt een upgradepad met één klik voor 2023-07-01-preview indexen. Het detecteert vectorvelden en biedt een knop Migreren .

• Migratiepad is van 2023-07-01-preview naar 2024-05-01-preview.
• Updates zijn beperkt tot vectorvelddefinities en configuraties van vectorzoekalgoritmen.
• Updates zijn in één richting. U kunt de upgrade niet omkeren. Zodra de index is bijgewerkt, moet u 2024-05-01-preview of later gebruiken om een query uit te voeren op de index.

Er is geen portalmigratie voor het upgraden van vector query-syntaxis. Zie code-upgrades voor wijzigingen in querysyntaxis.

Voordat u Migreren selecteert, selecteert u JSON bewerken om eerst het bijgewerkte schema te controleren. U moet een schema vinden dat voldoet aan de wijzigingen die worden beschreven in de sectie code-upgrade . Portalmigratie verwerkt alleen indexen met één vectorzoekalgoritmenconfiguratie. Er wordt een standaardprofiel gemaakt dat wordt toegewezen aan het 2023-07-01-preview algoritme voor vectorzoekopdrachten. Voor indexen met configuraties voor meervoudige vectorzoekopdrachten is handmatige migratie vereist.

Code-upgrade voor vectorindexen en zoekopdrachten

Vector search-ondersteuning is geïntroduceerd in Create or Update Index (2023-07-01-preview).

Voor het upgraden van 2023-07-01-preview een nieuwere stabiele versie of preview-versie is het volgende vereist:

• De vectorconfiguratie in de index hernoemen en herstructureren
• Vectorqueries herschrijven

Gebruik de instructies in deze sectie om vectorvelden, configuratie en query's te migreren van 2023-07-01-preview.

1. Roep Get Index aan om de bestaande definitie op te halen.

2. Wijzig de vectorzoekconfiguratie. 2023-11-01 en latere versies introduceren het concept van vectorprofielen die configuraties met betrekking tot vectoren bundelen onder één naam. Nieuwere versies hernoemen algorithmConfigurations ook naar algorithms.

   • Wijzig de naam van algorithmConfigurations in algorithms. Dit is alleen een hernoeming van de array. De inhoud is compatibel met eerdere versies. Dit betekent dat uw bestaande HNSW-configuratieparameters kunnen worden gebruikt.

   • Voeg profiles toe en geef elk een naam en een algoritmeconfiguratie.

   Vóór de migratie (2023-07-01-preview):

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

   Na migratie (2023-11-01):

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

3. Vectorvelddefinities wijzigen, vervangen door vectorSearchConfigurationvectorSearchProfile. Zorg ervoor dat de profielnaam wordt omgezet in een nieuwe vectorprofieldefinitie en niet de naam van de algoritmeconfiguratie. Andere vectorveldeigenschappen blijven ongewijzigd. Ze kunnen bijvoorbeeld niet worden gefilterd, gesorteerd of facetbaar, noch analysen of normalizers of synoniemenkaarten gebruiken.

   Voor (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"
     }
   

   Na (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. Roep Create of Update Index aan om de wijzigingen te posten.

5. Wijzig Search POST om de querysyntaxis te wijzigen. Deze API-wijziging maakt ondersteuning mogelijk voor polymorfe vectorquerytypen.

   • Wijzig de naam van vectors in vectorQueries.
   • Voor elke vectorquery voegt u deze toe kinden stelt u deze in op vector.
   • Voor elke vectorquery wijzigt u de naam value in vector.
   • Voeg desgewenst toe vectorFilterMode als u filterexpressies gebruikt. De standaardwaarde is vooraffilter voor indexen die zijn gemaakt na 2023-10-01. Indexen die vóór die datum zijn gemaakt, ondersteunen alleen postfilter, ongeacht hoe u de filtermodus instelt.

   Voor (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"
   }
   

   Na (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"
   }
   

Met deze stappen voltooit u de migratie naar 2023-11-01 een stabiele API-versie of nieuwere preview-API-versies.

Upgraden naar 2020-06-30

In deze versie is er één belangrijke wijziging en verschillende gedragsverschillen. Algemeen beschikbare functies zijn onder andere:

• Kennisarchief, permanente opslag van verrijkte inhoud die is gemaakt via vaardighedensets, gemaakt voor downstreamanalyse en verwerking via andere toepassingen. Er wordt een kennisarchief gemaakt via AZURE AI Search REST API's, maar deze bevindt zich in Azure Storage.

Incompatibele wijziging

Code die is geschreven op basis van eerdere API-versies werkt niet meer op 2020-06-30 en later als het de volgende functionaliteit bevat:

• Letterlijke Edm.Date waarden (een datum die bestaat uit jaar-maand-dag, zoals 2020-12-12) in filterexpressies moeten het Edm.DateTimeOffset formaat hebben: 2020-12-12T00:00:00Z. Deze wijziging was nodig om onjuiste of onverwachte queryresultaten te verwerken vanwege verschillen in tijdzones.

Gedragswijzigingen

• BM25-classificatiealgoritmen vervangen het vorige classificatie-algoritme door nieuwere technologie. Services die na 2019 zijn gemaakt, gebruiken dit algoritme automatisch. Voor oudere services moet u parameters instellen om het nieuwe algoritme te gebruiken.

• Geordende resultaten voor null-waarden zijn in deze versie gewijzigd, waarbij null-waarden eerst worden weergegeven als de sortering asc en laatste als de sortering is desc. Als u code hebt geschreven om te bepalen hoe null-waarden worden gesorteerd, moet u rekening houden met deze wijziging.

Upgraden naar 2019-05-06

Functies die algemeen beschikbaar zijn in deze API-versie zijn onder andere:

• Automatisch aanvullen is een typeahead-functie die een gedeeltelijk opgegeven term voltooit.
• Complexe typen bieden systeemeigen ondersteuning voor gestructureerde objectgegevens in zoekindex.
• JsonLines parseringsmodi, onderdeel van Azure Blob-indexering, maakt één zoekdocument per JSON-entiteit die wordt gescheiden door een nieuwe regel.
• AI-verrijking biedt indexering die gebruikmaakt van de AI-verrijkingsengines van Foundry Tools.

Wijzigingen die fouten veroorzaken

Code die is geschreven op basis van een eerdere API-versie werkt niet meer bij gebruik van 2019-05-06 of later, als deze de volgende functionaliteit bevat:

1. Typ de eigenschap voor Azure Cosmos DB. Voor indexeerders die zich richten op een Azure Cosmos DB for NoSQL API-gegevensbron, wijzig "type": "documentdb" in "type": "cosmosdb".

2. Als de foutafhandeling van de indexeerfunctie verwijzingen naar de status eigenschap bevat, moet u deze verwijderen. We hebben de status verwijderd uit het foutbericht omdat deze geen nuttige informatie biedt.

3. Verbindingsreeksen van gegevensbronnen worden niet meer opgenomen in de respons. Vanaf API-versies 2019-05-06 en 2019-05-06-Preview hoger retourneert de gegevensbron-API geen verbindingsreeks s meer in het antwoord van een REST-bewerking. In eerdere API-versies, voor gegevensbronnen die zijn gemaakt met POST, heeft Azure AI Search 201 geretourneerd, gevolgd door het OData-antwoord, dat de verbindingsreeks in tekst zonder opmaak bevatte.

4. De cognitieve vaardigheid Entiteitsherkenning wordt buiten gebruik gesteld. Als u de vaardigheid voor Naam Entiteitherkenning in uw code hebt aangeroepen, mislukt de oproep. Vervangingsfunctionaliteit is Entity Recognition Skill (V3). Volg de aanbevelingen in afgeschafte vaardigheden om te migreren naar een ondersteunde vaardigheid.

Complexe typen upgraden

API-versie 2019-05-06 heeft formele ondersteuning toegevoegd voor complexe typen. Als uw code eerdere aanbevelingen voor complexe type-equivalentie heeft geïmplementeerd in 2017-11-11-Preview of 2016-09-01-Preview, zijn er enkele nieuwe en gewijzigde limieten vanaf de versie 2019-05-06 waarvan u rekening moet houden:

• De limieten voor de diepte van subvelden en het aantal complexe verzamelingen per index zijn verlaagd. Als u indexen hebt gemaakt die deze limieten overschrijden met behulp van de preview-API-versies, mislukt elke poging om ze bij te werken of opnieuw te maken met behulp van de API-versie 2019-05-06 . Als u zich in deze situatie bevindt, moet u uw schema opnieuw ontwerpen om binnen de nieuwe limieten te passen en vervolgens uw index opnieuw te bouwen.

• Er is een nieuwe limiet die begint in api-versie 2019-05-06 op het aantal elementen van complexe verzamelingen per document. Als u indexen hebt gemaakt met documenten die deze limieten overschrijden met behulp van de preview-API-versies, mislukt elke poging om die gegevens opnieuw te indexeren met api-versie 2019-05-06 . Als u zich in deze situatie bevindt, moet u het aantal complexe verzamelingselementen per document verminderen voordat u uw gegevens opnieuw indexeert.

Zie Servicelimieten voor Azure AI Search voor meer informatie.

Hoe een oude complexe typestructuur bij te werken

Als uw code complexe typen gebruikt met een van de oudere preview-API-versies, gebruikt u mogelijk een indeling voor indexdefinities die er als volgt uitziet:

{
  "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" }
  ]
}  

Er is een nieuwere structuur-achtige indeling voor het definiëren van indexvelden geïntroduceerd in de API-versie 2017-11-11-Preview. In de nieuwe indeling heeft elk complex veld een verzameling velden waarin de subvelden worden gedefinieerd. In API-versie 2019-05-06 wordt deze nieuwe indeling uitsluitend gebruikt en mislukt het maken of bijwerken van een index met de oude indeling. Als u indexen hebt gemaakt met de oude indeling, moet u de API-versie 2017-11-11-Preview gebruiken om ze bij te werken naar de nieuwe indeling voordat ze kunnen worden beheerd met API-versie 2019-05-06.

U kunt platte indexen bijwerken naar de nieuwe indeling met behulp van de API-versie 2017-11-11-Preview:

1. Voer een GET-aanvraag uit om uw index op te halen. Als deze al in de nieuwe indeling staat, bent u klaar.

2. Vertaal de index van de platte indeling naar de nieuwe indeling. U moet code schrijven voor deze taak omdat er geen voorbeeldcode beschikbaar is op het moment van schrijven.

3. Voer een PUT-aanvraag uit om de index bij te werken naar de nieuwe indeling. Vermijd het wijzigen van andere details van de index, zoals de doorzoekbaarheid/filterbaarheid van velden, omdat wijzigingen die van invloed zijn op de fysieke expressie van de bestaande index, niet zijn toegestaan door de Update Index-API.

Upgrades van de control plane

Van toepassing op:2014-07-31-Preview, 2015-02-28en 2015-08-19

De listQueryKeys GET-aanvraag voor oudere versies van de Search Management-API is nu afgeschaft. U wordt aangeraden te migreren naar de meest recente stabiele versie van de BESTURINGSvlak-API om de listQueryKeys POST-aanvraag te gebruiken.

1. Wijzig in de bestaande code de api-version parameter in de meest recente versie (2025-05-01).

2. De aanvraag opnieuw omkaderen van GET naar 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. Als u een Azure SDK gebruikt, is het raadzaam om een upgrade uit te voeren naar de nieuwste versie.

Volgende stappen

Raadpleeg de naslagdocumentatie voor de REST API voor Search. Als u problemen ondervindt, vraagt u ons om hulp bij Stack Overflow of neemt u contact op met de ondersteuning.