Używanie tokenów sesji z interfejsem Map Tiles API

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

Token sesji to fragment danych (UUID), który jest używany w wywołaniach REST do identyfikowania sesji, czyli serii powiązanych wymian wiadomości. We wszystkich żądaniach dotyczących kafelków 2D i zdjęć Street View musisz uwzględnić token sesji. Dołączasz go jako wartość parametru session do wszystkich adresów URL żądań.

W interfejsie Map Tiles API token sesji reprezentuje zdefiniowany zestaw opcji wyświetlania. Oznacza to, że nie musisz przekazywać zestawu opcji wyświetlania przy każdym żądaniu kafelka. Możesz używać tego samego tokena sesji na wielu klientach. Token sesji jest obecnie ważny przez 2 tygodnie od momentu jego wydania, ale może się to zmienić. Czas ważności tokena sesji możesz zawsze sprawdzić w polu expiry w odpowiedzi.

Żądanie tokena sesji

Aby poprosić o token sesji, wyślij żądanie HTTPS POST do punktu końcowego createSession, jak pokazano w tym przykładzie. Żądanie musisz wysłać z nagłówkiem Content-Type: application/json.

curl -X POST -d '{
  "mapType": "streetview",
  "language": "en-US",
  "region": "US"
}' \
-H 'Content-Type: application/json' \
"https://tile.googleapis.com/v1/createSession?key=YOUR_API_KEY"

Pola wymagane

mapType

Typ mapy podstawowej. Może to być jedna z tych wartości:

roadmap
Standardowe kafelki mapy Google Maps.
satellite
Zdjęcia satelitarne.
terrain
Zdjęcia terenu. Jeśli jako typ mapy wybierzesz terrain, musisz też uwzględnić typ warstwy layerRoadmap (opisany w sekcji Pola opcjonalne).
streetview
 panoramy Street View. Więcej informacji znajdziesz w artykule o kafelkach Street View.
language

Tag języka IETF określający język, w którym mają być wyświetlane informacje na kafelkach. Na przykład en-US określa język angielski używany w Stanach Zjednoczonych.

region

Identyfikator regionu Common Locale Data Repository (2 wielkie litery) reprezentujący fizyczną lokalizację użytkownika. Na przykład: US.

Pola opcjonalne

imageFormat
Określa format pliku, który ma zostać zwrócony. Prawidłowe wartości to jpeg i png. Pliki JPEG nie obsługują przezroczystości, dlatego nie są zalecane w przypadku kafelków nakładki. Jeśli nie określisz imageFormat, automatycznie zostanie wybrany najlepszy format kafelka.
scale

Zwiększa rozmiar elementów mapy (takich jak etykiety dróg), zachowując rozmiar fragmentu mapy i obsługiwany obszar domyślnego fragmentu mapy. Zwiększenie skali zmniejsza też liczbę etykiet na mapie, co ogranicza bałagan. Prawidłowe wartości scale:

  • scaleFactor1x: wartość domyślna.
  • scaleFactor2x: podwaja rozmiar etykiet i usuwa etykiety mniej ważnych obiektów.
  • scaleFactor4x: czterokrotnie zwiększa rozmiar etykiet i usuwa etykiety mniej istotnych obiektów.

Poniższe przykłady pokazują efekt skalowania elementów mapy.

Współczynnik skalowania 1x Współczynnik skalowania 2x
Mapa ze współczynnikiem skalowania 1x Mapa ze współczynnikiem skalowania 2x
highDpi
Określa, czy mają być zwracane kafelki o wysokiej rozdzielczości. Jeśli współczynnik skalowania zostanie zwiększony, do zwiększenia rozmiaru kafelka zostanie użyta wartość highDpi. Zwykle zwiększenie współczynnika skalowania powoduje powiększenie kafelka do obrazu o tym samym rozmiarze, co obniża jakość. W przypadku highDpi rozmiar wynikowy również jest zwiększany, co pozwala zachować jakość. DPI to skrót od „Dots per Inch” (punkty na cal), a wysoka rozdzielczość oznacza, że kafelek jest renderowany z użyciem większej liczby punktów na cal niż zwykle. Jeśli true, liczba pikseli w każdym z wymiarów x i y jest mnożona przez współczynnik skalowania (czyli 2x lub 4x). Obsługiwany obszar kafelka pozostaje bez zmian. Ten parametr działa tylko z wartościami scale 2x lub 4x. Nie ma to wpływu na kafelki w skali 1x.
Współczynnik skalowania 1x Współczynnik skalowania 2x High DPI
Mapa wyświetlana w standardowej rozdzielczości Mapa wyświetlana w rozdzielczości 2x High DPI
layerTypes

Tablica wartości określająca typy warstw dodanych do mapy. Prawidłowe wartości to:

layerRoadmap
Wymagane, jeśli jako typ mapy podasz terrain. Można też opcjonalnie nałożyć je na typ mapy satellite. Nie ma wpływu na kafelki mapy drogowej.
layerStreetview
Pokazuje ulice i lokalizacje z dostępną funkcją Street View, używając niebieskich konturów na mapie.
layerTraffic
Wyświetla aktualne warunki na drodze.
styles

Tablica obiektów stylu JSON, które określają wygląd i poziom szczegółowości elementów mapy, takich jak drogi, parki i obszary zabudowane. Style służą do dostosowywania standardowej mapy podstawowej Google. Parametr styles jest prawidłowy tylko wtedy, gdy typ mapy to roadmap. Pełną składnię stylów znajdziesz w dokumentacji stylów.

overlay

Wartość logiczna określająca, czy layerTypes ma być renderowany jako osobna nakładka czy połączony z obrazem podstawowym. Gdy true, mapa podstawowa nie jest wyświetlana. Jeśli nie zdefiniowano żadnych layerTypes, ta wartość jest ignorowana.

Na przykład żądanie typu mapy satellite z warstwą layerRoadmap i parametrem overlay ustawionym na false zwraca kafelki odpowiadające typowi mapy hybrid używanemu w interfejsie Maps JavaScript API (obraz po lewej). Te same typy map i warstw z parametrem overlay ustawionym na true dają przezroczysty kafelek z nakładką mapy, odpowiednio stylizowany do nakładania na zdjęcia satelitarne (obraz po prawej).

overlay: false overlay: true
Nakładka ustawiona na wartość „false” Nakładka ustawiona na wartość „true”

Ten kod JSON jest przykładem typowej treści żądania, która zawiera zarówno pola wymagane, jak i opcjonalne.

{
  "mapType": "satellite",
  "language": "en-US",
  "region": "us",
  "layerTypes": [ "layerRoadmap", "layerStreetview" ],
  "overlay":  true,
  "scale": "scaleFactor1x",
  "styles": [
    {
      "stylers": [
        { "hue": "#00ffe6" },
        { "saturation": -20 }
      ]
    },{
      "featureType": "road",
      "elementType": "geometry",
      "stylers": [
        { "lightness": 100 },
        { "visibility": "simplified" }
      ]
    }
  ]
}

Ten przykład zawiera nakładkę, którą można połączyć ze zdjęciami satelitarnymi. Przykład zawiera zarówno mapę drogową, jak i nakładkę Street View. Wygenerowana mapa zawiera nazwy i dane w języku angielskim, jakim posługują się mieszkańcy Stanów Zjednoczonych.

Odpowiedź tokena sesji

Poniższy kod JSON to przykładowa treść odpowiedzi.

{
  "session": "IgAAAHGU9jnAU4KOAfwY3Bcd6eH_WxQsyocSBAdUnAr9pnvTTNXtF9c_27RBo94ytEXTDg",
  "expiry": "1361828036",
  "tileWidth": 256,
  "tileHeight": 256,
  "imageFormat": "png"
}

Poniższa lista zawiera definicje pól w treści odpowiedzi.

session
Wartość tokena sesji, którą musisz uwzględnić we wszystkich żądaniach do interfejsu Map Tiles API.
expiry
Ciąg tekstowy zawierający czas (w sekundach od początku epoki), po którym token wygasa. Token sesji jest ważny przez 2 tygodnie od momentu utworzenia, ale te zasady mogą ulec zmianie bez powiadomienia.
tileWidth
Szerokość kafelków mierzona w pikselach.
tileHeight
Wysokość kafelków mierzona w pikselach.
imageFormat
Format pliku graficznego, który może być png lub jpeg.