Maps JavaScript API-Anwendung von Version 2 auf Version 3 aktualisieren

Die Maps JavaScript API v2 ist seit dem 26. Mai 2021 nicht mehr verfügbar. Die entsprechenden Karten Ihrer Website funktionieren nicht mehr. Stattdessen werden JavaScript-Fehler zurückgegeben. Wenn Sie weiter Karten auf Ihrer Website verwenden möchten, müssen Sie zu Version 3 der Maps JavaScript API migrieren. In diesem Leitfaden wird der Prozess erläutert.

Übersicht

Jede Anwendung hat einen etwas anderen Migrationsprozess. Es gibt jedoch einige Schritte, die für alle Projekte gleich sind:

  1. Holen Sie sich einen neuen Schlüssel. Für die Maps JavaScript API werden jetzt die Schlüssel in der Google Cloud Console verwaltet. Wenn du noch einen V2-Schlüssel verwendest, solltest du dir vor Beginn der Migration einen neuen API-Schlüssel besorgen.
  2. Aktualisieren Sie Ihr API-Bootstrap. In den meisten Anwendungen wird die Maps JavaScript API 3 mit dem folgenden Code geladen:
    <script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
  3. Aktualisieren Sie Ihren Code. Der Umfang der erforderlichen Änderungen hängt stark von Ihrer Anwendung ab. Zu den häufigen Änderungen gehören:
    • Verweisen Sie immer auf den google.maps-Namespace. In Version 3 wird der gesamte Code der Maps JavaScript API im Namespace google.maps.* statt im globalen Namespace gespeichert. Die meisten Objekte wurden im Rahmen dieses Vorgangs ebenfalls umbenannt. Anstelle von GMap2 wird jetzt beispielsweise google.maps.Map geladen.
    • Entfernen Sie alle Verweise auf veraltete Methoden. Einige Dienstmethoden für allgemeine Zwecke wurden entfernt, z. B. GDownloadURL und GLog. Ersetzen Sie diese Funktionen entweder durch Dienstbibliotheken von Drittanbietern oder entfernen Sie diese Verweise aus Ihrem Code.
    • Optional: Fügen Sie Ihrem Code Bibliotheken hinzu. Viele Funktionen wurden in Dienstbibliotheken ausgelagert, sodass jede App nur die Teile der API laden muss, die verwendet werden.
    • Optional: Konfigurieren Sie Ihr Projekt für die Verwendung der externen V3-Assets. Mit den externen V3-Elementen können Sie Ihren Code mit dem Closure Compiler validieren oder die automatische Vervollständigung in Ihrer IDE auslösen. Weitere Informationen zu erweiterter Kompilierung und externen Dateien
  4. Testen und iterieren Sie haben noch etwas Arbeit vor sich, aber Sie sind auf dem besten Weg zu Ihrer neuen Kartenanwendung in Version 3.

Änderungen in Version 3 der Maps JavaScript API

Bevor Sie mit der Migration beginnen, sollten Sie sich mit den Unterschieden zwischen der Maps JavaScript API Version 2 und der Maps JavaScript API Version 3 vertraut machen. Die neueste Version der Maps JavaScript API wurde von Grund auf neu geschrieben. Dabei wurde ein Schwerpunkt auf moderne JavaScript-Programmiertechniken, eine verstärkte Nutzung von Bibliotheken und eine vereinfachte API gelegt. Der API wurden viele neue Funktionen hinzugefügt und einige bekannte Funktionen wurden geändert oder sogar entfernt. In diesem Abschnitt werden einige der wichtigsten Unterschiede zwischen den beiden Versionen hervorgehoben.

Die API v3 umfasst folgende Änderungen:

  • Eine optimierte Kernbibliothek. Viele der zusätzlichen Funktionen wurden in Bibliotheken verschoben, um die Lade- und Parsezeiten für die Core API zu reduzieren. So können Karten auf jedem Gerät schnell geladen werden.
  • Die Leistung mehrerer Funktionen wurde verbessert, z. B. das Polygon-Rendering und das Setzen von Markierungen.
  • Ein neuer Ansatz für clientseitige Nutzungslimits, um geteilte Adressen besser zu berücksichtigen, die von mobilen Proxys und Unternehmensfirewalls verwendet werden.
  • Unterstützung für mehrere moderne Browser und mobile Browser hinzugefügt. Die Unterstützung für Internet Explorer 6 wurde entfernt.
  • Viele der allgemeinen Hilfsklassen wurden entfernt ( GLog oder GDownloadUrl). Heutzutage gibt es viele hervorragende JavaScript-Bibliotheken mit ähnlichen Funktionen, z. B. Closure oder jQuery.
  • Eine HTML5-Implementierung von Street View, die auf allen Mobilgeräten geladen werden kann.
  • Benutzerdefinierte Street View-Panoramen mit Ihren eigenen Fotos, mit denen Sie Panoramabilder von Skipisten, zum Verkauf stehenden Häusern oder anderen interessanten Orten teilen können.
  • Mit Karten mit benutzerdefinierten Stilen können Sie die Darstellung von Elementen auf der Basiskarte an Ihren individuellen visuellen Stil anpassen.
  • Unterstützung für mehrere neue Dienste, z. B. ElevationService und Distance Matrix.
  • Die verbesserten Routendienste bieten alternative Routen, Routenoptimierung (ungefähre Lösungen für das Rundreiseproblem), Fahrradrouten (mit Fahrradebene), öffentliche Verkehrsmittelpläne und bewegliche Routen.
  • Ein aktualisiertes Geocoding-Format, das genauere Informationen zum Typ liefert als der Wert accuracy der Geocoding API v2.
  • Unterstützung für mehrere Infofenster auf einer einzelnen Karte

Anwendung aktualisieren

Neuer Schlüssel

Die Maps JavaScript API 3 verwendet ein neues Schlüsselsystem von Version 2. Möglicherweise verwenden Sie bereits einen V3-Schlüssel für Ihre Anwendung. In diesem Fall sind keine Änderungen erforderlich. Prüfen Sie dazu, ob der key-Parameter in der URL enthalten ist, über die Sie die Maps JavaScript API laden. Wenn der Schlüsselwert mit „ABQIAA“ beginnt, verwenden Sie einen V2-Schlüssel. Wenn Sie einen V2-Schlüssel haben, müssen Sie im Rahmen der Migration auf einen V3-Schlüssel umstellen. Dabei geschieht Folgendes:

Der Schlüssel wird beim Laden der Maps JavaScript API 3 übergeben. Weitere Informationen zum Generieren von API-Schlüsseln

Wenn Sie Google Maps APIs for Work nutzen, verwenden Sie möglicherweise eine Client-ID mit dem Parameter client anstelle des Parameters key. Client-IDs werden in der Maps JavaScript API v3 weiterhin unterstützt und müssen nicht umgestellt werden.

API laden

Die erste Änderung, die Sie an Ihrem Code vornehmen müssen, betrifft das Laden der API. In Version 2 wird die Maps JavaScript API über eine Anfrage an http://maps.google.com/maps geladen. Wenn Sie die Maps JavaScript API 3 laden, müssen Sie die folgenden Änderungen vornehmen:

  1. API von //maps.googleapis.com/maps/api/js laden
  2. Entfernen Sie den Parameter file.
  3. Aktualisieren Sie den Parameter key mit Ihrem neuen V3-Schlüssel. Kunden der Google Maps APIs for Work sollten einen client-Parameter verwenden.
  4. (Nur Google Maps Platform-Premiumoption) Der Parameter client muss wie im Entwicklerleitfaden für die Google Maps Platform-Premiumoption beschrieben angegeben werden.
  5. Entfernen Sie den Parameter v, um die neueste veröffentlichte Version anzufordern, oder ändern Sie seinen Wert entsprechend dem V3-Versionierungsschema.
  6. Optional: Ersetzen Sie den Parameter hl durch language und bewahren Sie den Wert bei.
  7. Optional: Fügen Sie einen libraries-Parameter hinzu, um optionale Bibliotheken zu laden.

Im einfachsten Fall wird in der v3-Bootstrap-Datei nur der API-Schlüsselparameter angegeben:

<script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>

Im folgenden Beispiel wird die neueste Version der Maps JavaScript API v2 auf Deutsch angefordert:

<script src="//maps.google.com/maps?file=api&v=2.x&key=YOUR_API_KEY&hl=de"></script>

Das folgende Beispiel ist eine entsprechende Anforderung für v3.

<script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&language=de"></script>

Einführung in den google.maps-Namespace

Die wohl auffälligste Änderung in der Maps JavaScript API Version 3 ist die Einführung des google.maps-Namespace. Die V2 API platziert standardmäßig alle Objekte im globalen Namespace, was zu Namenskollisionen führen kann. In Version 3 befinden sich alle Objekte im Namespace google.maps.

Wenn Sie Ihre Anwendung zu Version 3 migrieren, müssen Sie Ihren Code ändern, damit der neue Namespace verwendet werden kann. Leider funktioniert es nicht ganz, nach „G“ zu suchen und es durch „google.maps.“ zu ersetzen. Es ist jedoch eine gute Faustregel, die Sie beim Überprüfen Ihres Codes anwenden können. Im Folgenden finden Sie einige Beispiele für die entsprechenden Klassen in Version 2 und Version 3.

v2 v3
GMap2 google.maps.Map
GLatLng google.maps.LatLng
GInfoWindow google.maps.InfoWindow
GMapOptions google.map.MapOptions
G_API_VERSION google.maps.version
GPolyStyleOptions google.maps.PolygonOptions
or google.maps.PolylineOptions

Veralteten Code entfernen

Die Maps JavaScript API 3 bietet Parallelen zu den meisten Funktionen in Version 2. Es gibt jedoch einige Klassen, die nicht mehr unterstützt werden. Im Rahmen der Migration sollten Sie diese Klassen entweder durch Dienstbibliotheken von Drittanbietern ersetzen oder diese Verweise aus Ihrem Code entfernen. Es gibt viele hervorragende JavaScript-Bibliotheken mit ähnlichen Funktionen, z. B. Closure oder jQuery.

Die folgenden Klassen haben in der Maps JavaScript API 3 keine Entsprechung:

GBoundsGLanguage
GBrowserIsCompatibleGLayer
GControlGLog
GControlAnchorGMercatorProjection
GControlImplGNavLabelControl
GControlPositionGObliqueMercator
GCopyrightGOverlay
GCopyrightCollectionGPhotoSpec
GDownloadUrlGPolyEditingOptions
GDraggableObjectGScreenOverlay
GDraggableObjectOptionsGStreetviewFeatures
GFactualGeocodeCacheGStreetviewLocation
GGeoAddressAccuracyGStreetviewOverlay
GGeocodeCacheGStreetviewUserPhotosOptions
GGoogleBarGTileLayerOptions
GGoogleBarAdsOptionsGTileLayerOverlayOptions
GGoogleBarLinkTargetGTrafficOverlayOptions
GGoogleBarListingTypesGUnload
GGoogleBarOptionsGXml
GGoogleBarResultListGXmlHttp
GInfoWindowTabGXslt
GKeyboardHandler

Code vergleichen

Vergleichen wir zwei recht einfache Anwendungen, die mit der V2- und der V3-API geschrieben wurden.

<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.google.com/maps?file=api&v=2&key=YOUR_API_KEY"></script>
    <style>
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script>
    function initialize() {
      if (GBrowserIsCompatible()) {
        var map = new GMap2(
            document.getElementById('map'));
        map.setCenter(new GLatLng(37.4419, -122.1419), 13);
        map.setUIToDefault();

        map.addOverlay(new GMarker(new GLatLng(37.4419, -122.1419)));

      }
    }
    </script>
  </head>
  <body onload="initialize()" onunload="GUnload()">
    <div id="map"></div>
  </body>
</html>
    
<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
    <style>
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script>
    function initialize() {
      var map = new google.maps.Map(
        document.getElementById('map'), {
          center: new google.maps.LatLng(37.4419, -122.1419),
          zoom: 13,
          mapTypeId: google.maps.MapTypeId.ROADMAP
      });

      var marker = new google.maps.Marker({
            position: new google.maps.LatLng(37.4419, -122.1419),
            map: map
      });

    }
    google.maps.event.addDomListener(window, 'load', initialize);
    </script>
  </head>
  <body>
    <div id="map"></div>
  </body>
</html>

Wie Sie sehen, gibt es einige Unterschiede zwischen den beiden Anwendungen. Wichtige Änderungen sind:

  • Die Adresse, über die die API geladen wird, wurde geändert.
  • Die Methoden GBrowserIsCompatible() und GUnload() sind in Version 3 nicht mehr erforderlich und wurden aus der API entfernt.
  • Das GMap2-Objekt wird durch google.maps.Map als zentrales Objekt in der API ersetzt.
  • Eigenschaften werden jetzt über die Optionenklassen geladen. Im obigen Beispiel werden die drei zum Laden einer Karte erforderlichen Eigenschaften (center, zoom und mapTypeId) über ein MapOptions-Objekt festgelegt, das inline eingefügt ist.
  • Die Standardbenutzeroberfläche ist in v3 aktiviert. Sie können dies deaktivieren, indem Sie im MapOptions-Objekt das Attribut disableDefaultUI auf „wahr“ setzen.

Zusammenfassung

Sie haben jetzt einen Eindruck von einigen der wichtigsten Punkte bei der Migration von Version 2 zu Version 3 der Maps JavaScript API erhalten. Möglicherweise benötigen Sie weitere Informationen, die jedoch von Ihrer Anwendung abhängen. In den folgenden Abschnitten finden Sie Migrationsanleitungen für bestimmte Fälle, die möglicherweise auftreten. Außerdem gibt es mehrere Ressourcen, die Ihnen während des Upgrades helfen können.

  • In der Entwicklerdokumentation für die Maps JavaScript API Version 3 finden Sie weitere Informationen zur API und ihrer Funktionsweise.
  • In der Referenz zur Maps JavaScript API Version 3 finden Sie weitere Informationen zu den neuen Klassen und Methoden in der Version 3 der API.
  • In der Stack Overflow-Community können Sie Fragen zu Code stellen. Auf der Website werden für Fragen und Antworten zur Maps JavaScript API die Tags google-maps oder google-maps-api-3 verwendet.
  • Kunden der Google Maps Platform-Premiumoption sollten sich die Dokumentation zur Google Maps Platform-Premiumoption durchlesen.
  • Im Google Geo Developers Blog erfahren Sie mehr über die neuesten Änderungen an der API.

Wenn Sie Fragen zu diesem Artikel haben, verwenden Sie bitte den Link FEEDBACK GEBEN oben auf dieser Seite.

Ausführliche Referenz

In diesem Abschnitt werden die beliebtesten Funktionen der Version 2 und Version 3 der Maps JavaScript API verglichen. Jeder Abschnitt der Referenz kann einzeln gelesen werden. Wir empfehlen, sich diese Referenz nicht vollständig durchzulesen, sondern sie je nach Fall als Leitfaden für die Migration zu verwenden.

  • Ereignisse: Ereignisse registrieren und behandeln
  • Steuerelemente: Mit diesen Steuerelementen können Sie die Navigation auf der Karte steuern.
  • Overlays: Objekte auf der Karte hinzufügen und bearbeiten.
  • Kartentypen: e Kacheln, aus denen die Basiskarte besteht
  • Ebenen: Inhalte als Gruppe hinzufügen und bearbeiten, z. B. KML- oder Verkehrsebenen.
  • Dienste: Sie arbeiten mit den Geocoding-, Wegbeschreibungs- oder Street View-Diensten von Google.

Ereignisse

Das Ereignismodell der Maps JavaScript API 3 ähnelt dem in Version 2, obwohl sich im Hintergrund viel geändert hat.

Steuerung

Die Maps JavaScript API zeigt UI-Steuerelemente an, mit denen Nutzer mit Ihrer Karte interagieren können. Mit der API können Sie anpassen, wie diese Steuerelemente angezeigt werden.

Overlays

Overlays sind Objekte, die Sie der Karte hinzufügen, um Punkte, Linien, Bereiche oder Gruppen von Objekten zu kennzeichnen.

Kartentypen

Die in Version 2 und Version 3 verfügbaren Kartentypen unterscheiden sich geringfügig, aber alle grundlegenden Kartentypen sind in beiden Versionen der API verfügbar. In Version 2 werden standardmäßig „gemalt“ aussehende Straßenkartenkacheln verwendet. In Version 3 muss beim Erstellen eines google.maps.Map-Objekts jedoch ein bestimmter Kartentyp angegeben werden.

Ebenen

Ebenen sind Objekte auf der Karte, die aus einem oder mehreren Overlays bestehen. Sie können als einzelne Einheit bearbeitet werden und spiegeln in der Regel Sammlungen von Objekten wider.

Dienste