Die Google Maps Platform-Webdienste sind eine Sammlung von HTTP-Schnittstellen zu Google-Diensten, die geografische Daten für Ihre Kartenanwendungen bereitstellen.
In diesem Leitfaden werden einige gängige Vorgehensweisen beschrieben, die beim Einrichten von Webdienstanfragen und Verarbeiten von Dienstantworten hilfreich sind. Im Entwicklerhandbuch finden Sie die vollständige Dokumentation zur Address Validation API.
Was ist ein Webdienst?
Google Maps Platform-Webdienste sind eine Schnittstelle, über die Sie Maps API-Daten von externen Diensten anfordern und in Ihren Maps-Anwendungen verwenden können. Diese Dienste sind für die Verwendung in Verbindung mit einer Karte vorgesehen, wie in den Lizenzbeschränkungen in den Nutzungsbedingungen der Google Maps Platform beschrieben.
Die Maps APIs-Webdienste verwenden HTTP(S)-Anfragen an bestimmte URLs und übergeben dabei URL-Parameter und/oder POST-Daten im JSON-Format als Argumente an die Dienste. Im Allgemeinen geben diese Dienste Daten im Antworttext im JSON-Format zurück, um sie durch Ihre Anwendung zu parsen und/oder zu verarbeiten.
Senden Sie eine HTTP-POST-Anfrage an die Methode validAddress, um eine Adresse zu validieren:
https://addressvalidation.googleapis.com/v1:validateAddress
Übergeben Sie einen JSON-Text an die Anfrage, in der die zu validierende Adresse definiert wird.
Hinweis: Alle Anwendungen mit der Address Validation API erfordern eine Authentifizierung. Weitere Informationen zu Anmeldedaten für die Authentifizierung
SSL/TLS-Zugriff
HTTPS ist für alle Google Maps Platform-Anfragen erforderlich, die API-Schlüssel verwenden oder Nutzerdaten enthalten. Über HTTP gesendete Anfragen, die sensible Daten enthalten, können abgelehnt werden.
Gültige URL erstellen
Es mag den Anschein haben, dass „gültige“ URLs eine Selbstverständlichkeit sind. Das ist jedoch nicht der Fall. So kann beispielsweise eine URL, die in die Adresszeile eines Browsers eingegeben wird, Sonderzeichen wie "上海+中國" enthalten. Der Browser muss diese Zeichen vor der Übertragung intern in eine andere Codierung umwandeln.
Ebenso ist es möglich, dass Code, der UTF-8-Eingaben erzeugt oder akzeptiert, URLs mit UTF-8-Zeichen als „gültig“ behandelt; diese Zeichen müssten jedoch vor dem Senden an einen Webbrowser ebenfalls umgewandelt werden.
Dieser Vorgang wird als URL-Codierung oder Prozentcodierung bezeichnet.
Sonderzeichen
Sonderzeichen müssen umgewandelt werden, da alle URLs der Syntax entsprechen müssen, die in der Spezifikation Uniform Resource Identifier (URI) angegeben ist. Das bedeutet, dass URLs nur einen Teil der ASCII-Zeichen enthalten dürfen: die bekannten alphanumerischen Symbole und einige reservierte Zeichen, die in den URLs als Steuerzeichen dienen. Hier eine Übersicht:
| Zeichensatz | characters | Verwendung in der URL |
|---|---|---|
| Alphanumerisch | A b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 8 9 6 | Textstrings, Schemas (http), Portangaben (8080) usw. |
| Nicht reserviert | - _ . ~ | Textstrings |
| Reserviert | ! * ' ( ) ; : @ & = + $ , / ? % # [ ] | Steuerzeichen und/oder Textstrings |
Beachten Sie bei der Generierung einer URL, dass diese nur die in der Tabelle aufgeführten Zeichen enthalten darf. Die Anpassung der URL an diesen Zeichensatz führt in der Regel zu zwei Problemen, nämlich dass Zeichen weggelassen oder ersetzt werden müssen:
- Die Zeichen, die Sie verarbeiten möchten, sind nicht im obigen Zeichensatz enthalten. So müssen beispielsweise Zeichen ausländischer Sprachen, wie
上海+中國, mithilfe der oben angegebenen Zeichen codiert werden. Auch werden Leerzeichen, die innerhalb von URLs nicht zulässig sind, entsprechend den geltenden Konventionen oftmals durch das Zeichen'+'dargestellt. - Die Zeichen sind im obigen Zeichensatz als reservierte Zeichen enthalten, müssen aber im ursprünglichen Sinn des Zeichens verwendet werden.
So wird beispielsweise
?in URLs für den Beginn eines Abfragestrings verwendet. Möchten Sie es stattdessen für den Text „? and the Mysterions“ verwenden, müssen Sie das Zeichen'?'codieren.
Alle Zeichen, die als URL codiert werden sollen, werden mithilfe des Zeichens '%' und eines Hexadezimalwerts aus zwei Zeichen codiert, der ihrem UTF-8-Zeichen entspricht. So würde zum Beispiel der UTF-8-String 上海+中國 durch die URL-Codierung in %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B umgewandelt. Und aus ? and the Mysterians würde %3F+and+the+Mysterians oder %3F%20and%20the%20Mysterians werden.
Häufig vorkommende Zeichen, die codiert werden müssen
Folgende häufig vorkommende Zeichen müssen codiert werden:
| Unsicheres Zeichen | Codierter Wert |
|---|---|
| Leerzeichen | %20 |
| " | %22 |
| < | %3C |
| > | %3E |
| # | %23 |
| % | %25 |
| | | %7C |
Die Konvertierung von URLs, die aus Nutzereingaben empfangen werden, kann manchmal Probleme mit sich bringen. Beispielsweise kann ein Nutzer eine Adresse als „5th&Main St.“ eingeben. Im Allgemeinen sollten Sie die URL aus ihren Teilen erstellen und jede Nutzereingabe wortwörtlich betrachten.
Außerdem sind URLs für alle Google Maps Platform-Webdienste und statischen Web-APIs auf 16.384 Zeichen beschränkt. Bei den meisten Diensten wird diese Begrenzung selten erreicht. Beachten Sie jedoch, dass bestimmte Dienste einige Parameter haben, die zu langen URLs führen können.
Respektvolle Nutzung der Google APIs
Schlecht konzipierte API-Clients können sowohl das Internet als auch die Google-Server stärker als nötig belasten. Dieser Abschnitt enthält einige bewährte Methoden für Kunden der APIs. Wenn Sie diese Best Practices befolgen, können Sie verhindern, dass Ihre Anwendung aufgrund eines unbeabsichtigten Missbrauchs der APIs blockiert wird.
Exponentieller Backoff
In seltenen Fällen kann bei der Verarbeitung Ihrer Anfrage ein Fehler auftreten. Sie erhalten möglicherweise einen HTTP-Antwortcode 4XX oder 5XX oder die TCP-Verbindung zwischen Ihrem Client und dem Google-Server schlägt fehl. Oft lohnt es sich, die Anfrage noch einmal zu senden, da die Folgeanfrage möglicherweise erfolgreich ist, wenn die ursprüngliche Anfrage fehlgeschlagen ist. Es ist jedoch wichtig, Anfragen nicht einfach in einer Schleife wiederholt an die Google-Server zu senden. Dieses Verhalten kann zu einer Überlastung des Netzwerks zwischen Ihrem Client und Google führen, was für viele Parteien zu Problemen führt.
Ein besserer Ansatz ist es, wiederholte Versuche in immer größeren Abständen durchzuführen. In der Regel wird die Verzögerung bei jedem Versuch um einen multiplikativen Faktor erhöht. Dieser Ansatz wird als exponentieller Backoff bezeichnet.
Angenommen, Sie haben eine Anwendung, die diese Anfrage an die Time Zone API senden möchte:
https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510×tamp=1331161200&key=YOUR_API_KEY
Im folgenden Beispiel mit Python wird gezeigt, wie die Anforderung mit exponentiellem Backoff durchgeführt wird:
import json
import time
import urllib.error
import urllib.parse
import urllib.request
# The maps_key defined below isn't a valid Google Maps API key.
# You need to get your own API key.
# See https://developers.google.com/maps/documentation/timezone/get-api-key
API_KEY = "YOUR_KEY_HERE"
TIMEZONE_BASE_URL = "https://maps.googleapis.com/maps/api/timezone/json"
def timezone(lat, lng, timestamp):
# Join the parts of the URL together into one string.
params = urllib.parse.urlencode(
{"location": f"{lat},{lng}", "timestamp": timestamp, "key": API_KEY,}
)
url = f"{TIMEZONE_BASE_URL}?{params}"
current_delay = 0.1 # Set the initial retry delay to 100ms.
max_delay = 5 # Set the maximum retry delay to 5 seconds.
while True:
try:
# Get the API response.
response = urllib.request.urlopen(url)
except urllib.error.URLError:
pass # Fall through to the retry loop.
else:
# If we didn't get an IOError then parse the result.
result = json.load(response)
if result["status"] == "OK":
return result["timeZoneId"]
elif result["status"] != "UNKNOWN_ERROR":
# Many API errors cannot be fixed by a retry, e.g. INVALID_REQUEST or
# ZERO_RESULTS. There is no point retrying these requests.
raise Exception(result["error_message"])
if current_delay > max_delay:
raise Exception("Too many retry attempts.")
print("Waiting", current_delay, "seconds before retrying.")
time.sleep(current_delay)
current_delay *= 2 # Increase the delay each time we retry.
if __name__ == "__main__":
tz = timezone(39.6034810, -119.6822510, 1331161200)
print(f"Timezone: {tz}")
Sie sollten außerdem darauf achten, dass weiter oben in der Anwendungsaufrufkette kein Wiederholungscode vorhanden ist, der zu wiederholten Anfragen in schneller Abfolge führt.
Synchronisierte Anforderungen
Eine große Anzahl von synchronisierten Anfragen an die APIs von Google kann wie ein DDoS-Angriff (Distributed Denial of Service) auf die Infrastruktur von Google aussehen und entsprechend behandelt werden. Um dies zu vermeiden, sollten Sie darauf achten, dass API-Anfragen nicht zwischen Clients synchronisiert werden.
Angenommen, eine Anwendung zeigt die Zeit in der aktuellen Zeitzone an. Diese Anwendung wird wahrscheinlich im Client-Betriebssystem einen Alarm einrichten, mit dem das System zu Beginn der Minute aktiviert wird, damit die angezeigte Zeit aktualisiert werden kann. Die Anwendung sollte keine API-Aufrufe im Rahmen der Verarbeitung dieses Alarms ausführen.
Wenn API-Aufrufe als Reaktion auf einen festgelegten Alarm ausgeführt werden, ist das nicht hilfreich, da sie dazu führen, dass die API-Aufrufe mit dem Beginn der Minute synchronisiert werden, auch zwischen verschiedenen Geräten, anstatt gleichmäßig über die Zeit verteilt zu werden. Eine schlecht konzipierte Anwendung, die dies tut, erzeugt zu Beginn jeder Minute eine 60-mal höhere Traffic-Spitze.
Stattdessen wird bei einer guten Lösung ein zweiter Alarm für eine zufällig gewählte Zeit festgelegt. Wenn dieser zweite Alarm ausgelöst wird, ruft die Anwendung alle erforderlichen APIs auf und speichert die Ergebnisse. Wenn die Anzeige der Anwendung zu Beginn der Minute aktualisiert werden soll, werden zuvor gespeicherte Ergebnisse verwendet, anstatt die API noch einmal aufzurufen. Bei diesem Ansatz werden API-Aufrufe gleichmäßig über einen Zeitraum verteilt. Außerdem verzögern die API-Aufrufe das Rendering nicht, wenn die Anzeige aktualisiert wird.
Abgesehen vom Beginn der Minute sollten andere häufige Synchronisierungszeiten, die Sie nicht erreichen möchten, der Beginn einer Stunde und der Beginn jedes Tages um Mitternacht sein.
Antworten verarbeiten
In diesem Abschnitt wird gezeigt, wie diese Werte dynamisch aus Webdienstanforderungen extrahiert werden können.
Die Antworten der Google Maps-Webdienste sind leicht verständlich, aber nicht gerade nutzerfreundlich. Wenn Sie eine Abfrage durchführen, empfiehlt es sich, einige bestimmte Werte zu extrahieren, anstatt einen Datensatz anzuzeigen. Im Allgemeinen sollten Sie Antworten aus dem Webdienst parsen und nur die Werte extrahieren, die für Sie von Interesse sind.
Welches Parsing-Schema Sie verwenden, hängt davon ab, ob Sie die Ausgabe im JSON-Format zurückgeben. JSON-Antworten liegen bereits in Form von JavaScript-Objekten vor und können auf dem Client in JavaScript verarbeitet werden.