Sprawdzone metody korzystania z usług internetowych interfejsu Map Tiles API

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

W tym przewodniku opisano kilka typowych praktyk przydatnych podczas konfigurowania żądań usługi internetowej i przetwarzania odpowiedzi usługi. Pełną dokumentację interfejsu Map Tiles 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ń danych z interfejsu API Map Google z usług zewnętrznych i używania tych danych w aplikacjach Map Google. Zgodnie z ograniczeniami licencji opisanymi w Warunkach korzystania z usługi Google Maps Platform te usługi są przeznaczone do używania w połączeniu z mapą.

Usługi internetowe interfejsów API Map Google używają żądań HTTP(S) do określonych adresów URL, przekazując parametry adresu URL lub dane POST w formacie JSON jako argumenty do usług. Zwykle te usługi zwracają dane w treści odpowiedzi w formacie JSON do przeanalizowania lub przetworzenia przez aplikację.

Przykładem żądania usługi internetowej jest żądanie metadanych Street View, które ma następującą formę:

https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&panoId=panoId

Uwaga: wszystkie aplikacje korzystające z interfejsu Map Tiles 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ą dane użytkownika. Żądania wysyłane przez HTTP, które zawierają dane wrażliwe, mogą zostać odrzucone.

Zasady korzystania z interfejsów API Google

Źle zaprojektowane klienty API mogą niepotrzebnie obciążać zarówno internet, jak i serwery Google. Ta sekcja zawiera sprawdzone metody dotyczące klientów interfejsów API. Stosowanie tych sprawdzonych metod może pomóc Ci uniknąć zablokowania aplikacji z powodu niezamierzonego nadużycia interfejsów API.

Wzrastający czas do ponowienia

W rzadkich przypadkach podczas obsługi żądania może wystąpić błąd. Możesz otrzymać kod odpowiedzi HTTP 4XX lub 5XX albo połączenie TCP może po prostu nie zostać nawiązane między klientem a serwerem Google. Często warto spróbować ponownie, ponieważ kolejne żądanie może się powieść, nawet jeśli pierwotne się nie udało. Ważne jest jednak, aby nie wysyłać żądań do serwerów Google w pętli. Takie zapętlenie może przeciążyć sieć między klientem a Google, co może powodować problemy dla wielu stron.

Lepszym rozwiązaniem jest ponawianie prób z coraz dłuższymi przerwami między nimi. Zwykle opóźnienie jest zwiększane o mnożnik przy każdej próbie. Takie podejście jest znane jako wzrastający czas do ponowienia.

Załóżmy na przykład, że aplikacja chce wysłać do interfejsu Time Zone API takie żądanie:

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

Poniższy przykład w języku Python pokazuje, jak wysłać żądanie z wykorzystaniem wzrastającego czasu 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}")

Uważaj też, aby w łańcuchu wywołań aplikacji nie było kodu ponownej próby, który prowadzi do powtarzania żądań w krótkich odstępach czasu.

Żądania zsynchronizowane

Duża liczba zsynchronizowanych żądań do interfejsów API Google może wyglądać jak rozproszony atak typu DoS (DDoS) na infrastrukturę Google i zostać odpowiednio potraktowana. Aby 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 czas w bieżącej strefie czasowej. Ta aplikacja prawdopodobnie ustawi alarm w systemie operacyjnym klienta, który wybudzi go na początku minuty, aby można było zaktualizować wyświetlany czas. Aplikacja nie powinna wykonywać żadnych wywołań interfejsu API w ramach przetwarzania związanego z tym alarmem.

Wykonywanie wywołań interfejsu API w odpowiedzi na stały alarm jest nieprawidłowe, ponieważ powoduje, że wywołania interfejsu API są synchronizowane z początkiem minuty, nawet między różnymi urządzeniami, zamiast być równomiernie rozłożone w czasie. Źle zaprojektowana aplikacja, która tak robi, na początku każdej minuty wygeneruje skok ruchu 60 razy większy niż normalnie.

Zamiast tego można ustawić drugi alarm na losowo wybraną godzinę. Gdy ten drugi alarm się uruchomi, aplikacja wywołuje wszystkie potrzebne interfejsy API i zapisuje wyniki. Gdy aplikacja chce zaktualizować wyświetlane informacje na początku minuty, używa wcześniej zapisanych wyników, zamiast ponownie wywoływać interfejs API. Dzięki temu podejściu wywołania interfejsu API są rozłożone równomiernie w czasie. Ponadto wywołania interfejsu API nie opóźniają renderowania podczas aktualizowania wyświetlacza.

Oprócz początku minuty innymi typowymi momentami synchronizacji, których nie należy wybierać, są początek godziny i północ na początku każdego dnia.

Przetwarzanie odpowiedzi

W tej sekcji dowiesz się, jak dynamicznie wyodrębniać te wartości z odpowiedzi usługi internetowej.

Usługi internetowe Map Google dostarczają odpowiedzi, które są łatwe do zrozumienia, ale nie są zbyt przyjazne dla użytkownika. Podczas wykonywania zapytania zamiast wyświetlać zbiór danych, prawdopodobnie chcesz wyodrębnić kilka konkretnych wartości. Zazwyczaj będziesz analizować odpowiedzi z usługi internetowej i wyodrębniać tylko te wartości, które Cię interesują.

Używany schemat analizy zależy od tego, czy zwracasz dane wyjściowe w formacie JSON. Odpowiedzi JSON, które są już w postaci obiektów w JavaScripcie, mogą być przetwarzane w JavaScripcie na kliencie.