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

Die Maps JavaScript API Version 2 ist seit dem 26. Mai 2021 nicht mehr verfügbar. Die Karten Ihrer Website (Version 2) funktionieren dann nicht mehr und es 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. Dieser Leitfaden hilft Ihnen dabei.

Überblick

Der Migrationsprozess unterscheidet sich bei jeder Anwendung leicht. Einige Schritte sind jedoch bei allen Projekten gleich:

  1. Fordern Sie einen neuen Schlüssel an. In der Maps JavaScript API werden Schlüssel jetzt über die Google Cloud Console verwaltet. Falls Sie noch einen Schlüssel der Version 2 verwenden, fordern Sie Ihren neuen API-Schlüssel an, bevor Sie mit der Migration beginnen.
  2. Aktualisieren Sie das API-Bootstrap. In den meisten Anwendungen wird die Maps JavaScript API Version 3 mit folgendem Code geladen:
    <script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
  3. Aktualisiere deinen Code. Der Umfang der erforderlichen Änderungen hängt stark von Ihrer Anwendung ab. Zu den häufigsten Änderungen gehören:
    • Verweisen Sie immer auf den Namespace „google.maps“. In Version 3 wird der gesamte Maps JavaScript API-Code im Namespace google.maps.* und nicht im globalen Namespace gespeichert. Die meisten Objekte wurden im Rahmen dieses Prozesses ebenfalls umbenannt. Statt GMap2 wird jetzt beispielsweise google.maps.Map geladen.
    • Entfernen Sie alle Verweise auf veraltete Methoden. Eine Reihe von allgemeinen Dienstprogrammmethoden wie GDownloadURL und GLog wurde entfernt. Ersetzen Sie diese Funktion durch Dienstprogrammbibliotheken von Drittanbietern oder entfernen Sie diese Verweise aus Ihrem Code.
    • Optional: Bibliotheken in den Code einfügen Viele Funktionen wurden in Dienstprogrammbibliotheken ausgelagert, sodass jede Anwendung nur die Teile der API laden muss, die verwendet werden.
    • (Optional) Konfigurieren Sie Ihr Projekt für die Verwendung externer Version 3. Die externen v3-Elemente können verwendet werden, um Ihren Code mit dem Closure Compiler zu validieren oder die automatische Vervollständigung in Ihrer IDE auszulösen. Weitere Informationen finden Sie unter Erweiterte Kompilierung und Extern.
  4. Testen und wiederholen. Es gibt noch einiges zu tun, aber die gute Nachricht: Sie sind auf dem besten Weg zu Ihrer neuen Kartenanwendung der Version 3.

Änderungen in Version 3 der Maps JavaScript API

Bevor Sie die Migration planen, sollten Sie sich mit den Unterschieden zwischen der Maps JavaScript API Version 2 und Version 3 vertraut machen. Die neueste Version der Maps JavaScript API wurde von Grund auf neu entwickelt. Im Fokus standen moderne JavaScript-Programmiertechniken, mehr Bibliotheken und eine vereinfachte API. Die API wurde um viele neue Funktionen ergänzt und einige bekannte Funktionen wurden geändert oder sogar entfernt. In diesem Abschnitt werden einige der wichtigsten Unterschiede zwischen den beiden Releases hervorgehoben.

Die API v3 umfasst folgende Änderungen:

  • Eine optimierte Kernbibliothek. Viele der ergänzenden Funktionen wurden in Bibliotheken verschoben. Dadurch wurden die Lade- und Analysezeiten für die Core API verkürzt. So kann die Karte auf jedem Gerät schnell geladen werden.
  • Die Leistung verschiedener Funktionen wie Polygon-Rendering und Markierungsposition wurde verbessert.
  • Ein neuer Ansatz für clientseitige Nutzungslimits, um gemeinsame Adressen, die von mobilen Proxys und Unternehmensfirewalls verwendet werden, besser zu berücksichtigen.
  • Unterstützung mehrerer moderner Browser und mobiler Browser wurde hinzugefügt. Internet Explorer 6 wird nicht mehr unterstützt.
  • Viele der allgemeinen Hilfsklassen ( GLog oder GDownloadUrl) wurden entfernt. Mittlerweile 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 eigenen Fotos. So können Sie Panoramen von Skipisten, Häusern oder anderen interessanten Orten teilen.
  • Anpassungen für Karten mit benutzerdefinierten Stilen, mit denen Sie die Darstellung von Elementen auf der Basiskarte an Ihren individuellen visuellen Stil anpassen können
  • Unterstützung verschiedener neuer Dienste wie ElevationService und Distance Matrix
  • Ein verbesserter Routendienst bietet alternative Routen, Routenoptimierung (ungefähre Lösungen für das Problem des Vertriebsmitarbeiters), Fahrradrouten (mit Fahrradebene), Routen für öffentliche Verkehrsmittel und ziehbare Routen.
  • Ein aktualisiertes Geocoding-Format, das genauere Typinformationen als der accuracy-Wert der Geocoding API Version 2 liefert
  • Unterstützung mehrerer Infofenster auf einer einzelnen Karte

Upgrade der Anwendung

Ihr neuer Schlüssel

Die Maps JavaScript API Version 3 verwendet ein neues Schlüsselsystem aus Version 2. Möglicherweise verwenden Sie bereits einen Schlüssel der Version 3 mit Ihrer Anwendung. In diesem Fall ist keine Änderung erforderlich. Prüfen Sie dazu die URL, über die Sie die Maps JavaScript API auf ihren key-Parameter laden. Wenn der Schlüsselwert mit "ABQIAA" beginnt, verwenden Sie einen Schlüssel der Version 2. Wenn Sie einen Schlüssel der Version 2 haben, müssen Sie im Rahmen der Migration ein Upgrade auf einen Schlüssel der Version 3 durchführen. Dies hat folgende Auswirkungen:

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

Hinweis: 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 Version 3 der Maps JavaScript API weiterhin unterstützt und müssen nicht für die Schlüsselaktualisierung durchgeführt werden.

API laden

Bei der ersten Änderung, die Sie an Ihrem Code vornehmen müssen, geht es darum, wie Sie die API laden. In Version 2 wird die Maps JavaScript API über eine Anfrage an http://maps.google.com/maps geladen. Wenn Sie die Maps JavaScript API Version 3 laden, müssen Sie die folgenden Änderungen vornehmen:

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

Im einfachsten Fall gibt das V3-Bootstrap nur Ihren API-Schlüsselparameter an:

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

Im folgenden Beispiel wird die neueste Version der Maps JavaScript API Version 2 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 des Namespace „google.maps“

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

Wenn Sie Ihre Anwendung zu v3 migrieren, müssen Sie Ihren Code ändern, um den neuen Namespace zu verwenden. Die Suche nach „G“ und das Ersetzen durch „google.maps.“ funktioniert leider nicht vollständig, aber es ist eine gute Faustregel, die Sie beim Überprüfen Ihres Codes anwenden sollten. Im Folgenden finden Sie einige Beispiele für äquivalente Klassen in v2 und v3.

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

Entfernen von veraltetem Google-Code

In Version 3 der Maps JavaScript API gibt es Parallelen zu den meisten Funktionen von Version 2. Einige Klassen werden jedoch nicht mehr unterstützt. Im Rahmen der Migration sollten Sie diese Klassen entweder durch Dienstprogrammbibliotheken 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 Version 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 im Vergleich

Vergleichen wir zwei eher einfache Anwendungen, die mit der API v2 und v3 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 mehrere 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 in der API durch google.maps.Map als zentrales Objekt ersetzt.
  • Eigenschaften werden jetzt über die Optionenklassen geladen. Im Beispiel oben werden die drei Eigenschaften center, zoom und mapTypeId, die zum Laden einer Karte erforderlich sind, über ein Inline-Objekt MapOptions festgelegt.
  • Die Standardbenutzeroberfläche ist in v3 aktiviert. Sie können dies deaktivieren, indem Sie das Attribut disableDefaultUI im MapOptions-Objekt auf „true“ setzen.

Zusammenfassung

Sie haben jetzt einen Überblick über die 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. Die folgenden Abschnitte enthalten Migrationsanleitungen für bestimmte Fälle, auf die Sie stoßen können. Darüber hinaus gibt es mehrere Ressourcen, die während des Upgrades hilfreich sein können.

  • In der Entwicklerdokumentation für Version 3 der Maps JavaScript API erfahren Sie mehr über die API und ihre Funktionsweise.
  • In der Referenz zur Maps JavaScript API (Version 3) erfahren Sie mehr über die neuen Klassen und Methoden in der API Version 3.
  • Die Stack Overflow-Community ist der ideale Ort, um Fragen zu Code zu stellen. Verwenden Sie auf der Website für Fragen und Antworten, die sich auf die Maps JavaScript API beziehen, die Tags google-maps oder google-maps-api-3.
  • Kunden mit der Google Maps Platform-Premiumoption sollten die Dokumentation zur Google Maps Platform-Premiumoption lesen.
  • Im Google Geo Developers-Blog können Sie sich hervorragend über die neuesten Änderungen an der API informieren.

Bei Problemen oder Fragen zu diesem Artikel klicken Sie bitte oben auf dieser Seite auf den Link FEEDBACK SENDEN.

Ausführliche Referenz

In diesem Abschnitt finden Sie einen detaillierten Vergleich der beliebtesten Funktionen von Version 2 und 3 der Maps JavaScript API. Jeder Abschnitt der Referenz ist so konzipiert, dass er einzeln gelesen werden kann. Wir empfehlen, diese Referenz nicht vollständig zu lesen. Verwenden Sie das Material stattdessen, um die Migration für den jeweiligen Fall zu unterstützen.

  • Ereignisse: Ereignisse registrieren und behandeln
  • Steuerelemente: Auf der Karte angezeigte Navigationssteuerelemente ändern
  • 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: Mit den Geocoding-, Directions- oder Street View-Diensten von Google arbeiten.

Veranstaltungen

Das Ereignismodell für die Maps JavaScript API (Version 3) ähnelt dem in Version 2, hat sich aber grundlegend geändert.

Kontrollen

In der Maps JavaScript API werden UI-Steuerelemente angezeigt, über die Nutzer mit Ihrer Karte interagieren können. Mit der API lässt sich die Darstellung dieser Steuerelemente anpassen.

Overlays

Overlays stehen für Objekte, die Sie der Karte „hinzufügen“, um Punkte, Linien, Bereiche oder Objektsammlungen 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 farbige 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 eine Einheit bearbeitet werden und stellen im Allgemeinen Sammlungen von Objekten dar.

Dienste