Dołącz do nas podczas kolejnego Dnia Społeczności Deweloperów Google Maps Platform, który odbędzie się w grudniu w San Francisco. Zgłoś się, aby wziąć udział.

Google używa technologii AI do tłumaczenia treści na Twój preferowany język. Tłumaczenia wygenerowane przez AI mogą zawierać błędy.

Sprawdzone metody korzystania z interfejsu Street View Static API

Interfejsy API Google Maps Platform dla statycznych stron internetowych to zbiór interfejsów HTTP, które generują obrazy do umieszczenia bezpośrednio 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 kilka typowych praktyk przydatnych podczas konfigurowania żądań obrazów i usług internetowych oraz przetwarzania odpowiedzi usług. Więcej informacji o 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 działa jak usługa internetowa. Więcej informacji o usłudze metadanych znajdziesz w artykule Metadane zdjęć Street View.

Czym jest statyczny interfejs API sieci?

Interfejsy API Google Maps Platform do statycznych stron internetowych umożliwiają umieszczanie obrazu Map Google na stronie internetowej bez konieczności używania JavaScriptu lub dynamicznego wczytywania strony. Statyczne interfejsy API sieci Web 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 internetowe 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. Zgodnie z ograniczeniami licencyjnymi opisanymi w Warunkach korzystania z usługi Google Maps Platform te usługi są przeznaczone do używania w połączeniu z mapą.

Usługi internetowe interfejsów API Map Google używają żądań HTTP lub HTTPS do określonych adresów URL, przekazując parametry adresu 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 do przeanalizowania lub przetworzenia przez aplikację.

Żą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ń Google Maps Platform, które używają kluczy interfejsu API lub zawierają dane użytkownika. Żądania wysyłane przez HTTP, które zawierają dane wrażliwe, mogą zostać odrzucone.

Tworzenie prawidłowego adresu URL

Może się wydawać, że „prawidłowy” URL jest oczywisty, ale nie zawsze tak jest. Adres URL wpisany na przykład na pasku adresu w przeglądarce może zawierać znaki specjalne (np."上海+中國"). Przeglądarka musi wewnętrznie przetłumaczyć te znaki na inne kodowanie przed ich przesłaniem. Z tego samego powodu 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 musi też przetłumaczyć te znaki przed wysłaniem ich do serwera WWW. Ten proces nazywa się kodowaniem adresów URL lub kodowaniem procentowym.

Znaki specjalne

Znaki specjalne trzeba przekształcić, ponieważ wszystkie adresy URL muszą być zgodne ze składnią określoną w specyfikacji Uniform Resource Identifier (URI). W efekcie adresy URL mogą 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. Te znaki są podsumowane w tabeli:

Podsumowanie prawidłowych znaków w adresie URL

Ustaw	znaków	Zastosowanie adresu 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 w 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 9	ciągi tekstowe, użycie schematu (`http`), port (`8080`) itp.
Niezarezerwowane	- _ . ~	Ciągi tekstowe
Zarezerwowane	! * ' ( ) ; : @ & = + $ , / ? % # [ ]	znaki kontrolne lub ciągi tekstowe,

Podczas tworzenia prawidłowego adresu URL musisz upewnić się, że zawiera on tylko znaki podane w tabeli. Dostosowanie adresu URL do tego zestawu znaków zwykle prowadzi do 2 problemów – pominięcia i zastąpienia:

Znaki, które chcesz obsłużyć, znajdują się poza powyższym zestawem. Na przykład znaki w językach obcych, takie jak 上海+中國, muszą być zakodowane za pomocą powyższych znaków. Zgodnie z powszechną konwencją spacje (które nie są dozwolone w adresach URL) są często reprezentowane przez znak plusa '+'.
Znaki istnieją w powyższym zbiorze jako znaki zarezerwowane, ale muszą być używane dosłownie. Na przykład ? jest używany w adresach URL do oznaczania początku ciągu zapytania. Jeśli chcesz użyć ciągu „? i tajemnice”, 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 ich znakowi UTF-8. Na przykład 上海+中國 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 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:

Niebezpieczny znak	Zakodowana wartość
Spacja	`%20`
”.	`%22`
<	`%3C`
>	`%3E`
#	`%23`
%	`%25`
\|	`%7C`

Konwertowanie adresu URL otrzymanego od użytkownika bywa trudne. Użytkownik może na przykład wpisać adres „5th&Main St.”. Zasadniczo adres URL należy tworzyć z jego części, traktując wszelkie dane wejściowe użytkownika jako znaki dosłowne.

Dodatkowo adresy URL są ograniczone do 16 384 znaków we wszystkich usługach internetowych i statycznych interfejsach API Google Maps Platform. W przypadku większości usług ten limit znaków rzadko zostanie osiągnięty. Pamiętaj jednak, że niektóre usługi mają kilka parametrów, co może skutkować długimi adresami URL.

Używanie interfejsów API Google zgodnie z zasadami

Ź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. Postępowanie zgodnie z tymi sprawdzonymi metodami może zapobiec zablokowaniu aplikacji z powodu niezamierzonego nadużycia interfejsów API.

Wzrastający czas do ponowienia

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

Lepszym rozwiązaniem jest ponawianie prób z coraz dłuższymi przerwami między nimi. Opóźnienie zwykle zwiększa się o czynnik mnożnikowy przy każdej próbie. Takie podejście jest znane jako wzrastający czas do ponowienia.

Weźmy na przykład aplikację, która wysyła do interfejsu Time Zone API takie żądanie:

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 użyciem wzrastającego czasu do ponowienia:

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}")

Upewnij się, że w łańcuchu wywołań aplikacji nie ma kodu ponownej próby, który prowadzi do powtarzających się żądań w krótkich odstępach czasu.

Żądania zsynchronizowane

Duża liczba żądań synchronicznych do interfejsów API Google może wyglądać jak rozproszony atak typu DoS (DDoS) na infrastrukturę Google i zostać odpowiednio potraktowana. Aby uniknąć tego problemu, upewnij się, że żądania do interfejsu 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 wybudzić go na początku minuty i zaktualizować wyświetlany czas. Nie wykonuj żadnych wywołań interfejsu API w aplikacji w ramach przetwarzania związanego z tym alarmem.

Wykonywanie wywołań interfejsu API w odpowiedzi na stały alarm jest nieprawidłowe, ponieważ powoduje synchronizację wywołań interfejsu API z początkiem minuty, nawet między różnymi urządzeniami, zamiast równomiernego rozłożenia w czasie. Źle zaprojektowana aplikacja, która tak robi, na początku każdej minuty generuje skok ruchu do poziomu 60 razy wyższego niż normalnie.

Zamiast tego możesz zaprojektować aplikację tak, aby miała drugi alarm ustawiony na losowo wybrany czas. Gdy uruchomi się drugi alarm, aplikacja wywoła wszystkie potrzebne interfejsy API i zapisze 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 podejściu wywołania interfejsu API są rozłożone równomiernie w czasie. Ponadto wywołania interfejsu API nie opóźniają renderowania, gdy wyświetlacz się aktualizuje.

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

Przetwarzanie odpowiedzi

Ponieważ dokładny format poszczególnych odpowiedzi na zapytanie o usługę sieciową nie jest gwarantowany (niektórych elementów może brakować lub mogą znajdować się w kilku miejscach), nie zakładaj, że format zwracany w przypadku danej odpowiedzi jest taki sam dla różnych zapytań. Zamiast tego przetwórz odpowiedź i wybierz odpowiednie wartości za pomocą wyrażeń.

W tej sekcji dowiesz się, jak dynamicznie wyodrębniać te wartości z odpowiedzi usługi internetowej.

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

Schemat analizy, którego używasz, zależy od tego, czy zwracasz dane wyjściowe w formacie JSON. Odpowiedzi JSON, które są już w postaci obiektów w JavaScripcie, mogą być przetwarzane w JavaScripcie po stronie klienta.