Usługi internetowe Google Maps Platform to zbiór interfejsów HTTP do usług Google, które udostępniają dane geograficzne dla aplikacji mapowych.
W tym przewodniku opisano kilka typowych metod, które są przydatne podczas konfigurowania żądań usługi internetowej i przetwarzania odpowiedzi usługi. Pełną dokumentację Roads 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ń do interfejsu API Map Google z usług zewnętrznych i używania tych danych w aplikacjach Map Google. Usługi te zostały zaprojektowane do użytku w połączeniu z mapą zgodnie z ograniczeniami licencyjnymi zawartymi w Warunkach korzystania z Google Maps Platform.
Usługi internetowe interfejsów API Map Google używają żądań HTTP(S) do określonych adresów URL i przekazują do tych usług parametry adresu URL lub dane POST w formacie JSON. Zasadniczo te usługi zwracają dane w treści odpowiedzi w formacie JSON na potrzeby przeanalizowania lub przetworzenia przez aplikację.
Typowe żądanie usługi internetowej Roads API ma zwykle następujący format:
https://roads.googleapis.com/v1/snapToRoads?parameters&key=YOUR_API_KEY
gdzie snapToRoads wskazuje konkretną żądaną usługę. Inne usługi dotyczące dróg to nearestRoads i speedLimits.
Uwaga: wszystkie aplikacje interfejsu Roads API wymagają uwierzytelniania. Dowiedz się więcej o danych uwierzytelniających.
Dostęp przez SSL/TLS
Protokół HTTPS jest wymagany w przypadku wszystkich żądań Google Maps Platform, które korzystają z kluczy interfejsu API lub zawierają dane użytkowników. Żądania przesł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 nie jest to słuszne. Na przykład adres URL wpisany w pasku adresu w przeglądarce może zawierać znaki specjalne (np."上海+中國"). Przed przesłaniem przeglądarka musi je wewnętrznie przetłumaczyć na inne kodowanie.
Na podstawie tego samego tokena każdy kod generujący lub akceptujący dane wejściowe w formacie UTF-8 może traktować adresy URL ze znakami UTF-8 jako „prawidłowe”, ale przed wysłaniem ich na serwer WWW musiałby je przetłumaczyć.
Ten proces nazywa się
kodowaniem adresów URL lub kodowaniem procentowym.
Znaki specjalne
Musimy tłumaczyć znaki specjalne, ponieważ wszystkie adresy URL muszą być zgodne ze składnią określoną w specyfikacji identyfikatora zasobów (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, które mogą być używane jako znaki kontrolne w adresach URL. W tej tabeli podsumowano te znaki:
| Ustaw | znaków | Wykorzystanie adresów 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 s 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 | Ciągi tekstowe, użycie schematu (http), port (8080) itp. |
| Niezarezerwowane | – _ . ~ | Ciągi tekstowe |
| Zarezerwowano | ! * ' ( ) ; : @ & = + $ , / ? % [ ] | Znaki kontrolne i ciągi tekstowe |
Podczas tworzenia prawidłowego adresu URL musisz się upewnić, że zawiera on tylko znaki widoczne w tabeli Podsumowanie prawidłowych znaków adresu URL. Stworzenie adresu URL tak, aby użyć tego zestawu znaków, zwykle prowadzi do 2 problemów: pominięcia i zastąpienia:
- Znaki, które chcesz obsługiwać, znajdują się poza powyższym zestawem. Na przykład znaki w językach obcych, takich jak
上海+中國, muszą być zakodowane przy użyciu powyższych znaków. Zgodnie z popularną konwencją spacje (które nie są dozwolone w adresach URL) są często oznaczane również znakiem plusa'+'. - W powyższym zestawie znaków występują znaki zarezerwowane, ale muszą być używane dosłownie.
Na przykład znak
?jest używany w adresach URL do wskazywania początku ciągu zapytania. Jeśli chcesz użyć ciągu „?” i wiersza Mysterions, musisz zakodować znak'?'.
Wszystkie znaki przeznaczone do kodowania URL są kodowane za pomocą znaku '%' i dwuznakowej wartości szesnastkowej odpowiadającej ich znakowi UTF-8. Na przykład tekst 上海+中國 w UTF-8 będzie zakodowany na potrzeby adresu URL jako %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B. Ciąg znaków ? and the Mysterians będzie zakodowany na potrzeby adresu URL jako %3F+and+the+Mysterians lub %3F%20and%20the%20Mysterians.
Typowe znaki wymagające kodowania
Oto kilka typowych znaków, które muszą być zakodowane:
| Niebezpieczny znak | Zakodowana wartość |
|---|---|
| Spacja | %20 |
| ” | %22 |
| < | %3C |
| > | %3E |
| # | %23 |
| % | %25 |
| | | %7C |
Konwertowanie adresu URL uzyskanego z danych wejściowych użytkownika jest czasem trudne. Na przykład użytkownik może wpisać adres „ul. Główna i Piąta”. Adres URL zasadniczo powinien składać się z części, traktując wszystkie dane wejściowe użytkownika jako znaki literackie.
Dodatkowo adresy URL w usługach internetowych Google Maps Platform i statycznych internetowych interfejsach API mogą mieć maksymalnie 16 384 znaki. W przypadku większości usług ten limit znaków rzadko jest zbliżany do osiągnięcia tego limitu. Pamiętaj jednak, że niektóre usługi mają kilka parametrów, które mogą powodować długie adresy URL.
grzecznościowe korzystanie z interfejsów API Google,
Źle zaprojektowane klienty interfejsu API mogą powodować nadmierne obciążenie zarówno na internecie, jak i na serwerach Google. Ta sekcja zawiera kilka sprawdzonych metod dla klientów interfejsów API. Te sprawdzone metody pomogą Ci uniknąć zablokowania aplikacji z powodu nieumyślnego nadużywania interfejsów API.
Exponential Backoff
W rzadkich przypadkach podczas przetwarzania żądania może coś pójść nie tak. Może się zdarzyć, że otrzymasz kod odpowiedzi HTTP 4XX lub 5XX albo połączenie TCP między Twoim klientem a serwerem Google nie powiedzie się. Często warto spróbować ponownie wysłać żądanie, bo kolejne mogą okazać się skuteczne, gdy pierwotna próba się nie powiedzie. Ważne jest jednak, aby nie zapętlać powtarzających się żądań do serwerów Google. Takie zapętlenie może spowodować przeciążenie sieci między Twoim klientem a Google, powodując problemy u wielu stron.
Lepszym rozwiązaniem jest ponawianie próby przy rosnących opóźnieniach między próbami. Zazwyczaj opóźnienie jest zwiększane przez mnożnik przy każdej próbie. Jest to tzw. wykładniczy czas ponowienia.
Przyjrzyjmy się na przykład aplikacji, 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×tamp=1331161200&key=YOUR_API_KEY
Poniższy przykład w Pythonie pokazuje, jak utworzyć żądanie z wykładniczym ponawianiem:
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}")
Zwróć też uwagę na to, że w łańcuchu wywołań aplikacji nie może znajdować się wyżej kod ponawiania, który prowadzi do powtarzających się żądań w krótkich odstępach czasu.
Zsynchronizowane żądania
Duża liczba zsynchronizowanych żądań wysyłanych do interfejsów API Google może przypominać atak DDoS na infrastrukturę Google i być odpowiednio traktowany. Aby tego uniknąć, sprawdź, czy żą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 w systemie operacyjnym klienta alarm, który będzie ją wybudzać na początku minuty, aby można było zaktualizować wyświetlany czas. Podczas przetwarzania powiązanego z alarmem aplikacja nie powinna wykonywać żadnych wywołań interfejsu API.
Wywołania interfejsu API w odpowiedzi na ustalony alarm są błędne, ponieważ powodują synchronizację wywołań interfejsu API na początku minuty, nawet między różnymi urządzeniami, a nie równomiernie rozłożone w czasie. Źle zaprojektowana aplikacja, która robi to w taki sposób, spowoduje wzrost natężenia ruchu przy 60-krotnie normalnych poziomach ruchu na początku każdej minuty.
Drugim dobrym rozwiązaniem jest ustawienie w drugim alarmu na dowolną godzinę. Po uruchomieniu tego drugiego alarmu aplikacja wywołuje potrzebne interfejsy API i zapisuje wyniki. Gdy aplikacja chce zaktualizować widok na początku minuty, korzysta z zapisanych wcześniej wyników, zamiast ponownie wywoływać interfejs API. Przy tym podejściu wywołania interfejsu API są równomiernie rozkładane w czasie. Co więcej, wywołania interfejsu API nie opóźniają renderowania podczas aktualizowania wyświetlacza.
Pamiętaj, że oprócz początku minuty nie ustawiaj kierowania na początek godziny, a na początek każdego dnia o północy.
Przetwarzanie odpowiedzi
W tej sekcji omówiono sposób dynamicznego wyodrębniania tych wartości z odpowiedzi usługi internetowej.
Usługi internetowe Map Google udzielają odpowiedzi, które są łatwe do zrozumienia, ale nie są zrozumiałe dla użytkownika. Zamiast wyświetlać zbiór danych podczas wykonywania zapytania, warto wyodrębnić kilka określonych wartości. Warto przeanalizować odpowiedzi z usługi internetowej i wyodrębnić tylko te wartości, które Cię interesują.
Schemat analizy, którego użyjesz, zależy od tego, czy dane wyjściowe są zwracane w formacie JSON. Odpowiedzi JSON, które mają już formę obiektów JavaScript, mogą być przetwarzane w obrębie JavaScriptu po stronie klienta.