Best Practices für die Verwendung von Air Quality API-Webdiensten

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 bei der Einrichtung der Webdienst und Dienstantworten verarbeiten können. Weitere Informationen finden Sie im Entwicklerhandbuch. finden Sie eine vollständige Dokumentation der Air Quality API.

Was ist ein Webdienst?

Google Maps Platform-Webdienste sind eine Schnittstelle zum Anfordern von Maps API-Daten von externe Dienste und die Verwendung der Daten in Ihren Maps-Anwendungen. Diese Dienste sind die zur Verwendung in Verbindung mit einer Karte entwickelt wurden, siehe Lizenzbeschränkungen in den Nutzungsbedingungen für die Google Maps Platform beschrieben.

Die Maps APIs-Webdienste verwenden HTTP(S)-Anfragen an bestimmte URLs, wobei URL-Parameter und/oder POST-Daten im JSON-Format als Argumente für die Dienste. Im Allgemeinen geben diese Dienste Daten in der Antworttext als JSON für das Parsen und/oder Verarbeitung durch Ihre Anwendung.

Aktuelle stündliche Luftqualität anfordern mit currentConditions Endpunkt durch Senden einer HTTP-POST-Anfrage an folgende Adresse:

https://airquality.googleapis.com/v1/currentConditions:lookup?key=API_KEY

Übergeben Sie der Anfrage einen JSON-Text, in dem der Speicherort definiert ist.

Hinweis: Für alle Anwendungen der Luftqualitäts-API ist eine Authentifizierung erforderlich. Weitere Informationen zu Anmeldedaten für die Authentifizierung

SSL/TLS-Zugriff

HTTPS ist für alle Google Maps Platform-Anfragen erforderlich, bei denen API-Schlüssel verwendet werden oder die Nutzer Daten. Anfragen über HTTP, die sensible Daten enthalten, werden möglicherweise abgelehnt.

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.

Achtung: Browser und/oder Dienste können Codieren Sie einen Anfrage-URI vor dem Senden als URL. Bei APIs, die die kryptografische Anfragesignatur verwenden, kann dies die Signatur möglicherweise ungültig machen, wenn die URL-Codierung die Anfrage nach dem Signieren ändert. Um dies zu vermeiden codieren Sie Ihren Abfragestring immer URL-codiert, bevor Sie den

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 5 6 7 8 9	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 unnötig belasten. Dieser Abschnitt enthält einige bewährte Methoden für Kunden der APIs. Folge ich Mit diesen Best Practices können Sie vermeiden, dass Ihre Anwendung wegen unbeabsichtigtem Missbrauch von die APIs.

Exponential Backoff

In seltenen Fällen kann beim Ausführen Ihrer Anfrage ein Fehler auftreten. Sie erhalten dann möglicherweise einen 4XX- oder 5XX-HTTP-Antwortcode oder die TCP-Verbindung bricht irgendwo zwischen Ihrem Client und dem Google-Server ab. Häufig lohnt es sich, die Anfrage zu wiederholen, Die Folgeanfrage kann erfolgreich sein, wenn die ursprüngliche Anfrage fehlgeschlagen ist. Es ist jedoch wichtig, nicht einfach wiederholt Anfragen an die Server von Google. Dieses Schleifenverhalten kann die Netzwerk zwischen Ihrem Client und Google, was für viele Parteien zu Problemen führt.

Ein besserer Ansatz ist es, wiederholte Versuche in immer größeren Abständen durchzuführen. Normalerweise wird die Verzögerung bei jedem Versuch um einen Multiplikator erhöht. Dieser Ansatz wird als exponentieller Backoff bezeichnet.

Nehmen wir als Beispiel eine Anwendung, die diese Anfrage an die Time Zone API:

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=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}")

Außerdem sollten Sie darauf achten, dass in der Aufrufabfolge der Anwendung kein Code zum Wiederholen vorhanden ist, der zu wiederholten Anfragen in schneller Folge führt.

Synchronisierte Anforderungen

Eine große Anzahl synchronisierter 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 dafür sorgen, dass API-Anfragen nicht zwischen Clients synchronisiert werden.

Angenommen, eine Anwendung zeigt die Zeit in der aktuellen Zeitzone an. Diese App wird wahrscheinlich einen Alarm im Client-Betriebssystem einstellen, um den Ruhemodus zu beenden den Beginn der Minute, damit die angezeigte Zeit aktualisiert werden kann. Die Anwendung darf im Rahmen der Verarbeitung, die mit dieser Benachrichtigung verknüpft ist, keine API-Aufrufe ausführen.

API-Aufrufe als Reaktion auf einen festgelegten Alarm sind schlecht, da die API-Aufrufe dann bis zum Anfang der Minute synchronisiert, sogar zwischen verschiedenen Geräten. gleichmäßig über den Zeitraum verteilt. Eine schlecht konzipierte Anwendung, die dies tut, führt zu einer Spitze zu Beginn jeder Minute auf das sechzigfache Normalniveau.

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 benötigten APIs auf und speichert die Ergebnisse. Wenn die Anzeige der Anwendung zu Beginn der Minute aktualisiert werden soll, verwendet sie die zuvor gespeicherten Ergebnisse zu erhalten, 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 das Display aktualisiert wird.

Neben dem Beginn der Minute sollten Sie nicht auch den Beginn einer Stunde und den Beginn eines jeden Tages um Mitternacht als Synchronisierungszeitpunkt auswählen.

Verarbeiten von Antworten

Hinweis: Da das genaue Format einzelner Antworten bei einer Webserviceanfrage nicht garantiert werden kann (einige Elemente fehlen möglicherweise oder befinden sich an mehreren Stellen), sollten Sie niemals davon ausgehen, dass das für eine bestimmte Antwort zurückgegebene Format für verschiedene Abfragen identisch ist. Stattdessen sollten Sie die Antwort verarbeiten und entsprechende Werte über Ausdrücke.

In diesem Abschnitt wird erklärt, wie Sie diese Werte dynamisch aus den Webdienstantworten extrahieren.

Die Google Maps-Webdienste liefern Antworten, die einfach verstehen, aber nicht gerade nutzungsfreundlich. Wenn Sie eine Abfrage durchführen, Daten anzuzeigen, möchten Sie wahrscheinlich einige spezifische Werte. Im Allgemeinen sollten Sie Antworten aus dem Web analysieren. und extrahieren nur die Werte, die Sie interessieren.

Welches Parsing-Schema Sie verwenden, hängt davon ab, ob Sie im JSON-Format ausgegeben. JSON-Antworten, die bereits in Form von JavaScript-Objekte, können in JavaScript selbst verarbeitet werden auf der Kundschaft.