Migrera API:er för Azure Maps Search 1.0

Sök API-version 2026-01-01 ersätter Search API version 1.0. Den nyare versionen introducerar uppgiftsspecifika slutpunkter, tydligare avsikt och förbättrad skalbarhet. Den här artikeln beskriver hur du migrerar befintliga Search v1-integreringar.

Viktigt!

Azure Maps Search API version 1.0 har ersatts av Search API version 2026-01-01. Medan Search v1 fortsätter att fungera bör den nya utvecklingen använda det senaste sök-API:et för att få åtkomst till uppgiftsspecifika slutpunkter, bättre prestanda och långsiktigt stöd. För att undvika framtida tjänststörningar migrerar du befintliga Search v1-integreringar till Search 2026-01-01.

Mappning av API-ekvivalens

Avsikt Sök i v1-API Sök 2026-01-01 API
Framåtgeokodning Hämta sökadress Hämta geokoddata
Adress Aktivera fuzzy-sökning (slutgiltig) Hämta geokoddata
Komplettera automatiskt Aktivera Suddig sökning (type‑ahead) Hämta Geocode Autocomplete
Partiell geokodning Hämta batch för adressökning Hämta geokodningsbatch
Omvänd geokodning Hämta omvänd sökadress Hämta omvänd geokodning
Batchomvändning Hämta batch för omvänd sökning av adress Hämta batch för omvänd geokodning
Boundaries Hämta sökpolygon Hämta Polygon

Anmärkningsvärda skillnader

API:erna Search 2026-01-01 introducerar avsiktsspecifika slutpunkter, tydligare begärandesemantik och striktare resultatbeteende jämfört med Sök v1. I följande tabell sammanfattas de viktigaste skillnaderna när du migrerar.

Område Sök v1 Sök 2026-01-01
API-design Slutpunkter för flera syften (till exempel Sök fuzzy som används för både automatisk komplettering och slutlig sökning) Avsiktsspecifika API:er (till exempel Get Geocoding, Get Geocode Autocomplete, Get Reverse Geocoding)
Beteende för automatisk komplettering Implementerad med hjälp av Search Fuzzy med typeahead=true Dedikerad API för Get Geocode Autocomplete
Slutlig geokodning Förlitade sig ofta på fuzzy matchning för att returnera en "bästa gissning" Få geokodning prioriterar korrekthet och kan inte returnera några resultat
Tomma resultat Returnerade ofta en matchning med låg tillförlitlighet Kan returnera HTTP 200 med en tom resultatmatris när ingen matchning hittas
Hantering av resultatförtroende Konfidens och matchningskvalitet var ofta implicita Konfidens, matchningskoder och entitetstyp är explicita och bör utvärderas
Hantering av entitetshierarki Fuzzy-resultat kan returnera löst relaterade entiteter Resultaten kan summeras till en entitet på högre nivå (till exempel län eller region) och bör filtreras efter entitetstyp
Batchanvändning Batch-API:er tillgängliga men ofta valfria Batch-API:er rekommenderas för storskaliga och berikande arbetsflöden.
Arbetsflöden för databerikning Ofta omprövad med fuzzy-sökning Har uttryckligen stöd för berikningsmönster med tydligare no-match-signalering
URL-struktur Versionerad under /search/* ändpunkter Förenklade, uppgiftsspecifika slutpunkter (till exempel /geocode, /reverseGeocode)
Framtida utökningsbarhet Begränsad möjlighet att utveckla individuella beteenden API:er utvecklas oberoende baserat på avsikt (automatisk komplettering, geokodning, omvänd)

Skillnader i transaktionsanvändning

Search 2026-01-01 använder avsiktsspecifika API:er, vilket kan ändra hur transaktioner används jämfört med Sök v1.

I Sök v1 användes ofta en enda slutpunkt för flera syften för både automatisk komplettering och slutlig geokodning. I Search 2026-01-01 delas dessa scenarier upp i distinkta API:er, vilket hjälper till att justera transaktionsanvändningen närmare med användarens avsikt.

Viktiga överväganden vid migrering:

  • Använd Get Geocode Autocomplete endast för 'type-ahead'-användarinteraktioner.
  • Använd endast Hämta geokodning när en slutlig adress eller plats krävs.
  • Undvik att anropa slutgiltiga geokodnings-API:er upprepade gånger under interaktiva skrivscenarier.
  • Föredrar batch-API:er för storskaliga arbetsflöden eller bakgrunds-geokodningsarbetsflöden.

Mer information om hur Azure Maps-transaktioner beräknas och faktureras finns i Förstå Azure Maps-transaktioner.

Ändringar i resultathantering

Search 2026-01-01 lägger större vikt vid resultatkorrigering och explicit matchningssignalering än Search v1.

När du migrerar granskar du hur programmet tolkar söksvar:

  • En lyckad begäran kan inte returnera några resultat när ingen lämplig matchning hittas. Mer information finns i Förstå tomma geokodningsresultat.
  • Låg konfidens eller löst relaterade matchningar är mindre benägna att returneras automatiskt.
  • Program bör utvärdera konfidensvärden, matchningskoder och entitetstyper när de avgör om ett resultat är acceptabelt. Mer information finns i Förbättra resultatkvaliteten för frågebaserad geokodning.
  • Om en begärd entitet inte hittas kan tjänsten returnera en entitet på högre nivå i adresshierarkin (till exempel en region i stället för en stad). Mer information om hur du utvärderar resultatkvaliteten och validerar att returnerade entitetstyper matchar det avsedda sökscenariot finns i Metodtips för vidarebefordran av geokodning i Metodtips för Azure Maps Search-tjänsten.

Anta inte att varje lyckad begäran returnerar ett användbart resultat. Explicit resultatutvärdering krävs för att upprätthålla datakvaliteten.

Jämförelse av exempel på begäran och svar

Följande exempel visar hur vanliga Azure Maps Search v1-begäranden mappas till deras motsvarigheter i Search API 2026-01-01. Varje exempel fokuserar på samma användarsyfte och markerar övergången från slutpunkter för flera syften v1 till avsiktsspecifika API:er.

Framåtgeokodning (adress → koordinater)

I Sök-API v1 utfördes vanligtvis geokodning framåt med hjälp av slutpunkterna Sökadress eller Fuzzy-sökning. I Search API 2026-01-01 tillhandahålls den här funktionen av API:et Hämta geokodning , som löser strukturerade eller ostrukturerade adressindata till geografiska koordinater med hjälp av en dedikerad, avsiktsspecifik slutpunkt.

Sök v1 – Sökadress

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

Sök 2026-01-01 – Hämta geokodning

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

Fuzzy-adress eller platssökning (slutresultatet)

Sök-API v1 exponerar fuzzy-adress- och platshantering via en enda fuzzy slutpunkt för sökning. I Sök-API 2026-01-01 ersätts det här beteendet av Get Geocoding, som hanterar kostnadsfria adress- och platsfrågor samtidigt som scenarier för automatisk komplettering och förslag separeras i distinkta API:er.

Sök v1 – Fuzzy-sökning

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

Sök 2026-01-01 – Hämta geokodning

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

Automatisk komplettering / förslag vid inmatning

I Sök-API v1 aktiverades beteendet med sökning i förväg genom att ställa in typeahead=true på slutpunkten [Sök Fuzzy]. I Search API 2026-01-01 hanteras scenarier för automatisk komplettering explicit av API:et Get Geocode Autocomplete , som är optimerat för interaktiva användarindata och realtidsförslag.

Sök v1 – Sök fuzzy (ungefärlig typantydning)

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

Sök 2026-01-01 – Få Geokodautokomplettering

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

Mer information finns i Introduktion till API:et för automatisk komplettering av Azure Maps Geocode.

Batchvidarebefordring av geokodning

Search API v1 stödde gruppadresslösning genom slutpunkten för gruppadressökning. I Search API 2026-01-01 tillhandahålls den här funktionen av Get Geocoding Batch, vilket gör att flera adressfrågor kan skickas och bearbetas i en enda begäran för storskaliga eller bakgrundsarbetsbelastningar.

Sök v1 – Sökadresssats

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

Sök 2026-01-01 – Hämta geokodningsbatch

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

Omvänd geokodning (koordinater → adress)

Omvänd geokodning i Sök-API v1 utfördes med hjälp av den omvända slutpunkten för sökadress. I Search API 2026-01-01 är den här funktionen tillgänglig via Hämta omvänd geokodning, som konverterar longitud- och latitudkoordinater till en läsbar adress för människor med hjälp av ett dedikerat API för omvänd sökning.

Sök v1 – Omvänd sökadress

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

Sök 2026-01-01 – Hämta omvänd geokodning

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

Omvänd geokodning för batch

Sök-API v1 möjliggjorde batchomvändsökningar via Hämta sökadress omvänd batch. I Search API 2026-01-01 stöds det här scenariot av Get Reverse Geocoding Batch, vilket möjliggör att flera koordinatpar kan lösas till adresser i en enda begäran för telemetri, spårning eller berikningspipelines.

Sök v1 – Omvänd batch för sökadress

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

Sök 2026-01-01 – Hämta omvänd geokodningsbatch

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

Hämtning av administrativa gränser

I Sök-API v1 hämtades den administrativa gränsgeometrin med hjälp av Get Search Polygon. I Search API 2026-01-01 tillhandahålls den här funktionen av Api:et Get Polygon , som returnerar gränsgeometri för administrativa entiteter som stöds, till exempel länder/regioner och städer.

Sök v1 – Hämta sökpolygon

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

Sök 2026-01-01 – Hämta Polygon

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

Checklista för migrering

  • Inventera alla search v1-slutpunkter som används
  • Identifiera avsikt (komplettera automatiskt eller slutlig geokod)
  • Ersätt v1-slutpunkter med motsvarande 2026-01-01
  • Uppdatera frågeparametrar
  • Verifiera resultatbearbetning
  • Introducera batch-API:er där det är tillämpligt
  • Uppdatera dokumentation och exempel

Nästa steg

Bästa metoder för Azure Maps Search-tjänst

  • Uppdaterades senast