Sprawdzone metody korzystania z usług internetowych Pollen API

Usługi internetowe Google Maps Platform to zbiór interfejsów HTTP do usług Google, które dostarczają danych geograficznych do Twoich aplikacji mapowych.

Ten przewodnik opisuje kilka typowych metod przydatnych do konfigurowania żądań usługi internetowej i przetwarzania odpowiedzi usługi. Pełną dokumentację interfejsu Pollen API znajdziesz w przewodniku dla deweloperów.

Co to jest usługa internetowa?

Usługi internetowe Google Maps Platform to interfejs do wysyłania żądań o dane interfejsu API Map do usług zewnętrznych i używania tych danych w aplikacji 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 i przekazują parametry adresów URL lub dane POST w formacie JSON jako argumenty do usług. Zwykle te usługi zwracają dane w ciele odpowiedzi w formacie JSON do analizy lub przetwarzania przez aplikację.

Ten przykład pokazuje adres URL żądania REST GET kierowanego do metody forecast:lookup:

https://pollen.googleapis.com/v1/forecast:lookup?&key=API_KEY

Uwaga: wszystkie aplikacje korzystające z interfejsu Pollen API wymagają uwierzytelnienia. Dowiedz się więcej o danych uwierzytelniających.

Dostęp SSL/TLS

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

Tworzenie prawidłowego adresu URL

Może Ci się wydawać, że „prawidłowy” adres URL jest oczywisty, ale to nieprawda. Adres URL wpisany na 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. Z tego samego powodu każdy kod, który generuje lub akceptuje dane wejściowe w formacie UTF-8, może traktować adresy URL zawierające znaki w tym formacie jako „prawidłowe”, ale musi też przetłumaczyć te znaki przed wysłaniem ich na serwer WWW. Ten proces nazywa się kodowaniem URL-a lub kodowaniem procentowym.

Uwaga: przeglądarki lub usługi mogą automatycznie zakodować identyfikator URI żądania w formacie URL przed wysłaniem. W przypadku interfejsów API, które korzystają z podpisywania żądań kryptograficznych, może to potencjalnie unieważnić podpis, jeśli kodowanie URL zmieni żądanie po podpisaniu. Aby uniknąć tego problemu, zawsze koduj ciąg zapytania przed podpisaniem żądania.

Znaki specjalne

Musimy przetłumaczyć znaki specjalne, ponieważ wszystkie adresy URL muszą być zgodne z składnią określoną w specyfikacji identyfikatora 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
Znaki alfanumeryczne	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	Ciągi tekstowe, wykorzystanie schematu (http), port (8080) itp.
Niezarezerwowane	- _ . ~	Teksty
Zarezerwowane	! * ' ( ) ; : @ & = + $ , / ? % # [ ]	znaki sterujące lub ciągi tekstowe;

Podczas tworzenia prawidłowego adresu URL musisz się upewnić, że zawiera on tylko znaki podane w tabeli. Dostosowanie adresu URL do tego zestawu znaków prowadzi zazwyczaj do 2 problemów: pominięcia i zastąpienia:

• Znaki, które chcesz obsługiwać, znajdują się poza zestawem znaków wymienionym powyżej. Na przykład znaki obcych języków, takie jak 上海+中國, muszą być zakodowane za pomocą znaków wymienionych powyżej. Zgodnie z popularną konwencją spacje (niedozwolone w adresach URL) często są przedstawiane za pomocą znaku plusa '+'.
• Znaki z powyższego zestawu są znakami zarezerwowanymi, ale muszą być używane dosłownie. Na przykład w adresach URL znak ? wskazuje początek ciągu zapytania. Jeśli chcesz użyć ciągu „? and the Mysterions”, musisz zakodować znak '?'.

Wszystkie znaki do kodowania URL są kodowane za pomocą znaku '%' i dwuznakowej wartości szesnastkowej odpowiadającej ich znakowi UTF-8. Na przykład kod 上海+中國 w formacie UTF-8 byłby zakodowany w adresie URL jako %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B. Ciąg tekstowy ? and the Mysterians zostanie zakodowany w formacie URL jako %3F+and+the+Mysterians lub %3F%20and%20the%20Mysterians.

Typowe znaki wymagające kodowania

Oto kilka przykładów znaków, które muszą być zakodowane:

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

Konwertowanie adresu URL otrzymanego od użytkownika może być czasami trudne. Użytkownik może na przykład wpisać adres „5th&Main St.”. Zasadniczo adres URL powinien być budowany z pojedynczych części, a wszystkie dane wejściowe użytkownika powinny być traktowane jako znaki dosłowne.

Dodatkowo w przypadku wszystkich usług internetowych i interfejsów API Google Maps Platform ograniczenie długości adresów URL wynosi 16 384 znaki. W przypadku większości usług ten limit znaków jest rzadko osiągany. Pamiętaj jednak, że niektóre usługi mają kilka parametrów, które mogą powodować powstawanie długich adresów URL.

Uprzejme korzystanie z interfejsów API Google

Źle zaprojektowane klienty interfejsu API mogą zwiększać obciążenie zarówno internetu, jak i serwerów Google. Ta sekcja zawiera sprawdzone metody dla klientów interfejsów API. Postępując zgodnie z tymi sprawdzonymi metodami, unikniesz zablokowania aplikacji z powodu niezamierzonego nadużywania interfejsów API.

Exponential Backoff

W rzadkich przypadkach może wystąpić błąd podczas obsługi Twojego żądania. Możesz otrzymać kod odpowiedzi HTTP 4xx lub 5xx albo połączenie TCP może po prostu nie zostać nawiązane gdzieś między klientem a serwerem Google. 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 stosować pętli, która wielokrotnie wysyła żądania do serwerów Google. Takie działanie może spowodować przeciążenie sieci między klientem a Google, co może powodować problemy dla wielu stron.

Lepszym podejściem jest ponowne próbowanie z rosnącymi opóźnieniami między próbami. Zwykle opóźnienie jest zwiększane o wielokrotnik przy każdej próbie. Jest to podejście znane jako wzrastający czas do ponowienia.

Rozważmy na przykład aplikację, która chce wysłać to żądanie do interfejsu 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 Python 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 synchronizowanych żądań do interfejsów API Google może wyglądać jak rozproszony atak typu DoS na infrastrukturę Google i być traktowana odpowiednio. Aby tego uniknąć, musisz zadbać o to, aby żądania interfejsu API nie były synchronizowane między klientami.

Rozważ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 nie powinna wywoływać żadnych interfejsów API w ramach przetwarzania związanego z tym alarmem.

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

Jednym z dobrych rozwiązań jest ustawienie drugiego alarmu na losowo wybraną godzinę. Gdy ten drugi alarm się włączy, aplikacja wywołuje wszystkie potrzebne interfejsy API i zapisują wyniki. Gdy aplikacja chce zaktualizować wyświetlacz na początku minuty, używa wcześniej zapisanych wyników, zamiast ponownie wywoływać interfejs API. W tym przypadku wywołania interfejsu API są rozłożone równomiernie w czasie. Co więcej, wywołania interfejsu API nie opóźniają renderowania podczas aktualizowania wyświetlacza.

Oprócz początku minuty inne typowe momenty synchronizacji, których nie należy docelowo wybierać, to początek godziny oraz początek każdego dnia o północy.

Przetwarzanie odpowiedzi

Uwaga: dokładny format poszczególnych odpowiedzi na żądanie usługi sieci Web nie jest gwarantowany (niektóre elementy mogą być nieobecne lub znajdować się w kilku miejscach), dlatego nie należy zakładać, że format zwrócony dla danej odpowiedzi będzie taki sam w przypadku różnych zapytań. Zamiast tego należy przetworzyć odpowiedź i wybrać 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 dostarczają odpowiedzi, które są łatwe do zrozumienia, ale niekoniecznie przyjazne użytkownikowi. Podczas wykonywania zapytania zamiast wyświetlać zbiór danych prawdopodobnie chcesz wyodrębnić kilka konkretnych wartości. Zazwyczaj będziesz chciał przeanalizować odpowiedzi z usługi internetowej i wyodrębnić tylko te wartości, które Cię interesują.

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