Upgrade auf die neueste REST-API in Azure AI Search

Verwenden Sie diesen Artikel, um zu neueren Versionen der Search Service-REST-APIs und der Search Management-REST-APIs für Datenebenen- und Steuerungsebenenvorgänge zu migrieren.

Hier sind die neuesten Versionen der REST-APIs:

Die Upgradeanweisungen konzentrieren sich auf Codeänderungen, mit denen Sie Breaking Changes aus früheren Versionen umgehen können, so dass der vorhandene Code wie zuvor, aber mit der neueren API-Version, ausgeführt wird. Sobald Ihr Code funktioniert, können Sie entscheiden, ob neuere Features verwendet werden sollen. Weitere Informationen zu neuen Features finden Sie unter What's New.

Es wird empfohlen, die API-Versionen nacheinander zu aktualisieren, bis Sie zur neuesten Version gelangen.

2023-07-01-preview war die erste REST-API für die Vektorunterstützung. Verwenden Sie diese API-Version nicht. Diese API ist jetzt veraltet, und Sie sollten sofort zu einer stabilen Version oder einer neueren REST-API-Vorschauversion migrieren.

Upgradezeitpunkt

Azure KI-Suche unterbricht die Abwärtskompatibilität im äußersten Notfall. Das Upgrade ist erforderlich, wenn:

• Ihr Code verweist auf eine veraltete oder nicht unterstützte API-Version und ist von mindestens einer Änderung betroffen, die zu Inkompatibilitäten führen kann. Sie müssen wichtige Änderungen berücksichtigen, wenn Ihr Code auf 2025-11-01-preview für Agent-Abruf, auf 2025-05-01-preview für Wissensagents, auf 2023-07-10-preview für Vektoren, auf 2020-06-01-preview für den semantischen Sortierer und auf 2019-05-06 für veraltete Skills und Problemumgehungen ausgerichtet ist.

• Der Code erzeugt Fehler, wenn nicht erkannte Eigenschaften in einer API-Antwort zurückgegeben werden. Als eine bewährte Methode sollte Ihre Anwendung Eigenschaften ignorieren, die sie nicht versteht.

• Ihr Code behält API-Anforderungen bei und versucht, sie erneut an die neue API-Version zu senden. Dies kann beispielsweise vorkommen, wenn Ihre Anwendung Fortsetzungstoken beibehält, die von der Search-API zurückgegeben wurden (weitere Informationen finden Sie, indem Sie in der @search.nextPageParameters nach suchen).

So aktualisieren Sie

1. Wenn Sie eine Datenebenenversion aktualisieren, lesen Sie die Versionshinweise für die neue API-Version.

2. Aktualisieren Sie den api-version-Parameter, der im Anforderungsheader angegeben ist, auf eine neuere Version.

   Suchen Sie in Ihrem Anwendungscode, der direkte Aufrufe an die REST-APIs vorgibt, nach allen Instanzen der vorhandenen Version, und ersetzen Sie sie dann durch die neue Version. Weitere Informationen zum Strukturieren eines REST-Aufrufs finden Sie in der Schnellstartanleitung: Volltextsuche mit REST.

   Wenn Sie ein Azure SDK verwenden, zielt jedes Paket auf eine bestimmte Version der REST-API ab. Überprüfen Sie das Änderungsprotokoll, um zu ermitteln, welche REST-API-Version Ihr Paket unterstützt. Aktualisieren Sie auf die neueste Paketversion, um auf die neuesten Features und API-Verbesserungen zuzugreifen.

3. Wenn Sie eine Version der Datenebene aktualisieren, überprüfen Sie die im Artikel dokumentierten grundlegenden Änderungen und setzen Sie die empfohlenen Problemumgehungen um. Beginnen Sie mit der von Ihrem Code verwendeten Version, und lösen Sie alle Breaking Changes für jede neuere API-Version, bis Sie zur neuesten stabilen Version oder Vorschauversion gelangen.

Aktuelle Änderungen

Die folgenden wichtigen Änderungen gelten für Datenvorgänge.

Wichtige Änderungen für den Agent-Abruf

Im neuesten 2025-11-01-preview werden die APIs für Wissens-Agents (Basen), Wissensquellen und die Abrufaktion umgestaltet. Die neueste Version von 2025-11-01-preview benennt die Wissensagenten in Wissensdatenbanken um und verlegt mehrere Eigenschaften. Mehrere Eigenschaften werden ersetzt oder in andere Objekte verschoben.

Hilfe zu Breaking Changes finden Sie unter Migrieren des Agent-Abrufcodes.

Breaking Changed für Wissensagenten

Wissensagenten wurden in 2025-05-01-preview eingeführt. In 2025-08-01-preview wurde targetIndexes durch ein neues Wissensquellobjekt und defaultMaxDocsForReranker durch andere APIs ersetzt. Weitere bahnbrechende Änderungen werden eingeführt in 2025-11-01-preview.

Hilfe zu Breaking Changes finden Sie unter Migrieren des Agent-Abrufcodes.

Grundlegende Änderungen für Clientcode, der Verbindungsinformationen liest

Gilt ab dem 29. März 2024 und für alle unterstützten REST-APIs:

• Von GET Skillset, GET Index und GET Indexer werden in einer Antwort keine Schlüssel oder Verbindungseigenschaften mehr zurückgegeben. Dies ist eine Umbruchänderung, wenn Sie über Downstream-Code verfügen, der Schlüssel oder Verbindungen (vertrauliche Daten) aus einer GET-Abfrage liest.

• Wenn Sie Administrator- oder Abfrage-API-Schlüssel für Ihren Suchdienst abrufen müssen, verwenden Sie die REST-APIs für die Suchverwaltung.

• Wenn Sie Verbindungszeichenfolgen einer anderen Azure-Ressource (beispielsweise Azure Storage oder Azure Cosmos DB) abrufen müssen, verwenden Sie die APIs der entsprechenden Ressource sowie veröffentlichte Anleitungen, um die Informationen abzurufen.

Unterbrechen von Änderungen für semantischen Rangierer

Semantic Ranker ist allgemein verfügbar in 2023-11-01. Dies sind die bahnbrechenden Änderungen aus früheren Versionen:

• Für alle Versionen nach 2020-06-01-preview: semanticConfiguration ersetzt searchFields als Mechanismus zum Angeben, welche Felder für die L2-Rangfolge verwendet werden sollen.

• Für alle API-Versionen: Seit den Updates der von Microsoft gehosteten Semantikmodelle vom 14. Juli 2023 ist der semantische Sortierer sprachunabhängig, und die queryLanguage-Eigenschaft wurde im Grunde außer Betrieb gesetzt. Es gibt keinen Breaking Change im Code, die Eigenschaft wird jedoch ignoriert.

In Migrieren von Vorschauversionen finden Sie Informationen darüber, wie Sie Ihren Code auf die Verwendung von semanticConfiguration umstellen können.

Aktualisierungen der Datenebene

Upgradeleitfaden gehen davon aus, dass ein Upgrade von der neuesten vorherigen Version durchgeführt wird. Wenn Ihr Code auf einer alten API-Version basiert, empfehlen wir ein Upgrade über jede aufeinander folgende Version, um auf die neueste Version zu gelangen.

Upgrade auf 2025-11-01-Preview

2025-11-01-preview führt die folgenden wichtigen Änderungen des Agent-Abrufs ein, wie in 2025-08-01-preview implementiert:

• Ersetzt agents durch knowledgebases Mehrere Eigenschaften im Zusammenhang mit Wissensquellen wurden aus der Wissensbasisdefinition und zur Abrufen-Aktion verschoben.
• Wissensquelleneigenschaften werden umgestaltet und implementieren ein neues ingestionParameters Objekt für Wissensquellen, die eine Indexerpipeline generieren.

Weitere Informationen zu Änderungen und Codemigration finden Sie unter wichtige Änderungen in 2025-11-01-preview und in der Migrationsanleitung.

Für alle anderen vorhandenen APIs gibt es keine Verhaltensänderungen. Sie können in der neuen API-Version tauschen, und Ihr Code wird wie zuvor ausgeführt.

Upgrade auf 2025-09-01

2025-09-01 ist die neueste stabile REST-API-Version und fügt allgemeine Verfügbarkeit für den OneLake-Indexer, die Dokumentlayoutfähigkeit und andere APIs hinzu.

Falls Sie ein Upgrade von 2024-07-01 durchführen und keine Vorschaufeatures verwenden, gibt es keine Breaking Changes. Um die neue stabile Version zu verwenden, ändern Sie die API-Version, und testen Sie Ihren Code.

Upgrade auf 2025-08-01-preview

2025-08-01-preview führt die folgenden Breaking Changes an Wissensagents ein, die mithilfe von 2025-05-01-preview erstellt wurden:

• Ersetzt targetIndexes durch knowledgeSources
• Entfernt defaultMaxDocsForReranker ersatzlos

Andernfalls gibt es keine Breaking Changes für vorhandene APIs. Sie können in der neuen API-Version tauschen, und Ihr Code wird wie zuvor ausgeführt.

Upgrade auf 2025-05-01-preview

2025-05-01-preview bietet neue Features, aber es gibt keine Verhaltensänderungen für vorhandene APIs. Sie können in der neuen API-Version tauschen, und Ihr Code wird wie zuvor ausgeführt.

Upgrade auf 2025-03-01-preview

2025-03-01-preview bietet neue Features, aber es gibt keine Verhaltensänderungen für vorhandene APIs. Sie können in der neuen API-Version tauschen, und Ihr Code wird wie zuvor ausgeführt.

Upgrade auf 2024-11-01-preview

2024-11-01-preview-Abfrageumschreibung, Dokumentlayoutfähigkeit, schlüssellose Abrechnung für die Verarbeitung von Fähigkeiten, Markdown-Analysemodus und Neubewertungsoptionen für komprimierte Vektoren.

Wenn Sie von 2024-09-01-preview ein Upgrade vornehmen, können Sie die neue API-Version einfügen und Ihr Code wird wie zuvor ausgeführt.

Die neue Version führt jedoch Syntaxänderungen an vectorSearch.compressions ein:

• Ersetzt rerankWithOriginalVectors durch enableRescoring
• Verschiebt defaultOversampling zu einem neuen rescoringOptions-Eigenschaftsobjekt

Die Abwärtskompatibilität wird aufgrund einer internen API-Zuordnung beibehalten, es wird jedoch empfohlen, die Syntax zu ändern, wenn Sie die neue Vorschauversion übernehmen. Einen Vergleich der Syntax finden Sie unter Komprimieren von Vektoren mit skalarer oder binärer Quantisierung.

Upgrade auf 2024-09-01-preview

2024-09-01-preview fügt Matryoshka Representation Learning (MRL)-Komprimierung für text-embedding-3-Modelle, gezielte Vektorfilterung für Hybridabfragen, Details für Vektorteilbewertungen zum Debuggen und Tokensegmentierung für Textteilungsfähigkeiten hinzu.

Wenn Sie von 2024-05-01-preview ein Upgrade vornehmen, können Sie die neue API-Version einfügen und Ihr Code wird wie zuvor ausgeführt.

Upgrade auf 2024-07-01

2024-07-01 ist ein allgemeines Release. Die früheren Previewfunktionen sind jetzt allgemein verfügbar: integriertes Chunking und Vektorisierung (Skill zur Textaufteilung, AzureOpenAIEmbedding-Skill), Abfrage-Vektorisierung basierend auf AzureOpenAIEmbedding, Vektorkomprimierung (skalare Quantisierung, binäre Quantisierung, gespeicherte Eigenschaft, reduzierte Datentypen).

Wenn Sie ein Upgrade von 2024-05-01-preview auf eine stabile Version durchführen, gibt es keine Breaking Changes. Um die neue stabile Version zu verwenden, ändern Sie die API-Version, und testen Sie Ihren Code.

Es gibt einschneidende Änderungen, wenn Sie direkt ein Upgrade von 2023-11-01 durchführen. Führen Sie die für jede neuere Vorschauversion beschriebenen Schritte aus, um von 2023-11-01 zu 2024-07-01 zu migrieren.

Upgrade auf 2024-05-01-preview

2024-05-01-preview fügt einen Indexer für Microsoft OneLake, binäre Vektoren und weitere Einbettungsmodelle hinzu.

Wenn Sie ein Upgrade von 2024-03-01-preview durchführen, erfordert der AzureOpenAIEmbedding-Skill jetzt die Eigenschaften 'Modellname' und 'Dimensionen'.

1. Durchsuchen Sie Ihre Codebasis nach AzureOpenAIEmbedding-Verweisen.

2. Legen Sie modelName auf „text-embedding-ada-002“ und dimensions auf „1536“ fest.

Upgrade auf 2024-03-01-preview

2024-03-01-preview fügt schmale Datentypen, skalare Quantisierung und Vektorspeicheroptionen hinzu.

Wenn Sie ein Upgrade von 2023-10-01-preview durchführen, gibt es keine Breaking Changes. Es gibt jedoch einen Verhaltensunterschied: Für 2023-11-01 und neuere Vorschauen wurde der vectorFilterMode-Standardwert für Filterausdrücke von „postfilter“ auf „prefilter“ geändert.

1. Durchsuchen Sie Ihre Codebasis nach vectorFilterMode-Verweisen.

2. Wenn die Eigenschaft explizit festgelegt ist, ist keine Aktion erforderlich. Wenn Sie sich auf den Standardwert verlassen haben, besteht das neue Standardverhalten darin, vor der Abfrageausführung zu filtern. Wenn Sie den Filtervorgang nach der Abfrageausführung ausführen möchten, legen Sie vectorFilterMode explizit auf „postfilter“ fest, um das alte Verhalten beizubehalten.

Upgrade auf 2023-11-01

2023-11-01 ist ein allgemeines Release. Die früheren Vorschaufeatures sind jetzt allgemein verfügbar: Semantischer Rangierer und Vektorunterstützung.

Es gibt keine Breaking Changes bei 2023-10-01-preview, aber es gibt mehrere Breaking Changes zwischen 2023-07-01-preview und 2023-11-01. Weitere Informationen finden Sie unter Upgrade von 2023-07-01-preview.

Um die neue stabile Version zu verwenden, ändern Sie die API-Version, und testen Sie Ihren Code.

Upgrade auf 2023-10-01-preview

2023-10-01-preview war die erste Vorschauversion, in der eine integrierte Datensegmentierung und Vektorisierung während der Indizierung und eine integrierte Abfragevektorisierung hinzugefügt wurden. Die Version unterstützt auch die Vektorindizierung und Abfragen aus der vorherigen Version.

Wenn Sie ein Upgrade von der vorherigen Version durchführen, finden Sie im nächsten Abschnitt die erforderlichen Schritte.

Upgrade von der Vorschauversion 2023-07-01

Verwenden Sie diese API-Version nicht. Sie implementiert eine Vektorabfragesyntax, die mit einer neueren API-Version nicht kompatibel ist.

2023-07-01-preview ist jetzt veraltet. Daher sollten Sie unter keinen Umständen neuen Code auf dieser Version erstellen oder ein Upgrade auf dieser Version durchführen. In diesem Abschnitt wird der Migrationspfad von 2023-07-01-preview zu einer neueren API-Version beschrieben.

Portalupgrade für Vektorindizes

Das Azure-Portal unterstützt einen 1-Klick-Upgradepfad für Indizes von 2023-07-01-preview. Das Portal erkennt Vektorfelder und stellt die Schaltfläche Migrieren bereit.

• Der Migrationspfad führt von 2023-07-01-preview zu 2024-05-01-preview.
• Aktualisierungen sind auf Vektorfelddefinitionen und Konfigurationen für den Vektorsuchalgorithmus beschränkt.
• Updates sind unidirektional. Sie können das Upgrade nicht rückgängig machen. Nachdem für den Index ein Upgrade durchgeführt wurde, müssen Sie 2024-05-01-preview oder eine höhere Version verwenden, um den Index abzufragen.

Es gibt keine Portalmigration für das Upgraden der Vektorabfragesyntax. Informationen zu Änderungen der Abfragesyntax finden Sie unter Codeupgrades.

Bevor Sie Migrieren auswählen, wählen Sie JSON bearbeiten aus, um zuerst das aktualisierte Schema zu überprüfen. Sie sollten ein Schema finden, das mit den im Abschnitt Codeupgrade beschriebenen Änderungen übereinstimmt. Die Portalmigration behandelt nur einen Index mit einer einzigen Vektorsuchalgorithmuskonfiguration. Es wird ein Standardprofil erstellt, das dem Vektorsuchalgorithmus 2023-07-01-preview zugeordnet ist. Indizes mit mehreren Vektorsuchkonfigurationen erfordern eine manuelle Migration.

Codeupgrade für Vektorindizes und Abfragen

Die Unterstützung der Vektorsuche wurde in Erstellen oder Aktualisieren des Indexes (2023-07-01-preview) eingeführt.

Das Upgrade von 2023-07-01-preview auf eine neuere stabile oder Vorschauversion erfordert Folgendes:

• Umbenennung und Umstrukturierung der Vektorkonfiguration im Index
• Neuschreiben der Vektorabfragen

Verwenden Sie die Anweisungen in diesem Abschnitt zum Migrieren von Vektorfeldern, Konfigurationen und Abfragen von 2023-07-01-preview.

1. Rufen Sie Index abrufen auf, um die vorhandene Definition abzurufen.

2. Ändern Sie die Vektorsuchkonfiguration. 2023-11-01 und höhere Versionen führen das Konzept von Vektorprofilen ein, die vektorbezogene Konfigurationen unter einem Namen bündeln. Neuere Versionen benennen außerdem algorithmConfigurations in algorithms um.

   • Benennen Sie algorithmConfigurations in algorithms um. Dies ist nur eine Umbenennung des Arrays. Die Inhalte sind abwärtskompatibel. Dies bedeutet, dass Ihre vorhandenen HNSW-Konfigurationsparameter verwendet werden können.

   • Fügen Sie profiles hinzu, und geben Sie einen Namen und eine Algorithmuskonfiguration für jeden einzelnen an.

   Vor der Migration (2023-07-01-preview):

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

   Nach der 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. Ändern Sie Vektorfelddefinitionen, indem Sie vectorSearchConfiguration durch vectorSearchProfile ersetzen. Stellen Sie sicher, dass der Profilname in eine neue Vektorprofildefinition und nicht in den Konfigurationsnamen des Algorithmus aufgelöst wird. Andere Vektorfeldeigenschaften bleiben unverändert. Sie können z. B. weder filterbar, sortierbar oder facettierbar sein und auch keine Analysetools oder Normalisierer oder Synonymzuordnungen verwenden.

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

   Nach (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. Rufen Sie Erstellen oder Aktualisieren des Indexes auf, um die Änderungen zu veröffentlichen.

5. Ändern Sie Search-POST, um die Abfragesyntax zu ändern. Diese API-Änderung ermöglicht die Unterstützung für polymorphe Vektorabfragetypen.

   • Benennen Sie vectors in vectorQueries um.
   • Fügen Sie für jede Vektorabfrage kind hinzu, und legen Sie den Wert auf vector fest.
   • Benennen Sie für jede Vektorabfrage value in vector um.
   • Fügen Sie optional vectorFilterMode hinzu, wenn Sie Filterausdrücke verwenden. Der Standardwert für Indizes, die nach 2023-10-01 erstellt wurden, ist „prefilter“. Indizes, die vor diesem Datum erstellt wurden, unterstützen nur Postfilter, unabhängig davon, wie Sie den Filtermodus festlegen.

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

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

Diese Schritte führen die Migration zur stabilen API-Version 2023-11-01 oder neueren API-Vorschauversionen durch.

Upgrade auf 2020-06-30

In dieser Version gibt es eine umwälzende Änderung und mehrere Verhaltensunterschiede. Allgemein verfügbare Features umfassen:

• Wissensspeicher, dauerhafte Speicherung von angereicherten Inhalten, die durch Fähigkeiten erstellt wurden, um sie anschließend für Downstreamprozesse zu analysieren und durch andere Anwendungen zu verarbeiten. Ein Wissensspeicher wird über Azure KI-Suche REST-APIs erstellt, befindet sich aber in Azure Storage.

Breaking Change

Code, der für frühere API-Versionen geschrieben wurde, wird ab 2020-06-30 und höher unterbrochen, wenn der Code folgende Funktionalität enthält:

• Ein Edm.Date-Literal (ein Datum bestehend aus Jahr-Monat-Tag, z. B. 2020-12-12) in Filterausdrücken muss dem Edm.DateTimeOffset-Format folgen: 2020-12-12T00:00:00Z. Diese Änderung war erforderlich, um fehlerhafte oder unerwartete Abfrageergebnisse aufgrund von Zeitzonenunterschieden zu behandeln.

Verhaltensänderungen

• Der BM25-Rangfolgealgorithmus ersetzt den bisherigen Rangfolgealgorithmus mit neuerer Technologie. Dienste, die nach 2019 erstellt wurden, verwenden diesen Algorithmus automatisch. Für ältere Dienste müssen Sie Parameter festlegen, um den neuen Algorithmus zu verwenden.

• Die Behandlung von Nullwerten in sortierten Ergebnissen hat sich in dieser Version geändert, Nullwerte werden bei asc-Sortierung zuerst und bei desc-Sortierung zuletzt angezeigt. Wenn Sie Code zur Behandlung von Nullwerten geschrieben haben, seien Sie sich dieser Änderung bewusst.

Upgrade auf 2019-05-06

Zu den Features, die in dieser API-Version allgemein verfügbar wurden, gehören:

• AutoVervollständigen ist eine Funktion zur Textvervollständigung, mit der ein teilweise eingegebener Begriff vervollständigt wird.
• Komplexe Typen bieten native Unterstützung für strukturierte Objektdaten in einem Suchindex.
• Der Analysemodus JsonLines ist Teil der Azure-Blobindizierung. Dabei wird ein Suchdokument pro JSON-Entität erstellt, die durch eine neue Zeile getrennt ist.
• KI-Anreicherung bietet eine Indizierung, die auf den KI-basierten Anreicherungs-Tools von Foundry basiert.

Aktuelle Änderungen

Code, der für eine frühere API-Version geschrieben wurde, wird ab 2019-05-06 und höher unterbrochen, wenn er folgende Funktionalität enthält:

1. Type-Eigenschaft für Azure Cosmos DB. Für Indexer, die auf eine Azure Cosmos DB for NoSQL-API-Datenquelle abzielen, ändern Sie "type": "documentdb" in "type": "cosmosdb".

2. Wenn die Indizierungsfehlerbehandlung Verweise auf die status-Eigenschaft enthält, sollten Sie sie entfernen. Wir haben den Status aus der Fehlerantwort entfernt, da er keine nützlichen Informationen bereitstellte.

3. Verbindungszeichenfolgen für Datenquellen werden in der Antwort nicht mehr zurückgegeben. Ab den API-Versionen 2019-05-06 und 2019-05-06-Preview gibt die Datenquellen-API als Antwort auf einen REST-Vorgang keine Verbindungszeichenfolgen mehr zurück. In früheren API-Versionen wurde in Azure AI Search für mithilfe der POST-Methode erstellte Datenquellen 201 zurückgegeben, gefolgt von der OData-Antwort, welche die Verbindungszeichenfolge im Textformat enthielt.

4. Der kognitive Skill „Erkennung benannter Entitäten“ wurde eingestellt. Wenn Sie den Skill Erkennung benannter Entitäten im Code aufgerufen haben, schlägt der Aufruf fehl. Die Ersatzfunktion ist Skill „Entitätserkennung“ (V3). Führen Sie unter Berücksichtigung der Empfehlungen in Veraltete Skills eine Migration zu einem unterstützten Skill durch.

Aktualisieren von komplexen Typen

In API-Version 2019-05-06 wurde formale Unterstützung für komplexe Typen hinzugefügt. Wenn in Ihrem Code frühere Empfehlungen für Äquivalenz zu komplexen Typen in 2017-11-11-Preview oder 2016-09-01-Preview implementiert wurden, gelten ab Version 2019-05-06 einige neue und geänderte Grenzwerte, die Sie berücksichtigen müssen:

• Die Grenzwerte für die Tiefe der Unterfelder und die Anzahl der komplexen Sammlungen pro Index wurden abgesenkt. Wenn Sie Indizes erstellt haben, die diese Grenzwerte mithilfe der Vorschau-API-Versionen überschreiten, schlägt jeder Versuch, sie mithilfe der API-Version 2019-05-06 zu aktualisieren oder neu zu erstellen, fehl. Wenn Sie sich in dieser Situation befinden, müssen Sie Ihr Schema umgestalten, damit es in die neuen Grenzwerte passt, und dann Ihren Index neu erstellen.

• Ab API-Version 2019-05-06 gilt ein neuer Grenzwert für die Anzahl der Elemente von komplexen Sammlungen pro Dokument. Wenn Sie mit den API-Vorschauversionen Indizes mit Dokumenten erstellt haben, die diese Grenzwerte überschreiten, treten beim Neuindizieren dieser Daten mit API-Version 2019-05-06 Fehler auf. Wenn Sie sich in dieser Situation befinden, müssen Sie die Anzahl der Elemente von komplexen Sammlungen pro Dokument reduzieren, bevor Sie die Daten neu indizieren.

Weitere Informationen finden Sie unter Grenzwerte für den Azure AI Search-Dienst.

Wie man eine veraltete komplexe Typstruktur aktualisiert

Wenn Ihr Code komplexe Typen mit einer der älteren API-Vorschauversionen verwendet, verwenden Sie möglicherweise ein Indexdefinitionsformat, das wie folgt aussieht:

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

In API-Version 2017-11-11-Preview wurde ein neueres strukturähnliches Format zum Definieren von Indexfeldern eingeführt. In dem neuen Format enthält jedes komplexe Feld eine Feldsammlung, in der die Unterfelder definiert sind. In API-Version 2019-05-06 wird ausschließlich dieses neue Format verwendet, sodass beim Erstellen oder Aktualisieren eines Index mit dem alten Format Fehler auftreten. Wenn Sie Indizes mit dem alten Format erstellt haben, müssen Sie diese mithilfe der API-Version 2017-11-11-Preview in das neue Format ändern, bevor sie mit der API-Version 2019-05-06 verwaltet werden können.

Mit den folgenden Schritten können Sie flache Indizes mithilfe der API-Version 2017-11-11-Preview in das neue Format ändern:

1. Führen Sie eine GET-Anforderung aus, um den Index abzurufen. Wenn es bereits im neuen Format ist, sind Sie fertig.

2. Wandeln Sie den Index vom flachen Format in das neue Format um. Sie müssen für diese Aufgabe Code schreiben, da zum Zeitpunkt der Erstellung dieses Artikels kein Beispielcode vorhanden ist.

3. Führen Sie eine PUT-Anforderung aus, um den Index auf das neue Format zu aktualisieren. Vermeiden Sie das Ändern anderer Indexdetails (z. B. die Suchbarkeit/Filterbarkeit von Feldern), da Änderungen, die den physischen Ausdruck des vorhandenen Index beeinflussen, über die Update-Index-API nicht zulässig sind.

Steuern von Flugzeugupgrades

Gilt für:2014-07-31-Preview, 2015-02-28und 2015-08-19

Die listQueryKeys GET-Anforderung für ältere Suchverwaltungs-API-Versionen ist jetzt veraltet. Es wird empfohlen, zu der neuesten Version der stabilen Steuerebenen-API zu migrieren, um die listQueryKeys POST-Anforderung zu verwenden.

1. Ändern Sie im vorhandenen Code den api-version Parameter in die neueste Version (2025-05-01).

2. Anforderung von GET zu POST umformulieren.

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

3. Wenn Sie ein Azure SDK verwenden, empfiehlt es sich, ein Upgrade auf die neueste Version durchzuführen.

Nächste Schritte

Sehen Sie sich die Referenzdokumentation für die Search-REST-API an. Wenn Probleme auftreten, können Sie sich über Stack Overflow an uns wenden oder den Support kontaktieren.