Interfejsy API internetowej wersji Google Maps Platform to zbiór interfejsów HTTP do usług Google, których zadaniem jest generowanie obrazów, które można umieścić bezpośrednio na stronie internetowej.
Usługi internetowe Google Maps Platform to zbiór interfejsów HTTP dla usług Google, które udostępniają dane geograficzne aplikacjom z mapami.
W tym przewodniku opisano kilka typowych praktyk przydatnych przy konfigurowaniu żądań obrazów i usług internetowych oraz żądań odpowiedzi do usług. Pełną dokumentację interfejsu Street View Static API znajdziesz w przewodniku dla programistów.
Interfejs Street View Static API działa jak statyczny interfejs API, a usługa metadanych może być postrzegana jako usługa internetowa. Więcej informacji o usłudze metadanych znajdziesz w artykule o metadanych zdjęć Street View.Co to jest statyczny interfejs API?
Interfejsy API Map Google w wersji statycznej Google Maps Platform umożliwiają umieszczanie obrazów z Map Google na Twojej stronie internetowej bez JavaScriptu i dynamicznego wczytywania stron. Statyczne internetowe interfejsy API tworzą obraz na podstawie parametrów adresu URL wysyłanych przy użyciu standardowego żądania HTTPS.Typowe żądanie Street Static API ma na ogół taką formę:
https://www.googleapis.com/streetview/z/x/y?parameters
Co to jest usługa internetowa?
Usługi internetowe Google Maps Platform to interfejs, który służy do żądania danych interfejsu API Map Google z usług zewnętrznych i wykorzystywania danych z aplikacji Mapy. Usługi te są przeznaczone do użytku w połączeniu z mapą zgodnie z Ograniczeniami licencji w Warunkach korzystania z Google Maps Platform.
Usługi internetowe interfejsów API Map Google korzystają z żądań HTTP(S) do określonych adresów URL, przekazując parametry URL lub dane POST w formacie JSON jako argumenty kierowane do usług. Zasadniczo usługi te zwracają dane w treści odpowiedzi w formacie JSON na potrzeby analizy lub przetwarzania przez aplikację.
Żądanie statycznego interfejsu API Street View ma taką formę:https://maps.googleapis.com/maps/api/streetview/parameters
Uwaga: wszystkie aplikacje statyczne Street View 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 wykorzystujących klucze interfejsu API lub zawierających dane użytkowników. Żądania wysyłane przez HTTP zawierające dane wrażliwe mogą być odrzucane.
Tworzenie prawidłowego adresu URL
Może Ci się wydawać, że „prawidłowe” adresy URL są zrozumiałe, ale w rzeczywistości tak nie jest. Na przykład adres URL wpisany w pasku adresu w przeglądarce może zawierać znaki specjalne (np."上海+中國"). Przeglądarka musi przed przesłaniem przesłać te znaki do innego kodowania.
Na podstawie tego samego tokena 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 musi też tłumaczyć te znaki, zanim zostaną wysłane na serwer WWW.
Taki proces nazywa się
kodowaniem adresów URL lub kodowaniem procentowym.
Znaki specjalne
Musimy przetłumaczyć znaki specjalne, ponieważ wszystkie adresy URL muszą być zgodne ze składnią określoną w specyfikacji ujednoliconego identyfikatora zasobu (URI). Oznacza to, że adresy URL mogą zawierać tylko specjalny podzbiór znaków ASCII: znane symbole alfanumeryczne oraz niektóre zarezerwowane znaki, które mogą być używane jako znaki kontrolne w adresach URL. Ta tabela zawiera podsumowanie tych znaków:
| Ustaw | znaków | Użycie adresu URL |
|---|---|---|
| Znaki alfanumeryczne | a b c d e k g g h i j k l m n o p k r s k t n k 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 9 6 7 7 | Ciągi tekstowe, wykorzystanie schematu (http), port (8080) itd. |
| Niezarezerwowane | – _ . ~ | Ciągi tekstowe |
| Zarezerwowano | ! * ' ( ) ; : @ & = + $ , / ? % # [ ] | Kontrolowanie znaków i/lub ciągów tekstowych |
Podczas tworzenia prawidłowego adresu URL upewnij się, że zawiera on tylko te znaki podane w tabeli Podsumowanie prawidłowych znaków adresu URL. Użycie adresu URL w taki sposób, by używało tego zestawu znaków, prowadzi zwykle do 2 problemów: jednego pominięcia i jednego zamiennika:
- Znaki, które chcesz obsługiwać, nie są wymienione powyżej. Na przykład znaki w obcych językach, takie jak
上海+中國, muszą być kodowane przy użyciu powyższych znaków. Zgodnie z obowiązującą konwencją spacje (niedozwolone w adresach URL) są często przedstawiane za pomocą znaku plusa'+'. - Znaki w tych powyższych zestawach są zastrzeżone, ale należy ich używać dosłownie.
Na przykład w adresach URL jest używany znak
?wskazujący początek ciągu zapytania. Jeśli chcesz użyć ciągu „? i tajemnicy”, musisz zakodować znak'?'.
Wszystkie znaki zakodowane przy użyciu adresu URL są kodowane za pomocą znaku '%' i dwuznakowej wartości szesnastkowej odpowiadającej jej znakowi UTF-8. Na przykład 上海+中國 w kodowaniu UTF-8 będzie zakodowany jako URL w formacie %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B. Ciąg ? and the Mysterians zostanie zakodowany jako %3F+and+the+Mysterians lub %3F%20and%20the%20Mysterians.
Popularne znaki wymagające kodowania
Kilka typowych znaków, które należy zakodować:
| Niebezpieczny znak | Zakodowana wartość |
|---|---|
| Spacja | %20 |
| ” | %22 |
| < | %3C |
| > | %3E |
| # | %23 |
| % | %25 |
| | | %7C |
Konwersja adresu URL otrzymanego od użytkownika jest czasami skomplikowana. Na przykład użytkownik może wpisać adres jako „ul. Główna 5” Ogólnie należy tworzyć adres URL z jego części, traktując dane użytkowników jako dosłowne znaki.
Dodatkowo dla wszystkich usług internetowych Google Maps Platform i statycznych interfejsów API URL-e mogą mieć maksymalnie 8192 znaki. W przypadku większości usług limit znaków rzadko jest osiągany. Pamiętaj jednak, że niektóre usługi mają kilka parametrów, które mogą powodować długie adresy URL.
Kontrola wykorzystania interfejsów API Google
Źle zaprojektowane klienty API mogą wczytywać więcej zasobów zarówno na serwerach internetowych, jak i na serwerach Google. Ta sekcja zawiera kilka sprawdzonych metod dla klientów korzystających z interfejsów API. Postępuj zgodnie z tymi sprawdzonymi metodami, aby uniknąć zablokowania aplikacji w wyniku niezamierzonego nadużycia interfejsów API.
Exponential Backoff
Może się zdarzyć, że coś poszło nie tak. Możesz otrzymać kod odpowiedzi HTTP 4XX lub 5XX albo połączenie TCP może zakończyć się niepowodzeniem w dowolnym miejscu między klientem a serwerem Google. Często warto ponowić próbę, ponieważ kolejne żądanie może się udać, nawet jeśli pierwotne żądanie się nie powiodło. Ważne jest jednak, aby nie powtarzać pętli żądań do serwerów Google. Takie pętle mogą przeciążać sieć między klientem a Google, powodując problemy u wielu stron.
Lepszym rozwiązaniem jest ponowienie próby z większym opóźnieniem między kolejnymi próbami. Opóźnienie jest zwykle zwiększane mnożnikiem po każdej próbie (tzw. wykładnicze ponowienie).
Rozważ na przykład aplikację, która chce wysył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 Pythona pokazuje, jak wysłać żądanie z wykładniczym ponowieniem:
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ę, że w łańcuchu wywołań aplikacji nie ma ponownego kodu, który prowadzi do powtarzających się żądań w krótkim czasie.
Żądania zsynchronizowane
Duża liczba zsynchronizowanych żądań do interfejsów API Google może wyglądać jak ataki rozproszone (DDoS) rozproszone w infrastrukturze Google i odpowiednio traktowane. Aby tego uniknąć, upewnij się, że żądania API nie są synchronizowane między klientami.
Rozważmy na przykład aplikację wyświetlającą godzinę w bieżącej strefie czasowej. Ta aplikacja prawdopodobnie ustawi alarm w systemie operacyjnym klienta na początku minuty, aby można było zaktualizować wyświetlany czas. Aplikacja nie powinna wywoływać żadnych interfejsów API w ramach przetwarzania powiązanego z tym alarmem.
Wykonywanie wywołań interfejsu API w odpowiedzi na stały alarm sprawia, że są one synchronizowane na początku minuty nawet wtedy, gdy są rozłożone na różne urządzenia. Źle zaprojektowana aplikacja powoduje nagłe zwiększenie ruchu o 60 razy więcej niż zwykle, na początku każdej minuty.
Dobrym rozwiązaniem jest ustawienie drugiego alarmu na losowo wybrany czas. Gdy drugi alarm uruchomi się, aplikacja wywoła wszelkie interfejsy API, których potrzebuje, i zapisze wyniki. Jeśli aplikacja chce zaktualizować swój wyświetlacz na początku minuty, zamiast ponownie wywoływać interfejs API, używa wyników zapisanych wcześniej. Takie podejście powoduje równomierne rozłożenie w czasie wywołań interfejsu API. Co więcej, wywołania interfejsu API nie opóźniają renderowania po zaktualizowaniu wyświetlacza.
Oprócz początku minuty, które należy uwzględnić, należy unikać sytuacji, w których nie należy kierować reklam na godzinę i pół dnia każdego dnia.
Przetwarzanie odpowiedzi
Z tej sekcji dowiesz się, jak dynamicznie wyodrębniać te wartości z odpowiedzi usługi internetowej.
Usługi internetowe Map Google udostępniają odpowiedzi, które są łatwe do zrozumienia, ale niezbyt przyjazne dla użytkownika. Podczas wykonywania zapytania zamiast wyświetlać zbiór danych lepiej wyodrębnić kilka konkretnych wartości. Ogólnie analizuje się odpowiedzi z usługi internetowej i pobiera tylko te wartości, które Cię interesują.
Stosowany schemat analizy zależy od tego, czy zwracasz dane wyjściowe w formacie JSON. Odpowiedzi JSON, które są już w formie obiektów JavaScriptu, mogą być przetwarzane w samym języku JavaScript po stronie klienta.