Upgrade auf die neueste REST-API in Azure KI-Suche

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:

Gezielte Vorgänge	REST-API	Status
Datenebene	2026-04-01	Stabil
Datenebene	2026-05-01-preview	Vorschau
Steuerebene	2025-05-01	Stabil
Steuerebene	2026-03-01-preview	Vorschau

Aktualisierungsanweisungen konzentrieren sich auf Codeänderungen, damit Sie kritische Änderungen aus früheren Versionen überwinden können und vorhandener Code wie zuvor auf der neueren API-Version ausgeführt wird. Sobald Ihr Code funktionsfähig ist, können Sie entscheiden, ob neuere Funktionen verwendet werden sollen. Weitere Informationen zu neuen Features finden Sie unter What's new in Azure KI-Suche.

Es wird empfohlen, die API-Versionen nacheinander zu aktualisieren, wobei jede Version durchgearbeitet wird, bis Sie auf die neueste Version gelangen.

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

Hinweis

REST-API-Referenzdokumente sind jetzt versionsiert. Öffnen Sie für versionsspezifische Inhalte eine Referenzseite, und verwenden Sie dann die Auswahl oberhalb des Inhaltsverzeichnisses, um Ihre Version auszuwählen.

Wann soll ein Upgrade durchgeführt werden?

Azure KI-Suche unterbricht die Abwärtskompatibilität als letztes Mittel. Das Upgrade ist erforderlich, wenn:

• Ihr Code verweist auf eine veraltete oder nicht mehr unterstützte API-Version und unterliegt einer oder mehreren inkompatiblen Änderungen.

• Ihr Code schlägt fehl, wenn nicht erkannte Eigenschaften in einer API-Antwort zurückgegeben werden. Als bewährte Methode sollte Ihre Anwendung Eigenschaften ignorieren, die sie nicht verstehen.

• Ihr Code speichert API-Anforderungen und versucht, sie erneut an die neue API-Version zu senden. Dies könnte beispielsweise passieren, wenn Ihre Anwendung Fortsetzungstoken, die von der Such-API zurückgegeben werden, beibehält (weitere Informationen finden Sie @search.nextPageParameters in der Such-API-Referenz).

Anleitung zur Aktualisierung

1. Wenn Sie eine Datenebenenversion aktualisieren, überprüfen Sie , was in der neuen API-Version veröffentlicht wurde.

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 eine 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 beheben Sie alle Breaking Changes für jede neuere API-Version, bis Sie bei der neuesten stabilen oder Vorschauversion ankommen.

Aktuelle Änderungen

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

Wichtige Änderungen für den Agent-Abruf

2026-04-01 ist die erste stabile REST-API-Version für den agentischen Abruf. Es führt folgende grundlegende Änderungen gegenüber 2025-11-01-preview ein:

• Antwortsynthese, Abfrageplanung und konfigurierbare Begründungsaufwand werden entfernt. Der Abruf gibt nur extraktiven, abgesicherten Inhalt zurück.

• Die Abrufeanforderungsstruktur ändert sich: messages wird durch intents ersetzt, und mehrere Parameter werden umbenannt oder entfernt.

• Die Berechtigungsfilterung auf Dokumentebene für Blob- und OneLake-Wissensquellen wird nicht unterstützt.

Die vollständige Liste der Änderungen und Migrationsschritte auf Eigenschaftsebene finden Sie unter Migrieren des agentischen Abrufcodes.

Breaking Changed für Wissensagenten

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

Die vollständige Liste der Änderungen und Migrationsschritte auf Eigenschaftsebene finden Sie unter Migrieren des agentischen Abrufcodes.

Grundlegende Änderungen für Clientcode, der Verbindungsinformationen liest

Gültig am 29. März 2024 und gilt für alle unterstützten REST-APIs:

• GET Skillset, GET Index und GET Indexer geben keine Schlüssel oder Verbindungseigenschaften mehr in einer Antwort zurück. Dies ist eine wichtige Änderung, wenn Sie nachgelagerten Code haben, der Schlüssel oder Verbindungen (vertrauliche Daten) aus einer GET-Antwort 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 wie Azure Storage oder Azure Cosmos DB abrufen müssen, verwenden Sie die APIs dieser Ressource und veröffentlichte Anleitungen, um die Informationen abzurufen.

Unterbrechen von Änderungen für semantischen Rangierer

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

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

• Updates für alle API-Versionen am 14. Juli 2023 zu den von Microsoft gehosteten Semantikmodellen machten den semantischen Sortierer sprachunabhängig, wobei die Eigenschaft queryLanguage effektiv außer Betrieb genommen wurde. 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

Es wird im Upgrade-Leitfaden davon ausgegangen, dass ein Upgrade von der neuesten Vorversion 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 2026-05-01-Preview

2026-05-01-preview fügt neue Wissensquellentypen, neue Parameter für die Abrufaktion, neue SharePoint Indexerinhaltstypen und ACL-Optionen und andere Funktionen hinzu.

Es gibt keine Änderungen auf Drahtebene von 2025-11-01-preview. Wenn Sie jedoch das Python oder JavaScript SDK für den agentischen Abruf verwenden, wird der abrufende Client in KnowledgeBaseRetrievalClient umbenannt, und retrieveKnowledge(...) wird durch retrieve(...) ersetzt. Anleitungen zur SDK-Migration finden Sie unter Migrieren des agentischen Abrufcodes.

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 2026-04-01

2026-04-01 ist die neueste stabile REST-API-Version. Es fördert die agentenbasierte Suche, die Auswahl von Wissensquellen und die allgemeine Verfügbarkeit verschiedener Fähigkeiten und Funktionen.

Bevor Sie das Upgrade durchführen, prüfen Sie, ob eine der folgenden 2026-04-01 wichtigen Änderungen, die zu Inkompatibilitäten führen können, auf Ihren Code zutreffen:

• Sechs Eigenschaften werden aus der GenAI Prompt-Qualifikationsdefinition entfernt: httpMethod, , timeout, batchSize, degreeOfParallelism, httpHeadersund authResourceId. Entfernen Sie diese Eigenschaften vor dem Upgrade. Definitionen, die diese Eigenschaften weiterhin enthalten, geben einen 400 Bad Request Fehler zurück.

• Der Agent-Abruf erfordert jetzt eine eigene Abrechnungsgenehmigung. Wenn Sie derzeit über semanticSearch=standard verfügen, müssen Sie vor dem Upgrade explizit knowledgeRetrieval=standard festlegen. Weitere Informationen finden Sie unter Aktivieren oder Deaktivieren von agentischer Abrufabrechnung.

• Wenn Ihr Agent-Abrufcode auf die 2025-11-01-preview abzielt, entfernt 2026-04-01 mehrere Vorschaufunktionen und standardisiert den Abruf um die Absichten-Eingabe, das extrahierende Ergebnis und minimales Schließen. Weitere Informationen finden Sie unter Migration Ihres Agentenabrufcodes.

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-11-01-Preview

2025-11-01-preview führt die folgenden grundlegenden Änderungen an der agentenbasierten Abfrage ein, wie sie in 2025-08-01-preview implementiert ist:

• agents Ersetzt 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.

Die vollständige Liste der Änderungen und Migrationsschritte auf Eigenschaftsebene finden Sie unter Migrieren des agentischen Abrufcodes.

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 eine stabile REST-API-Version, die allgemeine Verfügbarkeit für den OneLake-Indexer, die Dokumentlayoutfähigkeit und andere APIs hinzufügt.

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-Vorschau

2025-08-01-preview führt die folgenden einschneidenden Änderungen an Wissensagenten ein, die mit 2025-05-01-preview erstellt wurden.

• targetIndexes Ersetzt durch knowledgeSources.
• Entfernt defaultMaxDocsForReranker ohne Ersatz.

Andernfalls gibt es 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 Version 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, Dokumentlayout-Funktion, schlüssellose Abrechnung für die Verarbeitung von Fähigkeiten, Markdown-Parsing-Modus und Neubewertungsoptionen für komprimierte Vektoren.

Wenn Sie ein Upgrade von 2024-09-01-preview durchführen, können Sie die neue API-Version einfügen und Ihr Code läuft wie zuvor weiter.

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

• Ersetzt rerankWithOriginalVectors mit enableRescoring
• Wechselt 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 eine Matryoshka Representation Learning (MRL)-Komprimierung für text-embedding-3-Modelle, gezielte Vektorfilterung für Hybridabfragen, Vektor-Subscore-Details zum Debuggen und das Token-Chunking für den Text Split Skill hinzu.

Wenn Sie ein Upgrade von 2024-05-01-preview durchführen, können Sie die neue API-Version einfügen und Ihr Code läuft wie zuvor weiter.

Upgrade auf 2024-07-01

2024-07-01 ist ein allgemeines Release. Die früheren Vorschaufeatures sind jetzt allgemein verfügbar: integriertes Chunking und Vektorisierung (Text Split Skill, AzureOpenAIEmbedding Skill), Abfragevektorizer basierend auf AzureOpenAIEmbedding, Vektorkomprimierung (skalare Quantisierung, binäre Quantisierung, gespeicherte Eigenschaft, schmale 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.

Wenn Sie ein Upgrade direkt von 2023-11-01 durchführen, kann es umwälzende Änderungen geben. Führen Sie die Schritte aus, die für jede neuere Vorschau beschrieben sind, 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 mehr Einbettungsmodelle hinzu.

Wenn Sie ein Upgrade von 2024-03-01-preview durchführen, erfordert der AzureOpenAIEmbedding-Skill jetzt einen Modellnamen und eine Dimensionseigenschaft.

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 die vectorFilterMode Standardeinstellung von Postfilter zu Prefilter für Filterausdrücke 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 eine Filterung nach der Abfrage wünschen, setzen Sie vectorFilterMode explizit auf Postfilter, 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.

Von 2023-10-01-preview gibt es keine grundlegenden Änderungen, aber von 2023-07-01-preview zu 2023-11-01 gibt es mehrere grundlegende Änderungen.. 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, um integrierte Datenblöcke und Vektorisierung während der Indizierung und integrierten Abfragevektorisierung hinzuzufügen. Es unterstützt auch die Vektorindizierung und Abfragen aus der vorherigen Version.

Wenn Sie ein Upgrade von der vorherigen Version durchführen, enthält der nächste Abschnitt die 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, sodass Sie keinen neuen Code auf dieser Version basieren sollten, noch sollten Sie ein Upgrade auf diese Version unter keinen Umständen durchführen. In diesem Abschnitt wird der Migrationspfad von 2023-07-01-preview jeder neueren API-Version erläutert.

Portalupgrade für Vektorindizes

Azure Portal unterstützt einen Ein-Klick-Upgradepfad für 2023-07-01-preview Indizes. Es erkennt Vektorfelder und stellt eine Schaltfläche " Migrieren " bereit.

• Der Migrationspfad ist von 2023-07-01-preview zu 2024-05-01-preview.
• Aktualisierungen sind auf Vektorfelddefinitionen und Vektorsuchalgorithmuskonfigurationen beschränkt.
• Updates sind einseitig. Sie können das Upgrade nicht rückgängig machen. Nachdem der Index aktualisiert wurde, müssen Sie 2024-05-01-preview oder eine spätere Version verwenden, um den Index abzufragen.

Es gibt keine Portalmigration für das Upgrade der Vektorabfragesyntax. Siehe Codeupgrades für Abfragesyntaxänderungen .

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 den im Codeupgradeabschnitt beschriebenen Änderungen entspricht. Die Portalmigration behandelt nur Indizes mit einer Konfiguration für den Vektorsuchalgorithmus. Es erstellt ein Standardprofil, das dem 2023-07-01-preview Vektorsuchalgorithmus zugeordnet ist. Indizes mit mehreren Vektorsuchkonfigurationen erfordern eine manuelle Migration.

Codeupgrade für Vektorindizes und Abfragen

Die Unterstützung der Vektorsuche wurde in Create or Update Index (2023-07-01-preview) eingeführt.

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

• Umbenennen und Neustrukturieren der Vektorkonfiguration im Index
• Umschreiben Ihrer 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 spätere Versionen führen das Konzept von Vektorprofilen ein, die vektorbezogene Konfigurationen unter einem Namen bündeln. Neuere Versionen benennen auch algorithmConfigurations in algorithms um.

   • Umbenennen algorithmConfigurations in algorithms. Dies ist nur eine Umbenennung des Arrays. Der Inhalt ist 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 Von Vektorfelddefinitionen, ersetzen vectorSearchConfiguration durch vectorSearchProfile. 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-Vorschau):

     {
         "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 Index erstellen oder aktualisieren 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.

   • Umbenennen vectors in vectorQueries.
   • Fügen Sie kind für jede Vektorabfrage hinzu und setzen Sie es auf vector fest.
   • Benennen Sie value für jede Vektorabfrage in vector um.
   • Fügen Sie optional hinzu vectorFilterMode , wenn Sie Filterausdrücke verwenden. Der Standard ist der Vorfilter für Indizes, die nach dem Zeitpunkt 2023-10-01 erstellt wurden. Indizes, die vor diesem Datum erstellt wurden, unterstützen nur den Postfilter, unabhängig davon, wie Sie den Filtermodus festlegen.

   Vor (2023-07-01-Vorschau):

   {
       "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 2023-11-01 stabilen API-Version oder neueren Vorschau-API-Versionen durch.

Upgrade auf 2020-06-30

In dieser Version gibt es eine wichtige Änderung und mehrere Verhaltensunterschiede. Zu den allgemein verfügbaren Features gehören:

• Wissensspeicher, permanente Speicherung von angereicherten Inhalten, die durch Skillsets erstellt wurden, erstellt für nachgelagerte Analyse und Verarbeitung durch andere Anwendungen. Ein Wissensspeicher wird über Azure KI-Suche REST-APIs erstellt, befindet sich jedoch in Azure Storage.

Breaking Change

Code, der für frühere API-Versionen geschrieben wurde, funktioniert nicht mehr ab 2020-06-30 und später, wenn der Code die folgenden Funktionen enthält:

• Alle Edm.Date Literale (ein Datum, das aus Jahr, Monat, Tag besteht, z. B. 2020-12-12) in Filterausdrücken müssen dem Edm.DateTimeOffset Format entsprechen: 2020-12-12T00:00:00Z. Diese Änderung war erforderlich, um fehlerhafte oder unerwartete Abfrageergebnisse aufgrund von Zeitzonenunterschieden zu behandeln.

Verhaltensänderungen

• Der BM25-Bewertungsalgorithmus ersetzt den vorherigen Bewertungsalgorithmus durch neuere 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.

• Sortierte Ergebnisse für NULL-Werte wurden in dieser Version geändert, wobei NULL-Werte zuerst angezeigt werden, wenn die Sortierung asc ist und zuletzt, wenn die Sortierung desc ist. Wenn Sie Code geschrieben haben, um zu behandeln, wie Nullwerte sortiert werden, beachten Sie diese Änderung.

Upgrade auf 2019-05-06

Features, die in dieser API-Version allgemein verfügbar wurden, umfassen:

• 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 im Suchindex.
• JsonLines-Analysemodi ist Teil der Azure-Blobindizierung. Dabei wird ein Suchdokument pro JSON-Entität erstellt, die durch eine neue Zeile getrennt ist.
• Die KI-Anreicherung stellt eine Indizierung bereit, die mithilfe der KI-Anreicherungsmotoren von Foundry Tools arbeitet.

Aktuelle Änderungen

Code, der mit einer früheren API-Version geschrieben wurde, funktioniert nicht mehr in 2019-05-06 und späteren Versionen, wenn es die folgenden Funktionen enthält:

1. Eigenschaft "Type" für Azure Cosmos DB. Für Indexer, die auf eine Azure Cosmos DB für NoSQL API abzielen Datenquelle, ä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 gab Azure KI-Suche für Datenquellen, die mit POST erstellt wurden, 201 zurück, gefolgt von der OData-Antwort, die die Verbindungszeichenfolge im Klartext enthielt.

4. Der kognitive Skill „Erkennung benannter Entitäten“ wurde eingestellt. Wenn Sie die Fähigkeit zur Namensentitätserkennung in Ihrem Code aufgerufen haben, schlägt der Aufruf fehl. Die Ersetzungsfunktion ist Entity Recognition Skill (V3). Befolgen Sie die Empfehlungen in veralteten Fähigkeiten , um zu einer unterstützten Fähigkeit zu migrieren.

Aufrüsten komplexer Typen

Die API-Version 2019-05-06 hat formale Unterstützung für komplexe Typen hinzugefügt. Wenn Ihr Code frühere Empfehlungen für die Gleichwertigkeit komplexer Typen in 2017-11-11-Preview oder 2016-09-01-Preview implementiert hat, gibt es einige neue und geänderte Grenzwerte, die mit der Version 2019-05-06 beginnen, die Sie beachten müssen:

• Die Grenzwerte für die Tiefe von Unterfeldern und die Anzahl komplexer Auflistungen pro Index wurden verringert. 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 so neu gestalten, dass es in die neuen Grenzwerte passt, und dann den Index neu erstellen.

• Es gibt eine neue Beschränkung für die Anzahl der Elemente komplexer Sammlungen pro Dokument, die mit der API-Version 2019-05-06 eingeführt wird. Wenn Sie Indizes mit Dokumenten erstellt haben, die diese Grenzwerte überschreiten, indem Sie die Vorschau-API-Versionen verwenden, schlägt jeder Versuch, diese Daten mit API-Version 2019-05-06 neu zu indizieren, fehl. Wenn Sie sich in dieser Situation befinden, müssen Sie die Anzahl komplexer Sammlungselemente pro Dokument reduzieren, bevor Sie Ihre Daten neu indizieren.

Weitere Informationen finden Sie unter Service-Grenzwerte für Azure KI-Suche.

So aktualisieren Sie eine alte komplexe Typstruktur

Wenn Ihr Code komplexe Typen mit einer der älteren Vorschau-API-Versionen 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" }
  ]
}  

Ein neueres strukturähnliches Format zum Definieren von Indexfeldern wurde in der API-Version 2017-11-11-Previeweingeführt. Im neuen Format verfügt jedes komplexe Feld über eine Feldauflistung, in der seine Unterfelder definiert sind. In API Version 2019-05-06 wird dieses neue Format exklusiv verwendet und versucht, einen Index mit dem alten Format zu erstellen oder zu aktualisieren, schlägt fehl. Wenn Sie Indizes mit dem alten Format erstellt haben, müssen Sie die API-Version 2017-11-11-Preview verwenden, um sie auf das neue Format zu aktualisieren, bevor sie mit API-Version 2019-05-06 verwaltet werden können.

Sie können flache Indizes mit den folgenden Schritten mithilfe der API-Version 2017-11-11-Previewauf das neue Format aktualisieren:

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

2. Übersetzen Sie den Index aus dem Flachformat in das neue Format. Sie müssen Code für diese Aufgabe schreiben, da zum Zeitpunkt dieses Schreibens kein Beispielcode verfügbar ist.

3. Führen Sie eine PUT-Anforderung aus, um den Index in das neue Format zu aktualisieren. Vermeiden Sie das Ändern anderer Details des Indexes, z. B. die Durchsuchbarkeit/Filterbarkeit von Feldern, da Änderungen, die sich auf den physischen Ausdruck des vorhandenen Index auswirken, von der Updateindex-API nicht zulässig sind.

Hinweis

Es ist nicht möglich, Indizes zu verwalten, die mit dem alten "flachen" Format aus dem Azure Portal erstellt wurden. Aktualisieren Sie Ihre Indizes von der "flachen" Darstellung auf die "Baumdarstellung" bei erster Gelegenheit.

Aktualisierungen der Steuerungsebene

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 neu formulieren von GET zu 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. Wenn Sie ein Azure SDK verwenden, empfiehlt es sich, ein Upgrade auf die neueste Version durchzuführen.

Nächste Schritte

Überprüfen Sie die Such-REST-API-Referenzdokumentation. Wenn Probleme auftreten, bitten Sie uns um Hilfe bei Stack Overflow , oder wenden Sie sich an den Support.

Rest-API-Referenz für den Suchdienst