Migrowanie interfejsów API usługi Azure Maps Search 1.0

Search API w wersji 2026-01-01 zastępuje Search API w wersji 1.0. Nowsza wersja wprowadza punkty końcowe specyficzne dla zadań, jaśniejszą intencję i lepszą skalowalność. W tym artykule wyjaśniono, jak migrować istniejące integracje usługi Search w wersji 1.

Mapowanie równoważności interfejsu API

Istotne różnice

Interfejsy API Wyszukiwania z dnia 2026-01-01 wprowadzają punkty końcowe specyficzne dla zamierzeń, jaśniejszą semantykę żądań i bardziej restrykcyjne zachowanie wyników w porównaniu z Wyszukiwaniem w wersji 1. W poniższej tabeli podsumowano najważniejsze różnice, które należy wziąć pod uwagę podczas migracji.

Różnice użycia transakcji

Usługa Search 2026-01-01 używa API specyficznych dla intencji, co może zmienić sposób, w jaki transakcje są wykorzystywane w porównaniu z Search w wersji 1.

W wersji 1 usługi Search, pojedynczy wielofunkcyjny punkt końcowy był często używany zarówno do autouzupełniania, jak i końcowego geokodowania. W usłudze Search 2026-01-01 te scenariusze są oddzielone do odrębnych interfejsów API, co ułatwia bardziej precyzyjne dopasowanie użycia transakcji do intencji użytkownika.

Kluczowe zagadnienia dotyczące migracji:

• Używaj Autouzupełnianie geokodowania tylko do interakcji użytkownika podczas wpisywania.
• Użyj funkcji Pobierz geokodowanie tylko wtedy, gdy wymagany jest końcowy adres lub miejsce.
• Unikaj wielokrotnego wywoływania końcowych interfejsów API geokodowania podczas interaktywnych scenariuszy wpisywania.
• Preferuj wsadowe interfejsy API do pracy z przepływami geokodowania na dużą skalę lub w tle.

Aby uzyskać szczegółowe informacje na temat sposobu obliczania i rozliczania transakcji usługi Azure Maps, zobacz Omówienie transakcji usługi Azure Maps.

Zmiany w obsłudze wyników

Wyszukiwanie 2026-01-01 kładzie większy nacisk na poprawność wyników i jawne sygnalizowanie dopasowania niż Wyszukiwanie w wersji 1.

Podczas migracji sprawdź, jak aplikacja interpretuje odpowiedzi wyszukiwania:

• Pomyślne żądanie może nie zwracać żadnych wyników , gdy nie zostanie znalezione odpowiednie dopasowanie. Aby uzyskać więcej informacji, zobacz Omówienie pustych wyników geokodowania.
• Niska pewność lub luźno powiązane dopasowania są mniej prawdopodobne, że zostaną automatycznie zwrócone.
• Aplikacje powinny oceniać wartości ufności, kody dopasowania i typy jednostek podczas określania, czy wynik jest akceptowalny. Aby uzyskać więcej informacji, zobacz Poprawianie jakości wyników na potrzeby geokodowania opartego na zapytaniach.
• Jeśli żądana jednostka nie zostanie znaleziona, usługa może zwrócić jednostkę wyższego poziomu w hierarchii adresów (na przykład region zamiast miasta). Aby uzyskać więcej informacji na temat oceniania jakości wyników i sprawdzania poprawności zwracanych typów jednostek zgodnie z zamierzonym scenariuszem wyszukiwania, zobacz Najlepsze rozwiązania dotyczące przekazywania geokodowania w artykule Najlepsze rozwiązania dotyczące usługi Azure Maps Search.

Nie zakładaj, że każde pomyślne żądanie zwraca wynik użyteczny. Jawna ocena wyników jest wymagana do zachowania jakości danych.

Przykładowe porównanie żądań i odpowiedzi

W poniższych przykładach pokazano, jak typowe żądania usługi Azure Maps Search w wersji v1 odpowiadają ich odpowiednikom w API wyszukiwania 2026-01-01. Każdy przykład koncentruje się na tym samym zamiarze użytkownika, podkreślając przejście z wielofunkcyjnych punktów końcowych w wersji 1 do API specyficznych dla zamiaru.

Geokodowanie przód (adres → współrzędne)

W interfejsie API wyszukiwania w wersji 1 często wykonywane było geokodowanie progresywne przy użyciu końcówek wyszukiwania adresów lub rozmytego wyszukiwania. W Search API 2026-01-01 ta funkcja jest udostępniana przez interfejs API Get Geocoding, który przekształca dane wejściowe adresów ustrukturyzowanych lub nieustrukturyzowanych na współrzędne geograficzne, używając dedykowanego punktu końcowego dla określonego celu.

Wyszukiwanie w wersji 1 — adres wyszukiwania

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

Wyszukaj 2026-01-01 — Uzyskaj geokodowanie

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

Niedokładne wyszukiwanie adresów lub miejsc (wynik końcowy)

Interfejs API wyszukiwania w wersji 1 udostępnił funkcjonalność rozwiązywania rozmytego adresu i miejsca za pośrednictwem pojedynczego rozmytego punktu końcowego wyszukiwania. W interfejsie API wyszukiwania 2026-01-01 to zachowanie zostaje zastąpione przez funkcję Get Geocoding, która obsługuje zapytania dotyczące dowolnych i niestrukturalnych adresów oraz miejsc, jednocześnie rozdzielając scenariusze autouzupełniania i sugestii na oddzielne interfejsy API.

Wyszukiwanie w wersji 1 — wyszukiwanie rozmyte

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

Wyszukaj 2026-01-01 — Uzyskaj geokodowanie

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

Sugestie autouzupełniania/wpisywania z wyprzedzeniem

W interfejsie API wyszukiwania w wersji 1 włączono zachowanie z wyprzedzeniem przez ustawienie typeahead=true w punkcie końcowym [Wyszukiwanie rozmyte]. W interfejsie API wyszukiwania 2026-01-01 scenariusze autouzupełniania są obsługiwane jawnie przez interfejs API Pobierania autouzupełniania kodu geograficznego , który jest zoptymalizowany pod kątem interaktywnych sugestii dotyczących danych wejściowych użytkownika i sugestii w czasie rzeczywistym.

Wyszukiwanie w wersji 1 — wyszukiwanie rozmyte (użycie typu z wyprzedzeniem)

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

Wyszukiwanie 2026-01-01 — Uzyskiwanie autouzupełniania kodu geograficznego

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

Aby uzyskać więcej informacji, zobacz Wprowadzenie do interfejsu API automatycznego uzupełniania kodu geograficznego usługi Azure Maps.

Geokodowanie wsadowe do przodu

Interfejs API wyszukiwania w wersji 1 obsługiwał rozwiązywanie adresów wsadowych za pośrednictwem punktu końcowego dla wsadowego wyszukiwania adresów. W interfejsie API wyszukiwania 2026-01-01 ta funkcja jest udostępniana przez usługę Get Geocoding Batch, umożliwiając wysyłanie i przetwarzanie wielu zapytań adresowych w jednym żądaniu dla obciążeń na dużą skalę lub w tle.

Wyszukiwanie w wersji 1 — wsadowe wyszukiwanie adresów

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

Wyszukiwanie 2026-01-01 — Pobieranie Geocoding Batch

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

Odwrotne geokodowanie (współrzędne → adres)

Odwrotne geokodowanie w interfejsie API wyszukiwania w wersji 1 zostało wykonane przy użyciu punktu końcowego odwrotnego adresu wyszukiwania. W Search API 2026-01-01 ta możliwość jest dostępna za pośrednictwem funkcji Get Reverse Geocoding, która konwertuje współrzędne długości i szerokości geograficznej na adres czytelny dla człowieka przy użyciu API dedykowanego do wyszukiwania wstecznego.

Wyszukiwanie wersja 1 – Odwrotne wyszukiwanie adresu

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

Szukaj 2026‑01‑01 – Uzyskaj odwrotne geokodowanie

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

Odwrotne geokodowanie wsadowe

Interfejs API wyszukiwania w wersji 1 włącza wyszukiwania wsadowego wstecznego za pomocą funkcji Uzyskaj adres wyszukiwania w partii odwrotnej. W interfejsie API wyszukiwania 2026-01-01 ten scenariusz jest obsługiwany przez usługę Get Reverse Geocoding Batch, umożliwiając rozpoznawanie wielu par współrzędnych na adresy w jednym żądaniu dla potoków telemetrii, śledzenia lub wzbogacania.

Wyszukiwanie w wersji 1 — odwrotna partia adresu wyszukiwania

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

Wyszukaj 2026-01-01 — Pobierz odwrotne geokodowanie wsadowe

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

Pobieranie granic administracyjnych

W interfejsie API wyszukiwania w wersji 1 pobrano geometrię granic administracyjnych przy użyciu funkcji Pobierz wielokąt wyszukiwania. W interfejsie API wyszukiwania 2026-01-01 ta funkcja jest udostępniana przez interfejs API Get Polygon , który zwraca geometrię granic dla obsługiwanych jednostek administracyjnych, takich jak kraje/regiony i miasta.

Wyszukiwanie w wersji 1 — uzyskiwanie wielokąta wyszukiwania

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

Wyszukaj 2026-01-01 — Pobierz Polygon

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

Lista kontrolna migracji

Następne kroki