Eseguire la migrazione dell'API Geocode Dataflow di Bing Maps
Questo articolo illustra come eseguire la migrazione dell'API Geocode Dataflow di Bing Maps alle API Geocoding Batch e Reverse Geocoding Batch di Mappe di Azure. L'API Geocoding Batch di Mappe di Azure viene usata per ottenere le coordinate di latitudine e longitudine di un indirizzo o di un nome di una posizione in modalità batch con una singola chiamata API. L'API Geocoding Batch di Mappe di Azure è una richiesta HTTP POST che invia batch di query all'API Geocoding di Mappe di Azure in una singola richiesta. L'API Reverse Geocoding Batch di Mappe di Azure viene usata per convertire le coordinate di latitudine e longitudine in un indirizzo stradale comprensibile. L'API Reverse Geocoding Batch di Mappe di Azure è una richiesta HTTP POST che invia batch di query all'API Get Reverse Geocoding di Mappe di Azure in una singola richiesta.
Prerequisiti
- Un account Azure
- Un account Mappe di Azure
- Una chiave di sottoscrizione o un altro tipo di autenticazione con Mappe di Azure
Differenze rilevanti
- L'API Geocode Dataflow di Bing Maps supporta la geocodifica batch diretta e inversa all'interno della stessa API. Mappe di Azure include API separate per la geocodifica diretta e la geocodifica inversa.
- L'API Geocode Dataflow di Bing Maps richiede il caricamento dei dati della posizione come file di dati XML o di testo (csv, pipe o delimitato da tabulazioni). Le API Geocoding Batch e Reverse Geocoding Batch di Mappe di Azure non usano un approccio di caricamento di file di dati, ma piuttosto una richiesta HTTP POST con dati sulla posizione in formato GeoJSON nel corpo della richiesta.
- L'API Geocode Dataflow di Bing Maps supporta fino a 200.000 entità per caricamento. Le API Geocoding Batch e Reverse Geocoding Batch di Mappe di Azure supportano fino a 100 query in batch in una richiesta sincrona e fino a 200.000 in una richiesta asincrona.
- L'API Geocode Dataflow di Bing Maps richiede una serie di chiamate API che seguono il caricamento iniziale dei dati per ottenere lo stato e scaricare i risultati. La richiesta sincrona delle API Geocoding Batch e Reverse Geocoding Batch di Mappe di Azure non richiede chiamate API aggiuntive. La richiesta asincrona richiede chiamate aggiuntive per ottenere lo stato del processo batch e scaricare i risultati.
- Le coordinate di Geocode Dataflow di Bing Maps sono in formato latitudine/longitudine. Le coordinate delle API Geocoding Batch e Reverse Geocoding Batch di Mappe di Azure sono in formato longitudine/latitudine, per via del formato GeoJSON.
- A differenza di Bing Maps for Enterprise, Mappe di Azure è un servizio globale che supporta la specifica di un ambito geografico, il che consente di limitare la residenza dei dati alle aree geografiche di Europa (UE) o Stati Uniti (US). Tutte le richieste (inclusi i dati di input) vengono elaborate esclusivamente nell'area geografica specificata. Per altre informazioni, vedere Ambito geografico del servizio Mappe di Azure.
Sicurezza e autenticazione
Bing Maps for Enterprise supporta solo l'autenticazione con chiave API. Mappe di Azure supporta diversi modi per autenticare le chiamate API, ad esempio una chiave di sottoscrizione, Microsoft Entra ID o il token di firma di accesso condiviso (SAS). Per altre informazioni sulla sicurezza e l'autenticazione in Mappe di Azure, vedere Autenticazione con Mappe di Azure e la sezione Sicurezza nella documentazione di Mappe di Azure Geocoding Batch.
Parametri della richiesta
Nella tabella seguente sono elencati i parametri di richiesta di Geocode Dataflow di Bing Maps e l'equivalente di Mappe di Azure:
| Parametro di Bing Maps | Parametro di Mappe di Azure | Descrizione |
|---|---|---|
| dataLocation | Non necessario | |
| input | Non necessario | L'API Geocode Dataflow di Bing Maps supporta il formato XML e testuale (csv, tabulazione e delimitato da pipe) per il file di dati di input di geocodifica batch. Mappe di Azure supporta il formato JSON per i dati di input di geocodifica batch nella richiesta HTTP POST. |
| output | Non necessario | L'API Geocode Dataflow di Bing Maps supporta JSON e XML per i dati di output del codice di geocodifica batch. Mappe di Azure supporta il formato JSON per i dati di output di geocodifica batch. |
Per altre informazioni sui parametri URI e sul corpo della richiesta di Mappe di Azure, vedere la documentazione di Geocoding Batch e Reverse Geocoding Batch di Mappe di Azure.
Confronto tra input e output dello schema dei dati di Bing Maps 2.0 con le API Geocode Batch e Reverse Geocode Batch di Mappe di Azure:
| Campo Bing Maps | Operazione di Bing Maps | Campo Mappe di Azure | Mappe di Azure tipo di dati | Descrizione |
|---|---|---|---|---|
| Address.AddressLine | Richiesta codifica geografica Risposta codifica geografica |
addressLine | string | |
| Address.AdminDistrict | Richiesta codifica geografica Risposta codifica geografica |
adminDistrict | string | |
| Address.CountryRegion | Richiesta codifica geografica Risposta codifica geografica |
countryRegion | string | |
| Address.District | Richiesta codifica geografica | adminDistrict2 | string | |
| Address.FormattedAddress | Risposta codifica geografica | |||
| Address.Landmark | Risposta codifica geografica | Non supportate | Non supportate | |
| Address.Locality | Richiesta codifica geografica Risposta codifica geografica |
locality | string | |
| Address.Neighborhood | Risposta codifica geografica | neighborhood | string | |
| Address.PostalCode | Richiesta codifica geografica Risposta codifica geografica |
postalCode | string | |
| Address.PostalTown | Richiesta codifica geografica | adminDistrict3 | ||
| BoundingBox.SouthLatitude, BoundingBox.EastLongitude, BoundingBox.NorthLatitude, BoundingBox.EastLongitude | Risposta codifica geografica | bbox | number[] | La proiezione di Mappe di Azure usata è EPSG:3857. Per altre informazioni, vedere RFC 7946. |
| Attendibilità | Risposta codifica geografica | confidence | ConfidenceEnum | Per altre informazioni, vedere la documentazione delle API Geocoding Batch e Reverse Geocoding Batch di Mappe di Azure. |
| ConfidenceFilter.MinimumConfidence | Richiesta codifica geografica Richiesta codifica geografica inversa |
Non supportate | Non supportate | |
| Impostazioni cultura | Richiesta codifica geografica Richiesta codifica geografica inversa |
Intestazione richiesta: Accept-Language | string | Per altre informazioni, vedere Lingue supportate da Mappe di Azure. |
| EntityType | Risposta codifica geografica | type | string | Per altre informazioni, vedere la documentazione delle API Geocoding Batch e Reverse Geocoding Batch di Mappe di Azure. |
| FaultReason | Risposta codifica geografica | Non supportate | Non supportato | |
| GeocodeEntity | Contenitore XML | Non necessario | Non necessario | |
| GeocodeFeed | Contenitore XML | Non necessario | Non necessario | |
| GeocodePoint | Risposta codifica geografica | geocodePoints | GeocodePoints[] | Per altre informazioni, vedere la documentazione delle API Geocoding Batch e Reverse Geocoding Batch di Mappe di Azure. |
| GeocodeRequest | Contenitore XML | Non necessario | Non necessario | Mappe di Azure include API separate per la geocodifica diretta e la geocodifica inversa. |
| ID | Richiesta codifica geografica | Non necessario | Non necessario | |
| IncludeEntityTypes | Richiesta codifica geografica Richiesta codifica geografica inversa |
Non supportate | Non supportate | |
| IncludeNeighborhood | Richiesta codifica geografica Richiesta codifica geografica inversa |
Non necessario | Non necessario | In Mappe di Azure, le informazioni sul quartiere vengono restituite nella risposta per impostazione predefinita, se disponibili. |
| IncludeQueryParse | Richiesta codifica geografica | Non supportate | Non supportate | |
| Location.Latitude Location.Longitude |
Richiesta codifica geografica inversa | coordinate | number[] | Obbligatorio come input se si usa l'API Reverse Geocoding Batch di Mappe di Azure per eseguire la geocodifica inversa. |
| MatchCodes | Risposta codifica geografica | matchCodes | MatchCodesEnum | Per altre informazioni, vedere la documentazione delle API Geocoding Batch e Reverse Geocoding Batch di Mappe di Azure. |
| MaxResults | Richiesta codifica geografica Richiesta codifica geografica inversa |
top | integer int32 |
In Mappe di Azure, il numero massimo di risposte restituite. Il valore predefinito è 5, il minimo è 1 e il massimo è 20. |
| Nome | Risposta codifica geografica | Non supportate | Non supportate | |
| Point.Latitude, Point.Longitude | Risposta codifica geografica | coordinate | number[] | Bing Maps restituisce le coordinate in formato latitudine/longitudine. Mappe di Azure restituisce le coordinate in formato longitudine/latitudine, per via del formato GeoJSON. |
| Query | Richiesta codifica geografica | query | string | |
| QueryParseValue | Risposta codifica geografica | Non supportate | Non supportato | |
| ReverseGeocodeRequest | Contenitore XML | Non necessario | Non necessario | Mappe di Azure include API separate per la geocodifica diretta e la geocodifica inversa. |
| StatusCode | Risposta codifica geografica | Non supportate | Non supportate | |
| StrictMatch | Richiesta codifica geografica | Non supportate | Non supportate | |
| TraceId | Risposta codifica geografica | Non supportate | Non supportate | |
| Versione | Non necessario | Non necessario |
Per altre informazioni sui campi di risposta di Geocoding Batch di Mappe di Azure, vedere le Definizioni di risposta.
Esempi di richiesta
Richiesta API Geocode Dataflow di Bing Maps:
http://spatial.virtualearth.net/REST/v1/Dataflows/Geocode?input=xml&key={BingMapsKey}
Per esempi che mostrano dati di input e output di esempio per la versione 2.0 di Geocode Dataflow, vedere Input di esempio di Geocode Dataflow e versione dati di output 2.0.
Richiesta API Geocoding Batch di Mappe di Azure:
POST https://atlas.microsoft.com/geocode:batch?api-version=2023-06-01&subscription-key={Your-Azure-Maps-Subscription-key}
Per inviare le query di geocodifica, usare una richiesta HTTP POST in cui il corpo contiene la matrice batchItems in formato JSON e l'intestazione Content-Type è impostata su application/json.
Il codice JSON seguente mostra una richiesta di esempio contenente due query di geocodifica, con una posizione in formato non strutturato e una posizione in formato strutturato:
{
"batchItems": [
{
"addressLine": "One, Microsoft Way, Redmond, WA 98052",
"top": 2
},
{
"addressLine": "Pike Pl",
"adminDistrict": "WA",
"locality": "Seattle",
"top": 3
}
]
}
Richiesta dell'API Reverse Geocoding Batch di Mappe di Azure di esempio:
POST https://atlas.microsoft.com/reverseGeocode:batch?api-version=2023-06-01&subscription-key={Your-Azure-Maps-Subscription-key}
Per inviare le query di geocodifica inversa, usare una richiesta HTTP POST in cui il corpo contiene una matrice batchItems in formato JSON e l'intestazione Content-Type è impostata su application/json.
Il codice JSON seguente mostra una richiesta di esempio contenente due query di geocodifica inversa:
{
"batchItems": [
{
"coordinates": [
-122.128275,
47.639429
],
"resultTypes": [
"Address",
"PopulatedPlace"
],
"optionalId": "4C3681A6C8AA4AC3441412763A2A25C81444DC8B"
},
{
"coordinates": [
-122.341979399674,
47.6095253501216
],
"optionalId": "6M9W39P12SNHGAIZ4JQ7F57NWJLV2BRYEQRD7OH7"
}
]
}
Esempi di risposta
Un URL per scaricare i risultati del processo di geocodifica viene fornito quando il processo batch Geocode Dataflow di Bing Maps viene elaborato correttamente, come illustrato dallo stato Completato del processo. Per un esempio di output Geocode Dataflow riuscito di Bing Maps, vedere Input di esempio di Geocode Dataflow e versione dati di output 2.0 nella documentazione di Bing Maps.
L'esempio seguente illustra cosa viene restituito nel corpo della risposta HTTP durante l'esecuzione di una richiesta API Geocoding Batch di Mappe di Azure:
{
"summary": {
"successfulRequests": 1,
"totalRequests": 2
},
"batchItems": [
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"type": "Address",
"confidence": "High",
"matchCodes": [
"Good"
],
"address": {
"locality": "Redmond",
"adminDistricts": [
{
"shortName": "WA"
},
{
"shortName": "King"
}
],
"countryRegion": {
"ISO": "US",
"name": "United States"
},
"postalCode": "98052",
"formattedAddress": "1 Microsoft Way, Redmond, WA 98052",
"addressLine": "1 Microsoft Way"
},
"geocodePoints": [
{
"geometry": {
"type": "Point",
"coordinates": [
-122.128275,
47.639429
]
},
"calculationMethod": "Rooftop",
"usageTypes": [
"Display",
"Route"
]
},
{
"geometry": {
"type": "Point",
"coordinates": [
-122.127028,
47.638545
]
},
"calculationMethod": "Rooftop",
"usageTypes": [
"Route"
]
}
]
},
"geometry": {
"type": "Point",
"coordinates": [
-122.128275,
47.639429
]
},
"bbox": [
-122.1359181505759,
47.63556628242932,
-122.1206318494241,
47.643291717570676
]
}
]
},
{
"error": {
"code": "Conflicting Parameters",
"message": "When 'query' is present, only the following parameters are valid: 'bbox, location, view, top'. 'addressLine' was passed"
}
}
]
}
L'esempio seguente illustra cosa viene restituito nel corpo della risposta HTTP durante l'esecuzione di una richiesta API Reverse Geocoding Batch di Mappe di Azure:
{
"batchItems": [
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
-122.1294081,
47.6391325
]
},
"properties": {
"geocodePoints": [
{
"geometry": {
"type": "Point",
"coordinates": [
-122.1294081,
47.6391325
]
},
"calculationMethod": "Rooftop",
"usageTypes": [
"Display"
]
}
],
"address": {
"addressLine": "15770 NE 31st St",
"adminDistricts": [
{
"shortName": "WA"
},
{
"shortName": "King Co."
}
],
"countryRegion": {
"name": "United States",
"iso": "US"
},
"locality": "Redmond",
"neighborhood": "Overlake",
"postalCode": "98052",
"formattedAddress": "15770 NE 31st St, Redmond, WA 98052, United States"
},
"confidence": "High",
"matchCodes": [
"Good"
],
"type": "Address"
},
"bbox": [
-122.13705120720665,
47.635269782429326,
-122.12176499279336,
47.64299521757068
]
}
]
},
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
-122.341979399674,
47.6095253501216
]
},
"properties": {
"geocodePoints": [
{
"geometry": {
"type": "Point",
"coordinates": [
-122.341979399674,
47.6095253501216
]
},
"calculationMethod": "Interpolation",
"usageTypes": [
"Display",
"Route"
]
}
],
"address": {
"addressLine": "1736 Pike Pl",
"adminDistricts": [
{
"shortName": "WA"
},
{
"shortName": "King Co."
}
],
"countryRegion": {
"name": "United States",
"iso": "US"
},
"intersection": {
"baseStreet": "Pike Pl",
"displayName": "Pike Pl and Stewart St",
"intersectionType": "Near",
"secondaryStreet1": "Stewart St",
"secondaryStreet2": null
},
"locality": "Seattle",
"neighborhood": "Downtown Seattle",
"postalCode": "98101",
"formattedAddress": "1736 Pike Pl, Seattle, WA 98101, United States"
},
"confidence": "Medium",
"matchCodes": [
"Good"
],
"type": "Address"
},
"bbox": [
-122.34961817972945,
47.605662632550924,
-122.33434061961856,
47.61338806769228
]
}
]
}
],
"summary": {
"successfulRequests": 2,
"totalRequests": 2
}
}
Utilizzo delle transazioni
Analogamente all'API Geocode Dataflow di Bing Maps, le API Geocoding Batch e Reverse Geocoding Batch di Mappe di Azure registrano una transazione fatturabile per ogni elemento geocodificato. Ad esempio, 100 posizioni geocodificate nella richiesta batch generano 100 transazioni fatturabili. Per altre informazioni sulle transazioni di Mappe di Azure, vedere Informazioni sulle transazioni di Mappe di Azure.
Informazioni aggiuntive
Altre API per la geocodifica in Mappe di Azure
- Get Geocoding: usare per ottenere le coordinate di latitudine e longitudine di un indirizzo o di un nome di un luogo.
- Get Reverse Geocoding: usare per ottenere un indirizzo e informazioni sulla posizione dalle coordinate di latitudine e longitudine.
Supporto tecnico