Sprawdzone metody korzystania z interfejsu Street View Static API

Zbiór interfejsów HTTP, czyli statyczne interfejsy API Google Maps Platform, generuje obrazy do bezpośredniego umieszczania na stronie internetowej.

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

W tym przewodniku opisujemy niektóre typowe praktyki przydatne podczas konfigurowania żądań usług obrazów i usług internetowych oraz przetwarzania odpowiedzi usług. Więcej informacji o interfejsie 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 – jak usługa internetowa. Więcej informacji o usłudze metadanych znajdziesz w artykule Metadane obrazów Street View.

Czym jest statyczny interfejs API?

Statyczne interfejsy API Google Maps Platform umożliwiają umieszczanie obrazu z Map Google na stronie internetowej bez konieczności używania JavaScriptu ani dynamicznego wczytywania strony. Statyczne interfejsy API sieci tworzą obraz na podstawie parametrów adresu URL wysyłanych za pomocą standardowego żądania HTTPS.

Typowe żądanie do interfejsu Street View Static API ma następującą postać:

  https://www.googleapis.com/streetview/z/x/y?parameters

Co to jest usługa internetowa?

Usługi sieciowe 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. Usługi te są przeznaczone do używania w połączeniu z mapą zgodnie z ograniczeniami licencyjnymi określonymi w Warunkach korzystania z usługi Google Maps Platform.

Usługi internetowe interfejsów API Map Google używają żądań HTTP lub HTTPS do określonych adresów URL, przekazując parametry URL lub dane POST w formacie JSON jako argumenty do usług. Zazwyczaj te usługi zwracają dane w treści odpowiedzi w formacie JSON, aby aplikacja mogła je przeanalizować lub przetworzyć.

Żądanie metadanych interfejsu Street View Static API ma następującą postać:

https://maps.googleapis.com/maps/api/streetview/parameters

Dostęp SSL i TLS

Protokół HTTPS jest wymagany w przypadku wszystkich żądań wysyłanych do Google Maps Platform, które używają kluczy API lub zawierają dane użytkowników. Żądania wysyłane przez 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 tak nie jest. Adres URL wpisany na przykład w pasku adresu w przeglądarce może zawierać znaki specjalne (np."上海+中國"). Przeglądarka musi wewnętrznie przetłumaczyć te znaki na inne kodowanie przed transmisją. Podobnie każdy kod, który generuje lub akceptuje dane wejściowe w formacie UTF-8, może traktować adresy URL ze znakami UTF-8 jako „prawidłowe”, ale przed wysłaniem ich do serwera WWW musi przetłumaczyć te znaki. Ten proces nazywa się kodowaniem 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 Uniform Resource Identifier (URI). Oznacza to, że adresy URL muszą zawierać tylko specjalny podzbiór znaków ASCII: znane symbole alfanumeryczne i niektóre znaki zarezerwowane do użycia jako znaki sterujące w adresach URL. W tej tabeli podsumowano te znaki:

Podczas tworzenia prawidłowego adresu URL musisz zadbać o to, aby zawierał on tylko znaki widoczne w tabeli. Dostosowanie adresu URL do tego zestawu znaków zwykle powoduje 2 problemy: pominięcie i zamianę:

• Znaki, które chcesz obsługiwać, nie należą do powyższego zestawu. Na przykład znaki w językach obcych, takie jak 上海+中國, muszą być zakodowane przy użyciu powyższych znaków. Zgodnie z powszechną konwencją spacje (które są niedozwolone w adresach URL) są często reprezentowane za pomocą znaku plusa '+'.
• Znaki z powyższego zbioru są znakami zarezerwowanymi, ale muszą być używane dosłownie. Na przykład symbol ? jest używany w adresach URL do oznaczania początku ciągu zapytania. Jeśli chcesz użyć ciągu znaków „? and the Mysterions”, musisz zakodować znak '?'.

Wszystkie znaki, które mają być zakodowane na potrzeby adresu URL, są kodowane za pomocą znaku '%' i dwuznakowej wartości szesnastkowej odpowiadającej znakowi UTF-8. Na przykład znak 上海+中國 w kodowaniu UTF-8 będzie zakodowany w adresie URL jako %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B. Ciąg znaków ? and the Mysterians zostanie zakodowany 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:

Konwertowanie adresu URL otrzymanego z danych wejściowych użytkownika może być czasami trudne. Na przykład użytkownik może wpisać adres jako „5th&Main St.”. Zazwyczaj adres URL należy tworzyć z jego części, traktując dane wejściowe użytkownika jako znaki dosłowne.

Dodatkowo w przypadku wszystkich usług sieciowych Google Maps Platform i statycznych interfejsów API sieciowych adresy URL są ograniczone do 16384 znaków. W przypadku większości usług ten limit znaków rzadko będzie osiągany. Pamiętaj jednak, że niektóre usługi mają kilka parametrów, które mogą powodować długie adresy URL.

Uprzejme korzystanie z interfejsów API Google

Źle zaprojektowane klienty API mogą powodować duże obciążenie internetu i serwerów. Ta sekcja zawiera sprawdzone metody dotyczące klientów interfejsu API. Stosowanie tych sprawdzonych metod może zapobiec zablokowaniu aplikacji z powodu niezamierzonego nadużywania interfejsów API.

Wzrastający czas do ponowienia

W rzadkich przypadkach coś może pójść nie tak z Twoim żądaniem. Możesz otrzymać kod odpowiedzi HTTP 4xx lub 5xx albo połączenie TCP może się nie udać gdzieś między Twoim klientem a serwerem Google. Często warto ponowić żądanie, ponieważ kolejne żądanie może się powieść, mimo że pierwotne się nie powiodło. Nie należy jednak wielokrotnie wysyłać żądań do serwerów Google. Takie zapętlenie może przeciążyć sieć między klientem a Google, powodując problemy dla wielu podmiotów.

Lepszym rozwiązaniem jest ponawianie próby z coraz większym opóźnieniem między kolejnymi próbami. Opóźnienie zwykle wzrasta o czynnik multiplikatywny przy każdej próbie. Takie podejście jest znane jako wzrastający czas do ponowienia.

Rozważmy na przykład aplikację, która wysył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ład w Pythonie pokazuje, jak wysłać żądanie z wykładniczym wycofywaniem:

import json
import time
import urllib.error
import urllib.parse
import urllib.request

# The maps_key defined in the following code 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 the request didn't produce an IOError, parse the result.
            result = json.load(response)

            if result["status"] == "OK":
                return result["timeZoneId"]
            elif result["status"] != "UNKNOWN_ERROR":
                # Many API errors can't be fixed by a retry, such as
                # INVALID_REQUEST or ZERO_RESULTS. Don't retry 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 on each retry.


if __name__ == "__main__":
    tz = timezone(39.6034810, -119.6822510, 1331161200)
    print(f"Timezone: {tz}")

Sprawdź, czy w łańcuchu wywołań aplikacji nie ma kodu ponownej próby, który powoduje powtarzanie żądań w szybkiej kolejności.

Zsynchronizowane prośby

Duża liczba zsynchronizowanych żądań wysyłanych do interfejsów API Google może wyglądać jak rozproszony atak typu „odmowa usługi” (DDoS) na infrastrukturę Google i być odpowiednio traktowana. Aby uniknąć tego problemu, upewnij się, że żądania API nie są synchronizowane między klientami.

Rozważmy na przykład aplikację, która wyświetla czas w bieżącej strefie czasowej. Ta aplikacja prawdopodobnie ustawia alarm w systemie operacyjnym klienta, aby go wybudzić na początku minuty i zaktualizować wyświetlany czas. Nie wykonuj w aplikacji ż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 niekorzystne, ponieważ powoduje synchronizację wywołań interfejsu API z początkiem minuty, nawet na różnych urządzeniach, zamiast równomiernego rozłożenia w czasie. Źle zaprojektowana aplikacja generuje w tym przypadku skok natężenia ruchu, który na początku każdej minuty jest 60 razy większy niż zwykle.

Zamiast tego możesz zaprojektować aplikację tak, aby drugi alarm był ustawiony na losowo wybraną godzinę. Gdy włączy się drugi alarm, aplikacja wywołuje potrzebne interfejsy API i zapisuje wyniki. Gdy aplikacja aktualizuje wyświetlane informacje 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ą równomiernie rozłożone w czasie. Ponadto wywołania interfejsu API nie opóźniają renderowania, gdy ekran jest aktualizowany.

Oprócz początku minuty nie kieruj reklam na inne popularne czasy synchronizacji, takie jak początek godziny i początek każdego dnia o północy.

Przetwarzanie odpowiedzi

Dokładny format poszczególnych odpowiedzi na żądanie usługi internetowej nie jest gwarantowany – niektóre elementy mogą być nieobecne lub znajdować się w wielu miejscach. Nie zakładaj więc, że format zwrócony w przypadku danej odpowiedzi jest taki sam w przypadku różnych zapytań. Zamiast tego przetwórz odpowiedź i wybierz odpowiednie wartości za pomocą wyrażeń.

W tej sekcji znajdziesz omówienie dynamicznego wyodrębniania tych wartości z odpowiedzi usługi internetowej.

Usługi internetowe Map Google zwracają odpowiedzi, które są zrozumiałe, ale nie przyjazne dla użytkownika. Podczas wykonywania zapytania zamiast wyświetlać zestaw danych prawdopodobnie chcesz wyodrębnić kilka konkretnych wartości. Zazwyczaj analizuj odpowiedzi z usługi internetowej i wyodrębniaj tylko te wartości, które Cię interesują.

Użyty schemat analizowania zależy od tego, czy zwracasz dane wyjściowe w formacie JSON. Odpowiedzi JSON, które są już w formie obiektów JavaScript, mogą być przetwarzane w JavaScript na urządzeniu klienta.