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

Token sesji to fragment danych (UUID) używany w wywołaniach REST do identyfikowania sesji, czyli serii powiązanych ze sobą wymiany wiadomości. Musisz umieszczać token sesji we wszystkich żądaniach dotyczących płyt 2D i zdjęć Street View. Podajesz ją jako wartość parametru session dołączanego 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. Tego samego tokena sesji możesz używać w wielu klientach. Token sesji jest obecnie ważny przez 2 tygodnie od momentu jego wystawienia, ale może się to zmienić. Czas wygaśnięcia tokena sesji możesz w każdej chwili sprawdzić w polu expiry w wiadomości z odpowiedzią.

Uwaga: aby uzyskać dostęp do kafelków 2D i Street View, musisz użyć tokenów sesji, ale nie do kafelków 3D.

Żądanie tokena sesji

Aby zażądać tokena 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 malowane fragmenty mapy z Map Google.

satellite

Zdjęcia satelitarne.

terrain

Zdjęcia terenu. Wybierając terrain jako typ mapy, musisz też podać 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 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 repozytorium danych Common Locale Data Repositories (dwie wielkie litery) reprezentujący 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, więc nie są zalecane w przypadku elementów nakładanych. Jeśli nie określisz właściwości imageFormat, automatycznie zostanie wybrany najlepszy format kafelka.

scale

Skaluje rozmiar elementów mapy (np. etykiet dróg), zachowując rozmiar kafelka i zasięg domyślnego kafelka. Zwiększenie skali zmniejsza też liczbę etykiet na mapie, co zwiększa przejrzystość. Poniższe wartości są prawidłowymi wartościami scale:

• scaleFactor1x: wartość domyślna.
• scaleFactor2x: podwaja rozmiar etykiety i usuwa etykiety podrzędnych cech.
• scaleFactor4x: rozmiar etykiety jest podzielony na cztery części i usuwane etykiety cech podrzędnych.

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

Współczynnik skali 1x	Współczynnik skali 2x

highDpi

Określa, czy zwrócić kafelki o wysokiej rozdzielczości. Jeśli współczynnik skali wzrośnie, highDpi służy do zwiększania rozmiaru kafelka. Normalnie zwiększenie współczynnika skali powoduje powiększenie powstałego kafelka w obraz o tym samym rozmiarze, co obniża jakość. W przypadku highDpi rozmiar wynikowy jest też zwiększany z zachowaniem jakości. DPI to skrót od kropek na cal, a wysokiej DPI oznacza, że kafelek renderuje się z użyciem większej liczby punktów na cal niż normalnie. Jeśli ustawiona jest wartość true, to liczba pikseli w każdym z wymiarów x i y jest mnożona przez współczynnik skali (czyli 2x lub 4x). Zasięg kafelka pozostaje bez zmian. Ten parametr działa tylko z wartościami scale wynoszącymi 2x lub 4x. Nie ma wpływu na kafelki skali 1x.

Współczynnik skali 1x	Współczynnik skali 2x wysoki DPI

layerTypes

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

layerRoadmap

Wymagane, jeśli jako typ mapy określisz terrain. Można ją też opcjonalnie nakładać na typ mapy satellite. Nie ma wpływu na fragmenty mapy.

layerStreetview

Ulice i lokalizacje z obsługą Street View są zaznaczone na mapie za pomocą niebieskich konturów.

layerTraffic

Pokazuje aktualne warunki na drodze.

styles

Tablica obiektów w stylu JSON, które określają wygląd i poziom szczegółowości obiektów map, takich jak drogi, parki i obszary zabudowane. Styl 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 określająca, czy element layerTypes powinien być renderowany jako oddzielna nakładka, czy połączony ze zdjęciem podstawowym. Jeśli true, mapa podstawowa nie jest wyświetlana. Jeśli nie zdefiniowano żadnej funkcji layerTypes, ta wartość jest ignorowana.

Na przykład żądanie mapy satellite z warstwą layerRoadmap i ustawienie overlay z wartością false spowoduje wyświetlenie kafelków odpowiadających typowi mapy hybrid używanym w interfejsie Maps JavaScript API (obraz po lewej stronie). Ten sam typ mapy i warstwy, w której parametr overlay ma wartość true, powoduje utworzenie przezroczystego kafelka z nakładką mapy, który jest odpowiednio dopasowany do zdjęć satelitarnych (obraz po prawej stronie).

overlay: fałsz	overlay: prawda

Ten kod JSON to przykład 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 przedstawia nakładkę, która nadaje się do łączenia ze zdjęciami satelitarnymi. W przykładzie znajduje się zarówno plan, jak i nakładka widoku ulicy. Otrzymana mapa jest renderowana z nazwami i danymi w języku angielskim, tak jak to się mówi w Stanach Zjednoczonych.

apiOptions: tablica wartości określających dodatkowe opcje do zastosowania. Obsługiwane opcje:

• MCYJ5E517XR2JC – włącz nowy styl mapy. W okresie akceptacji żądania będą korzystać z dotychczasowego stylu, chyba że podasz tę wartość.

Odpowiedź tokena sesji

Ten 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ędniać we wszystkich żądaniach do interfejsu Map Tiles API.

expiry

Ciąg tekstowy zawierający czas (w sekundach od początku epoki), w którym wygasa token. Token sesji jest ważny przez 2 tygodnie od momentu utworzenia, ale ta zasada może się zmienić bez powiadomienia.

tileWidth

Szerokość kafelków mierzona w pikselach.

tileHeight

Wysokość kafelków mierzona w pikselach.

imageFormat

Format obrazu: png lub jpeg.