Sprawdzone metody korzystania z usług internetowych interfejsu Geolocation 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.

W tym przewodniku opisano kilka typowych metod przydatnych do konfigurowania żądań usługi internetowej i przetwarzania odpowiedzi usługi. Pełną dokumentację interfejsu Geolocation API znajdziesz w przewodniku dla programistó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 używają żądań HTTP(S) do określonych adresów URL, przekazując parametry adresu URL lub dane w formacie 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ę.

Zapytania o lokalizację są wysyłane za pomocą metody POST pod ten adres URL:

https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY

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

Uprzejme korzystanie z interfejsów API Google

Źle zaprojektowane aplikacje korzystające z interfejsu API mogą generować niepotrzebnie duże obciążenie zarówno w internecie, jak i na serwerach 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.

Exponential Backoff

W rzadkich przypadkach może wystąpić błąd podczas obsługi żądania. Możesz wtedy otrzymać kod odpowiedzi HTTP 4xx lub 5xx albo połączenie TCP może po prostu nie działać 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 wysyłać wielokrotnie żądań 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ż 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

Ten przykład w języku Python pokazuje, jak wysłać żądanie z wykładniczym zmniejszaniem częstotliwości:

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.

Synchronizowane żą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.

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 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 niekorzystne, ponieważ powoduje, że wywołania interfejsu API są synchronizowane z początkiem minuty, nawet na różnych urządzeniach, zamiast być rozłożone równomiernie 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 się włączy, aplikacja wywołuje wszystkie potrzebne interfejsy API i zapisują wyniki. Gdy aplikacja chce zaktualizować wyświetlanie na początku minuty, korzysta z 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 dobierać, to początek godziny oraz początek każdego dnia o północy.

Przetwarzanie odpowiedzi

W tej sekcji omawiamy wyodrębnianie tych wartości dynamicznie z odpowiedzi usług internetowych.

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 są już w formie obiektów JavaScriptu, więc mogą być przetwarzane w samym języku JavaScript na kliencie.