Eseguire la migrazione delle API di Ricerca di Mappe di Azure 1.0

Ricerca L'API versione 2026-01-01 sostituisce l'API di ricerca versione 1.0. La versione più recente introduce endpoint specifici dell'attività, finalità più chiare e scalabilità migliorata. Questo articolo illustra come eseguire la migrazione delle integrazioni di Ricerca v1 esistenti.

Importante

L'API di ricerca di Mappe di Azure versione 1.0 è stata sostituita dall'API di ricerca versione 2026-01-01. Mentre la versione 1 della ricerca continua a funzionare, il nuovo sviluppo dovrebbe usare l'API di ricerca più recente per accedere a endpoint specifici dell'attività, prestazioni migliorate e supporto a lungo termine. Per evitare future interruzioni del servizio, eseguire la migrazione delle integrazioni di Ricerca v1 esistenti a Search 2026-01-01.

Mappatura delle equivalenze API

Scopo	API di ricerca v1	Ricerca 2026-01-01 API
Geocodifica diretta	Ottenere l'indirizzo di ricerca	Get Geocoding
Address	Get Search Fuzzy (finale)	Get Geocoding
Completamento automatico	Get Search Fuzzy (type‑ahead)	Ottenere il completamento automatico del codice geografico
Geocodifica batch	Get Search Address Batch	Get Geocoding Batch
Geocodifica inversa	Get Search Address Reverse	Get Reverse Geocoding
Batch reverse	Get Search Address Reverse Batch	Ottieni Batch di Geocodifica Inversa
Boundaries	Ottieni poligono di ricerca	Ottieni poligono

Differenze rilevanti

Le API Search 2026-01-01 introducono endpoint specifici della finalità, semantica delle richieste più chiare e comportamento dei risultati più restrittivo rispetto alla versione 1 della ricerca. La tabella seguente riepiloga le differenze più importanti da tenere presenti durante la migrazione.

Area	Ricerca v1	Ricerca 2026‑01‑01
Progettazione di API	Endpoint multiuso, ad esempio Ricerca fuzzy usato sia per il completamento automatico sia per la ricerca finale	API specifiche della finalità (ad esempio, Get Geocoding, Get Geocode Autocomplete, Get Reverse Geocoding)
Comportamento di completamento automatico	Implementato con Search Fuzzy con typeahead=true	API di completamento automatico Get Geocode dedicata
Geocodifica finale	Spesso si basava sulla corrispondenza fuzzy per restituire una "migliore ipotesi"	La geocodifica dà priorità alla correttezza e potrebbe non restituire risultati.
Risultati vuoti	Spesso restituiva una corrispondenza a bassa attendibilità	Può restituire HTTP 200 con una matrice di risultati vuota quando non viene trovata alcuna corrispondenza
Gestione dell'attendibilità dei risultati	Il livello di affidabilità e la qualità delle corrispondenze erano spesso implicite	La confidenza, i codici di corrispondenza e il tipo di entità sono espliciti e devono essere valutati
Gestione della gerarchia di entità	I risultati fuzzy potrebbero restituire entità correlate in modo libero	I risultati possono essere riforniti a un'entità di livello superiore (ad esempio, contea o area) e devono essere filtrati in base al tipo di entità
Utilizzo batch	API Batch disponibili ma spesso facoltative	Le API Batch sono consigliate per flussi di lavoro su larga scala e arricchimento
Flussi di lavoro di arricchimento dei dati	Veniva di solito ripetuto con la ricerca fuzzy	Supporta in modo esplicito i modelli di arricchimento con segnali più chiari in caso di assenza di corrispondenze
Struttura URL	Versionato sotto gli endpoint /search/*	Endpoint semplificati e specifici dell'attività (ad esempio, /geocode, /reverseGeocode)
Estendibilità futura	Capacità limitata di evolvere i singoli comportamenti	Le API si evolvono in modo indipendente in base alla finalità (completamento automatico, geocodifica, inversione)

Differenze di utilizzo delle transazioni

La ricerca 2026-01-01 usa API specifiche dell'intento, che possono modificare il modo in cui le transazioni vengono utilizzate rispetto alla ricerca v1.

In Search v1 un singolo endpoint multiuso è stato spesso usato sia per il completamento automatico che per la geocodifica finale. In Search 2026-01-01 questi scenari sono separati in API distinte, che consente di allineare l'utilizzo delle transazioni più strettamente con la finalità dell'utente.

Considerazioni chiave per la migrazione:

• Usa Get Geocode Autocomplete solo per le interazioni utente di tipo anticipato.
• Usare Get Geocoding solo quando è necessario un indirizzo o una posizione finale.
• Evitare di chiamare ripetutamente api di geocodifica finale durante scenari di digitazione interattiva.
• Preferisce le API batch per flussi di lavoro di geocodifica su larga scala o in background.

Per informazioni dettagliate sul modo in cui vengono calcolate e fatturate le transazioni di Mappe di Azure, vedere Informazioni sulle transazioni di Mappe di Azure.

Modifiche alla gestione dei risultati

La ricerca 2026-01-01 pone maggiore enfasi sulla correttezza dei risultati e sulla segnalazione esplicita della corrispondenza rispetto alla ricerca v1.

Durante la migrazione, esaminare il modo in cui l'applicazione interpreta le risposte di ricerca:

• Una richiesta con esito positivo potrebbe non restituire risultati quando non viene trovata alcuna corrispondenza appropriata. Per ulteriori informazioni, vedere Informazioni sui risultati di geocodifica vuoti.
• È meno probabile che siano fornite automaticamente corrispondenze con scarsa affidabilità o poco correlate.
• Le applicazioni devono valutare i valori di attendibilità, i codici di corrispondenza e i tipi di entità quando si determina se un risultato è accettabile. Per altre informazioni, vedere Migliorare la qualità dei risultati per la geocodifica basata su query.
• Se non viene trovata un'entità richiesta, il servizio può restituire un'entità di livello superiore nella gerarchia degli indirizzi, ad esempio un'area anziché una città. Per altre informazioni sulla valutazione della qualità dei risultati e sulla convalida dei tipi di entità restituiti che corrispondono allo scenario di ricerca previsto, vedere Procedure consigliate per la geocodifica diretta in Procedure consigliate per il servizio di ricerca di Mappe di Azure.

Non presupporre che ogni richiesta con esito positivo restituisca un risultato utilizzabile. La valutazione esplicita dei risultati è necessaria per mantenere la qualità dei dati.

Confronto di esempio di richiesta e risposta

Gli esempi seguenti mostrano come le richieste comuni di Azure Maps Search v1 siano mappate ai loro equivalenti nell'API di ricerca 2026-01-01. Ogni esempio è incentrato sulla stessa finalità dell'utente, evidenziando il passaggio dagli endpoint v1 multiuso alle API specifiche della finalità.

Geocodifica diretta (coordinate → indirizzo)

Nell'API di ricerca v1 la geocodifica in avanti è stata in genere eseguita usando gli endpoint search Address o Search Fuzzy. Nell'API di ricerca 2026-01-01 questa funzionalità viene fornita dall'API Get Geocoding, che risolve l'input di indirizzi strutturati o non strutturati in coordinate geografiche usando un endpoint specifico della finalità dedicato.

Cerca v1 - Indirizzo di ricerca

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

Search 2026‑01‑01 – Get Geocoding

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

Ricerca fuzzy di indirizzi o luoghi (risultato finale)

L'API Search v1 esponeva la risoluzione fuzzy di indirizzi e luoghi tramite un unico endpoint, Search Fuzzy. Nell'API di ricerca 2026-01-01, questo comportamento viene sostituito da Get Geocoding, che gestisce l'indirizzo in formato libero e inserisce le query separando al contempo scenari di completamento automatico e suggerimenti in API distinte.

Search v1 – Search Fuzzy

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

Search 2026‑01‑01 – Get Geocoding

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

Completamento automatico con suggerimenti mentre digiti

Nell'API Search API v1, il comportamento type‑ahead è stato abilitato impostando typeahead=true sull'endpoint [Search Fuzzy]. Nell'API di ricerca 2026-01-01 gli scenari di completamento automatico vengono gestiti in modo esplicito dall'API Get Geocode Autocomplete, ottimizzata per l'input interattivo dell'utente e i suggerimenti in tempo reale.

Search v1 – Search Fuzzy (type‑ahead usage)

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

Per altre informazioni, vedere Introduzione all'API di completamento automatico del codice geografico di Mappe di Azure.

Geocodifica diretta batch

L'API Search v1 supportava la risoluzione degli indirizzi batch tramite l'endpoint Search Address Batch. Nell'API di ricerca 2026-01-01 questa funzionalità è fornita da Get Geocoding Batch, consentendo l'invio e l'elaborazione di più query di indirizzi in una singola richiesta per carichi di lavoro su larga scala o in background.

Search v1 – Search Address Batch

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

Geocodifica inversa (coordinate → indirizzo)

La geocodifica inversa nell'API di ricerca v1 è stata eseguita usando l'endpoint inverso dell'indirizzo di ricerca. Nell'API di ricerca 2026-01-01 questa funzionalità è disponibile tramite Get Reverse Geocoding, che converte le coordinate di longitudine e latitudine in un indirizzo leggibile usando un'API di ricerca inversa dedicata.

Search v1 – Search Address Reverse

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

Search 2026‑01‑01 – Get Reverse Geocoding

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

Geocodifica inversa batch

L'API di ricerca v1 abilitava ricerche inverse batch tramite Get Search Address Reverse Batch. Nell'API di ricerca 2026-01-01 questo scenario è supportato da Get Reverse Geocoding Batch, consentendo la risoluzione di più coppie di coordinate agli indirizzi in una singola richiesta di telemetria, rilevamento o pipeline di arricchimento.

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

Recupero dei limiti amministrativi

Nell'API di ricerca v1 la geometria dei limiti amministrativi è stata recuperata usando Get Search Polygon. Nell'API di ricerca 2026-01-01 questa funzionalità viene fornita dall'API Get Polygon, che restituisce la geometria dei limiti per le entità amministrative supportate, ad esempio paesi/aree geografiche e città.

Ricerca v1 - Ottieni poligono di ricerca

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

Ricerca 2026-01-01 - Get Polygon

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

Elenco di controllo per la migrazione

• Inventario di tutti gli endpoint di ricerca v1 in uso
• Identificare la finalità (completamento automatico e geocodice finale)
• Sostituire gli endpoint v1 con equivalenti 2026-01-01
• Aggiornare i parametri di query
• Convalidare l'analisi delle risposte
• Introduzione alle API batch, se applicabile
• Aggiornare documentazione ed esempi

Passaggi successivi

Procedure consigliate per il servizio di ricerca di Mappe di Azure