Migrieren der Bing Maps Geocode Dataflow-API

In diesem Artikel wird erläutert, wie Sie die Bing Maps Geocode Dataflow-API zu Azure Maps Geocoding Batch und Reverse Geocoding Batch API migrieren. Die Geocodierungsbatch-API von Azure Maps wird verwendet, um Breiten- und Längengradkoordinaten einer Straße oder eines Namens eines Orts im Batchmodus mit einem einzelnen API-Aufruf abzurufen. Azure Maps Geocoding Batch API ist eine HTTP POST-Anforderung, die Batches von Abfragen in einer einzigen Anforderung an die Geocodierungs-API von Azure Maps sendet. Die Azure Maps Reverse Geocoding Batch-API wird verwendet, um Breiten- und Längengradkoordinaten in eine menschlichen verständlichen Straßenadresse zu übersetzen. Azure Maps Reverse Geocoding Batch API ist eine HTTP POST-Anforderung, die Batches von Abfragen an die Azure Maps Get Reverse Geocoding API in einer einzigen Anforderung sendet.

Voraussetzungen

• Ein Azure-Konto
• Ein Azure Maps-Konto
• Ein Abonnementschlüssel oder eine andere Form der Authentifizierung bei Azure Maps

Wichtige Unterschiede

• Die Bing Maps Geocode Dataflow-API unterstützt sowohl die Vorwärts- als auch die Rückwärts-Batch-Geocodierung innerhalb einer einzigen API. Azure Maps verfügt über eine separate API für vorwärts- und umgekehrte Geocodierung.
• Die Bing Maps Geocode Dataflow-API erfordert das Hochladen Ihrer Standortdaten als XML- oder Textdatendatei (CSV, Pipe oder Tabulatortrennzeichen). Die Geocodierungsbatch- und Reverse-Geocodierungsbatch-API von Azure Maps verwenden keinen Ansatz zum Hochladen von Datendateien, sondern eine HTTP POST-Anforderung mit Standortdaten im GeoJSON-Format im Textkörper der Anforderung.
• Bing Maps Geocode Dataflow-API unterstützt bis zu 200.000 Entitäten pro Upload. Die Azure Maps-API für Geocodierungs-Batches und Reverse-Geocodierungs-Batches unterstützt bis zu 100 Batch-Abfragen in einer synchronen Anforderung und bis zu 200.000 in einer asynchronen Anforderung.
• Die Bing Maps Geocode Dataflow-API erfordert eine Reihe von API-Aufrufen nach dem anfänglichen Datenupload, um den Status und die Downloadergebnisse abzurufen. Für die synchronen Anfragen Azure Maps Geocoding Batch und Reverse Geocoding Batch API sind keine zusätzlichen API-Aufrufe erforderlich. Für die asynchrone Anforderung sind zusätzliche Aufrufe erforderlich, um den Batchprozessstatus abzurufen und Ergebnisse herunterzuladen.
• Die Geocode-Datenflusskoordinaten von Bing Maps befinden sich im Breiten-/Längengradformat. Azure Maps-Geocodierungsbatch- und umgekehrte Geocodierungsbatch-API-Koordinaten sind im Längen-/Breitengradformat (aufgrund des GeoJSON-Formats).
• Im Gegensatz zu Bing Maps for Enterprise ist Azure Maps ein globaler Dienst, der die Angabe eines geografischen Bereichs unterstützt, mit dem Sie die Datenaufbewahrung auf die europäischen (EU) oder usa (USA) geografischen Gebiete (Geos) beschränken können. Alle Anforderungen (einschließlich Eingabedaten) werden ausschließlich im angegebenen geografischen Bereich verarbeitet. Weitere Informationen finden Sie im geografischen Bereich des Azure Maps-Diensts.

Sicherheit und Authentifizierung

Bing Maps for Enterprise unterstützt nur die API-Schlüsselauthentifizierung. Azure Maps unterstützt mehrere Möglichkeiten zum Authentifizieren Ihrer API-Aufrufe, z. B. eines Abonnementschlüssels, einer Microsoft Entra-ID oder eines SAS-Tokens (Shared Access Signature). Weitere Informationen zur Sicherheit und Authentifizierung in Azure Maps finden Sie im Abschnitt "Authentifizierung mit Azure Maps " und im Abschnitt "Sicherheit" in der Dokumentation zum Geocodierungsbatch von Azure Maps.

Anforderungsparameter

In der folgenden Tabelle sind die Bing Maps Geocode Dataflow-Anforderungsparameter und deren Äquivalente bei Azure Maps aufgeführt.

Weitere Informationen zu den Azure Maps-URI-Parametern und anforderungstext finden Sie in der Dokumentation zum Azure Maps-Geocodierungsbatch und umgekehrten Geocodierungsbatch .

Bing Maps Data Schema 2.0-Eingabe- und Ausgabevergleich mit Azure Maps Geocode Batch und Reverse Geocode Batch API:

Weitere Informationen zu den Antwortfeldern des Azure Maps-Geocodierungsbatchs finden Sie in den Antwortdefinitionen.

Beispiele anfordern

Bing Maps Geocode Dataflow-API-Anforderung :

http://spatial.virtualearth.net/REST/v1/Dataflows/Geocode?input=xml&key={BingMapsKey}

Beispiele, die Beispieleingabe- und Ausgabedaten für Version 2.0 des Geocode-Datenflusses zeigen, finden Sie unter Geocode Dataflow Sample Input and Output Data Version 2.0.

Azure Maps Geocoding Batch-API-Anforderung:

POST https://atlas.microsoft.com/geocode:batch?api-version=2023-06-01&subscription-key={Your-Azure-Maps-Subscription-key}

Um die Geocodierungsabfragen zu senden, verwenden Sie eine HTTP POST-Anforderung, bei der der Textkörper der Anforderung das BatchItems-Array im JSON-Format enthält und der Content-Type-Header auf "application/json" festgelegt ist.

Der folgende JSON-Code zeigt eine Beispielanforderung mit zwei Geocodierungsabfragen mit einem Speicherort im unstrukturierten Format und einem Speicherort im strukturierten Format:

{ 
  "batchItems": [ 
    { 
      "addressLine": "One, Microsoft Way, Redmond, WA 98052", 
      "top": 2 
    }, 
    { 
      "addressLine": "Pike Pl", 
      "adminDistrict": "WA", 
      "locality": "Seattle", 
      "top": 3 
    } 
  ] 
} 

Beispiel für azure Maps Reverse Geocoding Batch-API-Anforderung:

POST https://atlas.microsoft.com/reverseGeocode:batch?api-version=2023-06-01&subscription-key={Your-Azure-Maps-Subscription-key}

Verwenden Sie zum Senden der umgekehrten Geocodierungsabfragen eine HTTP POST-Anforderung, bei der der Textkörper der Anforderung ein BatchItems-Array im JSON-Format enthält und der Content-Type-Header auf "application/json" festgelegt ist.

Der folgende JSON-Code zeigt eine Beispielanforderung mit zwei umgekehrten Geocodierungsabfragen:

{ 
  "batchItems": [ 
    { 
      "coordinates": [ 
        -122.128275, 
        47.639429 
      ], 
      "resultTypes": [ 
        "Address", 
        "PopulatedPlace" 
      ], 
      "optionalId": "4C3681A6C8AA4AC3441412763A2A25C81444DC8B" 
    }, 
    { 
      "coordinates": [ 
        -122.341979399674, 
        47.6095253501216 
      ], 
      "optionalId": "6M9W39P12SNHGAIZ4JQ7F57NWJLV2BRYEQRD7OH7" 
    } 
  ] 
} 

Beispielantworten

Eine URL zum Herunterladen der Geocode-Auftragsergebnisse wird bereitgestellt, wenn der Geocode Dataflow-Batchauftrag von Bing Maps erfolgreich verarbeitet wird, wie im Status des abgeschlossenen Auftrags dargestellt. Ein Beispiel für eine erfolgreiche Bing Maps Geocode Dataflow-Ausgabe finden Sie unter Geocode Dataflow Sample Input and Output Data Version 2.0 in der Bing Maps-Dokumentation.

Das folgende Beispiel zeigt, was beim Ausführen einer Azure Maps-Geocoding-Batch-API-Anforderung im Inhalt der HTTP-Antwort zurückgegeben wird.

{ 
  "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"
      }
    }
  ]
}

Das folgende Beispiel zeigt, was im Textkörper der HTTP-Antwort zurückgegeben wird, wenn eine Azure Maps Reverse Geocoding Batch-API-Anforderung ausgeführt wird:

{ 
    "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 
    } 
} 

Transaktionsnutzung

Ähnlich wie die Geocode-Dataflow-API von Bing Maps protokollieren Azure Maps-Geocodierungsbatch- und umgekehrte Geocodierungsbatch-APIs eine abrechnende Transaktion pro geocodiertem Element. Beispielsweise ergeben 100 Standorte, die in der Batchanforderung geocodiert sind, 100 abrechnungsfähige Transaktionen. Weitere Informationen zu Azure Maps-Transaktionen finden Sie unter Grundlegendes zu Azure Maps-Transaktionen.

Zusatzinformation

Weitere Geocodierungs-APIs für Azure Maps

• Geocodierung abrufen: Dient zum Abrufen von Breiten- und Längengradkoordinaten einer Straße oder eines Namens eines Orts.
• Reverse Geocoding abrufen: Dient zum Abrufen einer Straßenadresse und Standortinformationen aus Breiten- und Längengradkoordinaten.

Support

• Microsoft Q&A-Forum