Sprawdzone metody korzystania z usług internetowych interfejsu Air Quality API

Usługi internetowe Google Maps Platform to zbiór interfejsów HTTP Google usługi udostępniające dane geograficzne na potrzeby aplikacji z mapami.

W tym przewodniku opisujemy kilka typowych sposobów konfigurowania usługa sieciowa żądań i przetwarzania odpowiedzi usługi. Zapoznaj się z przewodnikiem dla programistów. , aby zapoznać się z pełną dokumentacją interfejsu Air Quality API.

Co to jest usługa internetowa?

Usługi internetowe Google Maps Platform to interfejs do żądania danych interfejsu API Map Google z usług zewnętrznych i wykorzystywanie danych w aplikacjach Mapy. Te usługi są przeznaczone do użytku w połączeniu z mapą zgodnie z ograniczeniami licencji określonymi w Warunkach korzystania z usługi Google Maps Platform.

Usługi internetowe interfejsów API Map Google używają żądań HTTP(S) kierowanych do konkretnych adresów URL, przekazują parametry adresów URL lub Dane POST w formacie JSON jako argumenty dla usług. Usługi te zwracają dane w treść odpowiedzi w formacie JSON do analizy lub przetwarzania przez aplikację.

Poproś o aktualną jakość powietrza według godzin za pomocą: currentConditions przez wysłanie żądania HTTP POST do:

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

Przekaż treści JSON. do żądania określającego lokalizację.

Uwaga: wszystkie aplikacje interfejsu Air Quality API wymagają uwierzytelniania. Dowiedz się więcej o danych uwierzytelniających.

Dostęp SSL/TLS

Protokół HTTPS jest wymagany w przypadku wszystkich żądań Google Maps Platform, które używają kluczy interfejsu API lub zawierają użytkowników i skalowalnych danych. Żądania przesyłane za pomocą protokołu HTTP, które zawierają dane wrażliwe, mogą zostać odrzucone.

Tworzenie prawidłowego adresu URL

Możesz sądzić, że „prawidłowy” adres URL jest oczywisty, ale tak nie jest. Adres URL wpisany w pasku adresu w przeglądarce może na przykład zawierać znaki specjalne (np. "上海+中國"). Przed przesłaniem przeglądarka musi przetłumaczyć te znaki na inne kodowanie. Zgodnie z tym samym tokenem każdy kod, który generuje lub akceptuje dane wejściowe UTF-8, może traktować adresy URL ze znakami UTF-8 jako „prawidłowe”, ale wymagają tego również przetłumaczyć te znaki przed wysłaniem ich na serwer WWW. Ten proces nazywa się kodowaniem URL-a lub kodowaniem procentowym.

Uwaga: przeglądarki i/lub usługi mogą automatycznie Przed wysłaniem zakoduj identyfikator URI żądania w adresie URL. W interfejsach API, które używają podpisywania żądań kryptograficznych, może to potencjalnie unieważnić podpis, jeśli kodowanie URL zmienia żądanie po podpisaniu. Aby unikać ten problem zawsze koduj ciąg zapytania w adresie URL przed podpisaniem tagu o połączenie.

Znaki specjalne

Znaki specjalne trzeba przetłumaczyć, Wszystkie adresy URL muszą spełniać składnię określoną w tagu Strój Specyfikacja identyfikatora zasobu (URI). Oznacza to, że adresy URL mogą zawierać tylko specjalny podzbiór znaków ASCII: znane symbole alfanumeryczne oraz niektóre znaki zarezerwowane do użycia jako znaki kontrolne w adresach URL. W tej tabeli znajdziesz te znaki:

Do startu	znaków	Użycie adresu URL
Alfanumeryczne	a b c d e f g h i j k l m n o p q r s t u v 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	Ciągi tekstowe, wykorzystanie schematu (http), port (8080) itp.
Niezarezerwowane	- _ . ~	Teksty
Zarezerwowane	! * ( ) ; : @ & = + $ , / ? % # [ ]	Znaki kontrolne lub ciągi tekstowe

Tworząc prawidłowy adres URL, należy się upewnić, że zawiera on tylko znaki podane tabeli. Zgodność adresu URL w celu ogólnego korzystania z tego zestawu znaków prowadzi do dwóch problemów: pierwszego pominięcia i zastąpienia:

• Znaki, którymi chcesz się zajmować, znajdują się poza powyżej zestawu. Na przykład znaki w obcych językach takie jak 上海+中國, muszą być zakodowane za pomocą funkcji powyżej znaków. Zgodnie z powszechną konwencją pokoje (czyli niedozwolonych w adresach URL) są często przedstawiane za pomocą znaku plusa '+' znak.
• Znaki w powyższym zestawie są dostępne jako znaki zarezerwowane. ale muszą być używane dosłownie. Na przykład ? jest używany w adresach URL do oznaczania początku ciągu zapytania, jeśli chcesz użyć „? i Tajemnice” musisz zakodować '?' znak.

Wszystkie znaki do kodowania URL są zakodowane używając znaku '%' i dwuznakowego kodu szesnastkowego odpowiadającą jej znakowi UTF-8. Przykład: Kod 上海+中國 w UTF-8 byłby zakodowany jako URL %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B ciąg ? and the Mysterians byłby zakodowany w adresie URL jako %3F+and+the+Mysterians lub %3F%20and%20the%20Mysterians.

Typowe znaki, które wymagają kodowania

Oto kilka typowych znaków, które muszą być zakodowane:

Niebezpieczna postać	Zakodowana wartość
Spacja	%20
”	%22
<	%3C
>	%3E
#	%23
%	%25
|	%7C

Konwersja adresu URL otrzymanego z danych wejściowych użytkownika jest czasami podchwytliwe. Na przykład użytkownik może wprowadzić adres jako „ul. Główna” Ogólnie rzecz biorąc, adres URL powinieneś tworzyć z pojedynczych części, traktując każdy wpis użytkownika jako znaki dosłowne.

Oprócz tego adresy URL we wszystkich usługach internetowych Google Maps Platform mogą mieć maksymalnie 16 384 znaki i statycznych sieciowych interfejsów API. W większości usług limit znaków będzie rzadko osiągany. Pamiętaj jednak: pamiętaj, że niektóre usługi mają kilka parametrów, które mogą powodować długie adresy URL.

Kontrolowane korzystanie z interfejsów API Google

Źle zaprojektowane klienty interfejsu API mogą powodować większe obciążenie zarówno w internecie, jak i w internecie Serwery Google. Ta sekcja zawiera kilka sprawdzonych metod dla klientów korzystających z interfejsów API. Obserwujesz te sprawdzone metody pomogą Ci uniknąć zablokowania aplikacji z powodu przypadkowego naruszenia dla interfejsów API.

Exponential Backoff

W rzadkich przypadkach może coś pójść nie tak podczas wyświetlania żądania. możesz otrzymać kod HTTP 4XX lub 5XX kodu odpowiedzi lub połączenie TCP może po prostu ulec awarii gdzieś pomiędzy klientem a serwera. Często warto ponownie przesłać prośbę, ponieważ może się udać, gdy pierwotna prośba zakończyła się niepowodzeniem. Ważne jest jednak, aby nie po prostu wielokrotnego wysyłania żądań do serwerów Google. Takie zapętlenie może spowodować przeciążenie między klientem a Google, co powoduje problemy u wielu stron.

Lepszym podejściem jest ponowne próbowanie z rosnącymi opóźnieniami między próbami. Zwykle jest zwiększane przez mnożnik przy każdej próbie. Ta metoda nazywa się Wykładniczy czas ponowienia.

Weźmy na przykład aplikację, która chce wysłać to żądanie do Time Zone API:

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1331161200&key=YOUR_API_KEY

Poniższy przykładowy kod w Pythonie pokazuje, jak wysłać żądanie ze wzrastającym czasem do ponowienia:

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}")

Upewnij się też, że w łańcuchu wywołań aplikacji nie ma kodu prób ponownego połączenia, który powoduje powtarzające się żądania w szybkiej kolejności.

Zsynchronizowane żądania

Duża liczba zsynchronizowanych żądań do interfejsów API Google może wyglądać jak rozproszone Atak typu Denial of Service (DDoS) na infrastrukturę Google i odpowiednio traktowany. Do tego uniknąć, upewnij się, że żądania do interfejsu API nie są synchronizowane między klientami.

Weźmy na przykład aplikację, która wyświetla godzinę w bieżącej strefie czasowej. Aplikacja prawdopodobnie ustawi alarm w systemie operacyjnym klienta, który będzie ją budził na początku minuty, aby zaktualizować wyświetlany czas. Aplikacja powinna nie może wykonywać żadnych wywołań interfejsu API w ramach przetwarzania związanego z tym alarmem.

Wykonywanie wywołań interfejsu API w odpowiedzi na naprawiony alarm jest niewłaściwe, ponieważ powoduje jest zsynchronizowany z początkiem minuty, nawet między różnymi urządzeniami, a nie równomiernie rozłożony w czasie. Źle zaprojektowana aplikacja spowoduje wzrost natężenia ruchu o 60 razy większy niż normalnie na początku każdej minuty.

Zamiast tego można ustawić drugi alarm na losową godzinę. Gdy ten drugi alarm uruchomi się, aplikacja wywoła wszelkie potrzebne interfejsy API i zapisze wyników. Gdy aplikacja chce zaktualizować wyświetlacz na początku minuty, używa funkcji zapisane wcześniej wyniki, zamiast ponownie wywoływać interfejs API. Przy tej metodzie wywołania interfejsu API są równomiernie rozłożone na przestrzeni czasu. Co więcej, wywołania interfejsu API nie opóźniają renderowania, gdy wyświetlacz jest są aktualizowane.

Oprócz początku minuty warto też zachować ostrożność. nie są ustawione na początek godziny i początek każdego dnia o północy.

Przetwarzanie odpowiedzi

Uwaga: jako dokładny format poszczególnych odpowiedzi ze znakiem żądania usługi sieciowej nie są gwarantowane (może brakować niektórych elementów lub mogą znajdować się one w wielu lokalizacjach), nie zakładaj, że format zwrócony w przypadku danej odpowiedzi będzie taki sam różne zapytania. Zamiast tego przetwórz odpowiedź i wybierz odpowiednie wartości za pomocą wyrażeń.

W tej sekcji omówiono sposób dynamicznego wyodrębniania tych wartości z odpowiedzi usługi sieciowej.

Usługi internetowe Map Google udzielają odpowiedzi, które są łatwe do ale też nie są łatwe w użyciu. Podczas wykonywania zapytania zamiast wyświetlać zbiór danych prawdopodobnie chcesz wyodrębnić kilka konkretnych wartości. Odpowiedzi z internetu powinny być analizowane i wyodrębnij tylko te wartości, które Cię interesują.

Schemat analizy zależy od tego, czy zwracasz dane wyjściowe w formacie JSON. Odpowiedzi JSON, które są już w formie obiektów JavaScript, mogą być przetwarzane w samym języku JavaScript na kliencie.