Sprawdzone metody korzystania z usług internetowych interfejsu Roads API

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

W tym przewodniku opisano kilka typowych metod przydatnych podczas konfigurowania żądań usług internetowych i przetwarzania odpowiedzi usługi. Pełną dokumentację interfejsu Roads API znajdziesz w przewodniku dla programistów.

Co to jest usługa sieciowa?

Usługi internetowe Google Maps Platform to interfejs umożliwiający zgłaszanie żądań danych interfejsu API Map Google z usług zewnętrznych i korzystanie z tych danych w aplikacjach Map. Usługi te są przeznaczone do używania w połączeniu z mapą, zgodnie z ograniczeniami licencji zawartymi w Warunkach korzystania z 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. Ogólnie rzecz biorąc, usługi te zwracają dane w treści odpowiedzi w postaci kodu JSON na potrzeby analizy lub przetwarzania przez aplikację.

Typowe żądanie usługi sieciowej do interfejsu Roads API ma zwykle taką postać:

https://roads.googleapis.com/v1/snapToRoads?parameters&key=YOUR_API_KEY

gdzie snapToRoads oznacza żądaną usługę. Inne usługi związane z drogami to nearestRoads i speedLimits.

Uwaga: wszystkie aplikacje interfejsu Roads API wymagają uwierzytelniania. 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. Na przykład adres URL wpisany w pasku adresu w przeglądarce może zawierać znaki specjalne (np."上海+中國"). Przed transmisją przeglądarka musi wewnętrznie 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 musiałby również je przetłumaczyć przed wysłaniem ich na serwer WWW. Ten proces nazywamy kodowaniem adresów URL, czyli kodowaniem procentowym.

Znaki specjalne

Musimy tłumaczyć znaki specjalne, ponieważ wszystkie adresy URL muszą spełniać wymagania opisane w specyfikacji identyfikatora URI (Uniform Resource Identifier). Oznacza to, że adresy URL mogą zawierać tylko specjalny podzbiór znaków ASCII: znane symbole alfanumeryczne i niektóre znaki zarezerwowane do wykorzystania jako znaki kontrolne w adresach URL. Tabela zawiera podsumowanie tych znaków:

Ustaw	postacie	Użycie adresu URL
Alfanumeryczne	a b c d e f g h i j k l m	Ciągi tekstowe, wykorzystanie schematu (http), port (8080) itp.
Niezarezerwowane	- _ . ~	Ciągi tekstowe
Zarezerwowano	! * ' ( ) ; : @ & = + $ , / ? % # [ ]	Znaki kontrolne lub ciągi tekstowe

Podczas tworzenia prawidłowego adresu URL musisz upewnić się, że zawiera on tylko znaki podane w tabeli. Skonfigurowanie adresu URL tak, aby używał takiego zestawu znaków, zwykle skutkuje 2 problemami: pominięciem i zastąpieniem:

• Znaki, które chcesz obsługiwać, znajdują się poza powyższym zestawem. Na przykład znaki w innych językach, takich jak 上海+中國, muszą być zakodowane przy użyciu podanych wyżej znaków. Zgodnie z popularną konwencją spacje (niedozwolone w adresach URL) często są przedstawiane za pomocą znaku plusa '+'.
• Znaki w powyższym zestawie występują jako znaki zastrzeżone, ale muszą być używane dosłownie. Na przykład ? jest używany w adresach URL do wskazywania początku ciągu zapytania. Jeśli chcesz użyć ciągu znaków „?” i „tajemnic”, 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 ? 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ść
Miejsce	%20
”	%22
<	%3C
>	%3E
#	%23
%	%25
|	%7C

Konwersja adresu URL otrzymanego z danych wejściowych użytkownika bywa czasem skomplikowana. Użytkownik może na przykład wprowadzić adres „ul. Główna 5" Ogólnie adres URL należy tworzyć z części, a wszelkie dane wpisane przez użytkownika traktuj jak znaki.

Poza tym adresy URL we wszystkich usługach internetowych Google Maps Platform i statycznych internetowych interfejsach API mogą mieć maksymalnie 16 384 znaki. W większości usług limit znaków będzie 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.

Kontrolowane 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 kilka sprawdzonych metod dla klientów korzystających z 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 coś może pójść nie tak przy realizacji żądania, możesz otrzymać kod odpowiedzi HTTP 4XX lub 5XX albo połączenie TCP może po prostu ulec awarii gdzieś pomiędzy klientem a serwerem Google. Często warto ponawiać próbę, ponieważ kolejna prośba może się udać, gdy pierwotna prośba nie powiedzie się. Ważne jest jednak, aby nie zapętlać sobie wielu żądań wysyłanych do serwerów Google. Takie zapętlenie może spowodować przeciążenie sieci między klientem a Google, co może powodować problemy u wielu stron.

Lepszym sposobem jest ponowienie próby z coraz większymi opóźnieniami. Zazwyczaj opóźnienie jest zwiększane przez mnożnik przy każdej próbie. Jest to tzw. wykładniczy czas 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}")

Zadbaj też o to, by wyżej w łańcuchu wywołań aplikacji nie było kodu ponawiania prób, który prowadzi do powtarzających się żądań w krótkich odstępach czasu.

Zsynchronizowane żądania

Duża liczba zsynchronizowanych żądań do interfejsów API Google może wyglądać jak atak typu Distributed Denial of Service (DDoS) na infrastrukturę Google i jest odpowiednio traktowany. 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 godzinę w bieżącej strefie czasowej. Ta aplikacja prawdopodobnie ustawi alarm w systemie operacyjnym klienta, który aktywuje go na początku minuty, aby można było zaktualizować wyświetlaną godzinę. Podczas przetwarzania powiązanego z tym alarmem aplikacja nie powinna wykonywać żadnych wywołań interfejsu API.

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, która to robi, na początku każdej minuty wywoła skok ruchu na poziomie 60-krotnie większym niż normalne.

Dobrym rozwiązaniem jest ustawienie drugiego alarmu na losowo wybraną godzinę. Po uruchomieniu tego drugiego alarmu aplikacja wywołuje potrzebne interfejsy API i zapisuje wyniki. Gdy aplikacja chce zaktualizować wyświetlacz na początku minuty, używa wcześniej zapisanych wyników, zamiast ponownie wywoływać interfejs API. Dzięki temu wywołania interfejsu API są rozłożone równomiernie w czasie. Dodatkowo wywołania interfejsu API nie opóźniają renderowania podczas aktualizowania wyświetlacza.

Oprócz początku minuty należy też pamiętać, że synchronizacja nie przypada na początek godziny i początek każdego dnia o północy.

Przetwarzanie odpowiedzi

Uwaga: ponieważ dokładny format poszczególnych odpowiedzi z żądaniem usługi internetowej nie jest gwarantowany (może brakować niektórych elementów lub mogą znajdować się one w wielu lokalizacjach), nie należy zakładać, że format zwrócony dla danej odpowiedzi będzie taki sam w przypadku różnych zapytań. 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 zrozumienia, ale niezbyt przyjazne dla użytkownika. Podczas wykonywania zapytania zamiast wyświetlania zbioru danych prawdopodobnie zechcesz wyodrębnić kilka konkretnych wartości. Ogólnie zalecamy analizowanie odpowiedzi z usługi internetowej i wyodrębnienie tylko tych wartości, które Cię interesują.

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