Migrieren der Bing Maps Geocode Dataflow-API

In diesem Artikel wird erläutert, wie Sie die Bing Maps Geocode Dataflow-API zu Azure Maps Geocodierungsbatch und umgekehrte 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 an die Azure Maps Geocoding API in einer einzigen Anforderung 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 Geoflow-API von Bing Maps unterstützt die Vorwärts- und umgekehrte Batch-Geocodierung innerhalb derselben 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). Azure Maps Geocoding Batch und umgekehrte Geocoding Batch API 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-Geocodierungsbatch- und umgekehrte Geocodierungsbatch-API unterstützt bis zu 100 batchierte 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 synchrone Anforderung der Azure Maps-Geocodierungsbatch- und umgekehrten Geocodierungsbatch-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 Datenresidenz auf die europäischen (EU) oder US-amerikanischen (US) geografischen Bereiche (Geografien) beschränken können. Alle Anforderungen (einschließlich Eingabedaten) werden ausschließlich im angegebenen geografischen Bereich verarbeitet. Weitere Informationen finden Sie unter Geografischer Bereich des Azure Maps-Dienstes.

Sicherheit und Authentifizierung

Bing Maps for Enterprise unterstützt nur die Authentifizierung mit einem API-Schlüssel. Azure Maps unterstützt mehrere Möglichkeiten für die Authentifizierung Ihrer API-Aufrufe, z. B. Abonnementschlüssel, Microsoft Entra ID oder SAS-Tokens (Shared Access Signature). Weitere Informationen zur Sicherheit und Authentifizierung in Azure Maps finden Sie unter Authentifizierung mit Azure Maps und im Abschnitt Sicherheit der Dokumentation zu Azure Maps Geocoding Batch.

Anforderungsparameter

In der folgenden Tabelle sind die Bing Maps Geocode Dataflow-Anforderungsparameter und die Azure Maps-Entsprechung aufgeführt:

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

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

Weitere Informationen zu den Antwortfeldern des Azure Maps-Geocodierungsbatchs finden Sie in der Antwort Definitionen.

Beispiele für Anforderungen

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 Dataflows 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 den Content-Type Header auf application/jsonfestgelegt 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 umgekehrte Geocoding Batch API-Anforderung:

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

Um die umgekehrten Geocodierungsabfragen zu senden, verwenden Sie eine HTTP POST-Anforderung, bei der der Textkörper der Anforderung ein batchItems Array im JSON-Format enthält, und den Content-Type Header auf application/jsonfestgelegt 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 abgeschlossenen Auftragsstatus 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.

Im folgenden Beispiel wird gezeigt, was beim Ausführen der Anforderung für das Geocoding Batch in Azure Maps im Text 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"
      }
    }
  ]
}

Im folgenden Beispiel wird gezeigt, was beim Ausführen der Anforderung für das umgekehrte Geocoding Batch in Azure Maps im Text der HTTP-Antwort zurückgegeben 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.

Weitere Informationen

More Azure Maps Geocoding APIs

• Geocodierung abrufen: Verwenden Sie diese Eigenschaft, um Breiten- und Längengradkoordinaten einer Straßenadresse oder eines Ortsnamens abzurufen.
• Umgekehrtes Geocoding abrufen: Dient zum Abrufen einer Adresse und Standortinformationen aus Breiten- und Längengradkoordinaten.

Unterstützung

• Microsoft Q&A-Forum