Migrieren von Azure Maps Search 1.0-APIs

Suche Die API-Version 2026-01-01 ersetzt die Such-API , Version 1.0. Die neuere Version führt aufgabenspezifische Endpunkte, klarere Absichten und verbesserte Skalierbarkeit ein. In diesem Artikel wird erläutert, wie Sie vorhandene Such-v1-Integrationen migrieren.

Von Bedeutung

Die Azure Maps Search-API, Version 1.0 , wurde von der Such-API, Version 2026-01-01, abgelöst. Während Search v1 weiterhin funktioniert, sollte die neue Entwicklung die neueste Such-API für den Zugriff auf aufgabenspezifische Endpunkte, verbesserte Leistung und langfristige Unterstützung verwenden. Um zukünftige Dienstunterbrechungen zu vermeiden, migrieren Sie vorhandene Such-v1-Integrationen zu Search 2026-01-01.

API-Äquivalenzzuordnung

Purpose Search v1 API Such-API für 2026-01-01
Vorwärts-Geokodierung Suchadresse abrufen Geocodierung abrufen
Adresse Fuzzy-Suche ausführen (abgeschlossen) Geocodierung abrufen
AutoVervollständigen Fuzzy-Suche abrufen (Eingabevorhersage) Geocode-Autovervollständigung abrufen
Batch-Geocodierung Suchadressen-Stapel abrufen Geocodierungsstapel abrufen
Umgekehrte Geocodierung Get Search Address Reverse Umgekehrte Geocodierung abrufen
Batch Reverse Get Search Address Reverse Batch Umgekehrter Geocodierungsbatch abrufen
Boundaries Such-Polygon abrufen Polygon abrufen

Wichtige Unterschiede

Die Search 2026-01-01-01-APIs stellen absichtsspezifische Endpunkte, eine klarere Anforderungssemantik und ein strengeres Ergebnisverhalten im Vergleich zu Search v1 vor. In der folgenden Tabelle sind die wichtigsten Unterschiede zusammengefasst, die bei der Migration beachtet werden müssen.

Fläche Suchen v1 Suche 2026-01-01
API-Design Mehrzweck-Endpunkte (z. B. Such-Fuzzys, die sowohl für die Autovervollständigung als auch für die endgültige Suche verwendet werden) Intent-spezifische APIs (z. B. Get Geocoding, Get Geocode AutoComplete, Get Reverse Geocoding)
AutoVervollständigen-Verhalten Implementiert mithilfe von Suchfuzzy mit typeahead=true Dedizierte Geocode-Autovervollständigungs-API
Endgültige Geocodierung Oft wird auf Fuzzy-Abgleich zurückgegriffen, um eine "beste Vermutung" abzugeben. Get Geocoding priorisiert die Korrektheit und gibt möglicherweise keine Ergebnisse zurück.
Leere Ergebnisse Oftmals wurde eine Übereinstimmung mit niedriger Konfidenz zurückgegeben Kann HTTP 200 mit einem leeren Ergebnisarray zurückgeben, wenn keine Übereinstimmung gefunden wird
Vertrauensverwaltung von Ergebnissen Konfidenz und Qualität der Übereinstimmung waren oft implizit Konfidenz, Übereinstimmungscodes und Entitätstyp sind explizit und sollten ausgewertet werden.
Behandlung von Entitätshierarchien Fuzzy-Ergebnisse könnten lose verwandte Entitäten zurückgeben Ergebnisse können zu einer höhergeordneten Entität (z. B. Kreis oder Region) zusammengefasst und nach Entitätstyp gefiltert werden.
Batchnutzung Batch-APIs verfügbar, aber häufig optional Batch-APIs werden für Workflows mit großer Skalierung und Anreicherung empfohlen.
Datenanreicherungsworkflows Häufig mit Fuzzysuche erneut versucht Unterstützt explizit Anreicherungsmuster mit klarerem Nicht-Übereinstimmungssignal
URL-Struktur Versioniert unter Endpunkten /search/* Vereinfachte, aufgabenspezifische Endpunkte (z. B /geocode. , /reverseGeocode)
Zukünftige Erweiterbarkeit Eingeschränkte Fähigkeit, individuelle Verhaltensweisen zu entwickeln APIs werden unabhängig nach Absicht weiterentwickelt (AutoVervollständigen, Geocodierung, Reverse)

Nutzungsunterschiede bei Transaktionen

Search 2026-01-01 verwendet intentbasierte APIs, die die Art und Weise, wie Transaktionen im Vergleich zu Search v1 genutzt werden, ändern können.

In Search v1 wurde häufig ein einzelner multifunktionsfähiger Endpunkt sowohl für autovervollständigen als auch für die endgültige Geocodierung verwendet. In Search 2026-01-01 werden diese Szenarien in unterschiedliche APIs unterteilt, wodurch die Transaktionsnutzung besser mit Benutzerabsicht ausgerichtet werden kann.

Wichtige Überlegungen bei der Migration:

  • Verwenden Sie Get Geocode Autocomplete nur für vorausschauende Benutzerinteraktionen.
  • Verwenden Sie „Geocodierung abrufen“ nur, wenn eine endgültige Adresse oder ein endgültiger Ort erforderlich ist.
  • Vermeiden Sie das Aufrufen endgültiger Geocodierungs-APIs während interaktiver Eingabeszenarien.
  • Bevorzugen Sie Batch-APIs für Workflows mit großer oder Hintergrund-Geocodierung.

Ausführliche Informationen dazu, wie Azure Maps-Transaktionen berechnet und in Rechnung gestellt werden, finden Sie unter Grundlegendes zu Azure Maps-Transaktionen.

Änderungen bei der Ergebnisbehandlung

Suche 2026-01-01 legt mehr Wert auf die Ergebniskorrektur und explizite Übereinstimmungssignalisierung als Suche v1.

Überprüfen Sie bei der Migration, wie Ihre Anwendung Suchantworten interpretiert:

  • Eine erfolgreiche Anforderung gibt möglicherweise keine Ergebnisse zurück, wenn keine geeignete Übereinstimmung gefunden wird. Weitere Informationen finden Sie unter Grundlegendes zu leeren Geocodierungsergebnissen.
  • Die Wahrscheinlichkeit, dass Treffer mit geringer Wahrscheinlichkeit oder mit geringem Zusammenhang automatisch zurückgegeben werden, ist geringer.
  • Anwendungen sollten Konfidenzwerte, Übereinstimmungscodes und Entitätstypen auswerten, wenn ermittelt wird, ob ein Ergebnis akzeptabel ist. Weitere Informationen finden Sie unter Verbessern der Ergebnisqualität für die abfragebasierte Geocodierung.
  • Wenn eine angeforderte Entität nicht gefunden wird, gibt der Dienst möglicherweise eine Entität auf höherer Ebene in der Adresshierarchie zurück (z. B. eine Region anstelle einer Stadt). Weitere Informationen zum Auswerten der Ergebnisqualität und zum Überprüfen, dass zurückgegebene Entitätstypen mit dem beabsichtigten Suchszenario übereinstimmen, finden Sie unter Bewährte Methoden für die Weiterleitung der Geocodierung in bewährten Methoden für den Azure Maps Search-Dienst.

Gehen Sie nicht davon aus, dass jede erfolgreiche Anforderung ein verwendbares Ergebnis zurückgibt. Eine explizite Ergebnisauswertung ist erforderlich, um die Datenqualität aufrechtzuerhalten.

Vergleich von Anforderungs- und Antwortbeispielen

Die folgenden Beispiele zeigen, wie allgemeine Azure Maps Search v1-Anforderungen ihren Entsprechungen in der Such-API 2026-01-01 zugeordnet werden. Jedes Beispiel konzentriert sich auf die gleiche Benutzerabsicht, wobei die Umstellung von Multi-Purpose v1-Endpunkten zu intentsspezifischen APIs hervorgehoben wird.

Weiterleiten der Geocodierung (Adresse → Koordinaten)

In der Such-API v1 wurde die Weiterleitungs-Geocodierung häufig mithilfe der Endpunkte "Suchadresse" oder "Suchfuzzy" durchgeführt. In der Such-API 2026-01-01-01 wird diese Funktion von der Get Geocoding-API bereitgestellt, die strukturierte oder unstrukturierte Adresseingaben mithilfe eines dedizierten, absichtsspezifischen Endpunkts in geografische Koordinaten aufgelöst.

Suche v1 – Suchadresse

GET https://atlas.microsoft.com/search/address/json
  ?api-version=1.0
  &query=1%20Microsoft%20Way%2C%20Redmond%20WA

Suche 2026-01-01 – Geocodierung abrufen

GET https://atlas.microsoft.com/geocode
  ?api-version=2026-01-01
  &query=1%20Microsoft%20Way%2C%20Redmond%20WA

Fuzzy-Suche nach Adressen oder Orten (Endergebnis)

Search API v1 stellte die unscharfe Adress- und Ortsauflösung über einen einzigen Search Fuzzy Endpunkt zur Verfügung. In der Such-API 2026-01-01-01 wird dieses Verhalten durch Get Geocoding ersetzt, das Freiformularadressen verarbeitet und Abfragen platziert, während AutoVervollständigen- und Vorschlagsszenarien in unterschiedliche APIs getrennt werden.

Suche v1 – Unscharfe Suche

GET https://atlas.microsoft.com/search/fuzzy/json
  ?api-version=1.0
  &query=Space%20Needle

Suche 2026-01-01 – Geocodierung abrufen

GET https://atlas.microsoft.com/geocode
  ?api-version=2026-01-01
  &query=Space%20Needle

Autocomplete / Vorausgefüllte Vorschläge

In Search API v1 wurde das Type-Ahead-Verhalten durch Festlegen von typeahead=true am [Search Fuzzy]-Endpunkt aktiviert. In der Such-API 2026-01-01 werden AutoVervollständigen-Szenarien explizit von der Get Geocode AutoComplete-API behandelt, die für interaktive Benutzereingaben und Echtzeitvorschläge optimiert ist.

Search v1 - Search Fuzzy (Verwendung von Type-Ahead)

GET https://atlas.microsoft.com/search/fuzzy/json
  ?api-version=1.0
  &query=1%20Mic
  &typeahead=true

Search 2026-01-01 - Get Geocode Autocomplete

GET https://atlas.microsoft.com/geocode:autocomplete
  ?api-version=2026-01-01
  &query=1%20Mic
  &coordinates=-122.129,47.639

Weitere Informationen finden Sie unter Einführung in die Azure Maps Geocode AutoVervollständigen-API.

Batch forward geocoding

Search API v1 unterstützt die Batch-Adressauflösung über den Search Address Batch Endpunkt. In der Such-API 2026-01-01-01 wird diese Funktionalität von Get Geocoding Batch bereitgestellt, sodass mehrere Adressabfragen in einer einzigen Anforderung für umfangreiche oder Hintergrundworkloads übermittelt und verarbeitet werden können.

Suche v1 – Suchadressen-Sammlung

POST https://atlas.microsoft.com/search/address/batch/json
  ?api-version=1.0

Search 2026-01-01 - Get Geocoding Batch

POST https://atlas.microsoft.com/geocode:batch
  ?api-version=2026-01-01

Umgekehrte Geocodierung (Koordinaten → Adresse)

Umgekehrte Geokodierung in der Such-API v1 wurde über den Endpunkt "Suche Adresse Rückwärts" ausgeführt. In der Such-API 2026-01-01-01 ist diese Funktion über Get Reverse Geocoding verfügbar, die Längengrad- und Breitengradkoordinaten mithilfe einer dedizierten Reverse-Lookup-API in eine lesbare Adresse konvertiert.

Suche v1 – Rückwärtssuche der Adresse

GET https://atlas.microsoft.com/search/address/reverse/json
  ?api-version=1.0
  &position=47.639,-122.129

Suche 2026-01-01 – Abfrage von Reverse-Geocoding-Daten

GET https://atlas.microsoft.com/reverseGeocode
  ?api-version=2026-01-01
  &coordinates=-122.129,47.639

Umgekehrte Batch-Geocodierung

Such-API v1 aktivierte Batch-Reverse-Lookups mithilfe von Get Search Address Reverse Batch. In der Such-API 2026‑01‑01 wird dieses Szenario von Get-Reverse-Geocoding-Batch unterstützt, sodass mehrere Koordinatenpaare in einer einzigen Anforderung für Telemetrie, Nachverfolgung oder Anreicherungspipelines in Adressen aufgelöst werden können.

Search v1 - Search Address Reverse Batch

POST https://atlas.microsoft.com/search/address/reverse/batch/json
  ?api-version=1.0

Search 2026-01-01 - Get Reverse Geocoding Batch

POST https://atlas.microsoft.com/reverseGeocode:batch
  ?api-version=2026-01-01

Abruf administrativer Abgrenzungen

In der Such-API v1 wurde die administrative Begrenzungsgeometrie mithilfe von Get Search Polygon abgerufen. In der Such-API 2026-01-01-01 wird diese Funktionalität von der Get Polygon-API bereitgestellt, die grenzgeometrie für unterstützte administrative Entitäten wie Länder/Regionen und Städte zurückgibt.

Search v1 – Get Search Polygon

GET https://atlas.microsoft.com/search/polygon/json
  ?api-version=1.0
  &entityId=US-WA

Suche 2026-01-01 – Polygon abrufen

GET https://atlas.microsoft.com/polygon
  ?api-version=2026-01-01
  &entityId=US-WA

Migrationscheckliste

  • Inventarisieren aller verwendeten Search v1-Endpunkte
  • Identifizieren der Absicht (Autocomplete vs. finaler Geocode)
  • Ersetzen von v1-Endpunkten durch 2026-01-01-Entsprechungen
  • Aktualisieren von Abfrageparametern
  • Überprüfung des Antwort-Parsings
  • Einführen von Batch-APIs, sofern zutreffend
  • Aktualisieren von Dokumentationen und Beispielen

Nächste Schritte

Bewährte Methoden für den Suchdienst von Azure Maps

  • Zuletzt aktualisiert um