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

Token sesji to fragment danych (a UUID) używany w wywołaniach REST do identyfikowania sesji—serii powiązanych wymian wiadomości. Token sesji musisz uwzględnić we wszystkich żądaniach dotyczących kafelków 2D i zdjęć Street View. Dodajesz go jako wartość parametru session dołączonego 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 z każdym żądaniem kafelka. Możesz używać tego samego tokena sesji na wielu klientach. Token sesji jest obecnie ważny przez 2 tygodnie od daty wydania, ale może się to zmienić. Czas wygaśnięcia tokena sesji możesz sprawdzić, patrząc na pole expiry w wiadomości z 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 musi zawierać nagłówek 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. Ta wartość może być jedną z tych:

roadmap

Standardowe kafelki mapy Google.

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 Kafelki Street View.

language

Tag języka IETF, który określa język używany do wyświetlania informacji 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), który reprezentuje fizyczną lokalizację użytkownika. Na przykład US.

Pola opcjonalne

imageFormat

Określa format pliku do zwrócenia. Prawidłowe wartości to jpeg lub 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 (np. etykiet 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 zmniejsza bałagan. Prawidłowe wartości scale to:

• scaleFactor1x: wartość domyślna.
• scaleFactor2x: podwaja rozmiar etykiety i usuwa etykiety drobnych elementów.
• scaleFactor4x: czterokrotnie zwiększa rozmiar etykiety i usuwa etykiety drobnych elementów.

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

Współczynnik skalowania 1x	Współczynnik skalowania 2x

highDpi

Określa, czy mają być zwracane kafelki o wysokiej rozdzielczości. Jeśli współczynnik skalowania zostanie zwiększony, highDpi służy do zwiększenia rozmiaru kafelka. Zwykle zwiększenie współczynnika skalowania powiększa wynikowy kafelek do obrazu o tym samym rozmiarze, co obniża jakość. W przypadku highDpi zwiększa się też rozmiar wynikowy, co pozwala zachować jakość. DPI oznacza punkty na cal, a High DPI oznacza, że kafelek jest renderowany przy użyciu większej liczby punktów na cal niż zwykle. Jeśli wartość to true, liczba pikseli w każdym z wymiarów x i y jest mnożona przez współczynnik skalowania (czyli 2x lub 4x). Obszar pokrycia kafelka pozostaje bez zmian. Ten parametr działa tylko w przypadku wartości scale 2x lub 4x. Nie ma wpływu na kafelki o skali 1x.

Współczynnik skalowania 1x	Współczynnik skalowania 2x High DPI

layerTypes

Tablica wartości, która określa typy warstw dodanych do mapy. Prawidłowe wartości:

layerRoadmap

Wymagane, jeśli jako typ mapy określisz terrain. Można też opcjonalnie nałożyć na typ mapy satellite. Nie ma wpływu na kafelki mapy drogowej.

layerStreetview

Pokazuje ulice i lokalizacje z obsługą Street View za pomocą 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. Stylizacja służy do dostosowywania standardowej mapy podstawowej Google. Parametr styles jest prawidłowy tylko wtedy, gdy typ mapy to roadmap. Pełną składnię stylu znajdziesz w dokumentacji stylu.

overlay

Wartość logiczna, która określa, czy layerTypes mają być renderowane jako osobna nakładka, czy też łączone z obrazami bazowymi. Gdy wartość to 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 powoduje wyświetlenie kafelków odpowiadających typowi mapy hybrid używanemu w Maps JavaScript API (obraz po lewej). Te same typy map i warstw z parametrem overlay ustawionym na true powodują wyświetlenie przezroczystego kafelka z nakładką mapy, odpowiednio stylizowanego do nakładania na zdjęcia satelitarne (obraz po prawej).

overlay: false	overlay: true

Poniższy kod JSON to przykład typowego 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. Wynikowa mapa jest renderowana z nazwami i danymi w języku angielskim, w wersji używanej w Stanach Zjednoczonych.

Odpowiedź tokena sesji

Poniższy kod JSON to przykład treści 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 interfejsu Map Tiles API.

expiry

Ciąg znaków zawierający czas (w sekundach od początku epoki), w którym token wygasa. Token sesji jest ważny przez 2 tygodnie od daty utworzenia, ale ta zasada może ulec zmianie bez powiadomienia.

tileWidth

Szerokość kafelków w pikselach.

tileHeight

Wysokość kafelków w pikselach.

imageFormat

Format obrazu, który może być png lub jpeg.