שימוש באסימוני סשנים עם API של אריחי מפה

טוקן סשן הוא נתון (UUID) שמשמש בקריאות REST כדי לזהות סשן – סדרה של חילופי הודעות קשורים. חובה לכלול אסימון סשן בכל הבקשות של משבצות דו-ממדיות ותמונות Street View. צריך לכלול אותו כערך של פרמטר session שמצורף לכל כתובות ה-URL של הבקשות.

ב-Map Tiles API, טוקן לסשן מייצג קבוצה מוגדרת של אפשרויות תצוגה. זה אומר שאתם לא צריכים להעביר קבוצה של אפשרויות תצוגה בכל בקשה למשבצת. אפשר להשתמש באותו טוקן סשן בכמה לקוחות. הטוקן לסשן תקף כרגע למשך שבועיים מרגע ההנפקה, אבל זה עשוי להשתנות. תמיד אפשר לבדוק את זמן התפוגה של טוקן לסשן בשדה expiry בהודעת התשובה.

בקשה לטוקן לסשן

כדי לבקש טוקן סשן, שולחים בקשת HTTPS POST לנקודת הקצה createSession, כמו בדוגמה הבאה. צריך לשלוח את הבקשה עם כותרת 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"

שדות חובה

mapType

סוג המפה הבסיסית. הערך הזה יכול להיות אחד מהבאים:

roadmap

משבצות המפה הרגילות של מפות Google.

satellite

צילומי לוויין.

terrain

תמונות של פני השטח. כשבוחרים באפשרות terrain כסוג המפה, צריך לכלול גם את סוג השכבה layerRoadmap (הסבר מפורט מופיע בקטע שדות אופציונליים).

streetview

תמונות פנורמיות ב-Street View. מידע נוסף זמין במאמר משבצות ב-Street View.

language

תג שפה של IETF שמציין את השפה שבה מוצג המידע במשבצות. לדוגמה, en-US מציין את השפה האנגלית כפי שמדוברת בארצות הברית.

region

מזהה אזור של מאגר נתונים משותף של לוקאלים (שתי אותיות רישיות) שמייצג את המיקום הפיזי של המשתמש. לדוגמה, US.

שדות אופציונליים

imageFormat

‫

מציין את פורמט הקובץ שיוחזר. הערכים התקינים הם jpeg או png. קובצי JPEG לא תומכים בשקיפות, ולכן לא מומלץ להשתמש בהם במשבצות חופפות. אם לא מציינים imageFormat, המערכת בוחרת באופן אוטומטי את הפורמט הכי מתאים למשבצת.

scale

מגדיל את הגודל של רכיבי המפה (כמו תוויות של כבישים), תוך שמירה על גודל קטע המפה והיקף גיאוגרפי של קטע המפה המוגדר כברירת מחדל. הגדלת קנה המידה גם מצמצמת את מספר התוויות במפה, וכך מפחיתה את העומס. אלה הערכים החוקיים של scale:

• ‫scaleFactor1x: ברירת המחדל.
• ‫scaleFactor2x: מכפיל את גודל התווית ומסיר תוויות של תכונות משניות.
• ‫scaleFactor4x: מגדילה את גודל התווית פי 4 ומסירה תוויות של תכונות משניות.

הדוגמאות הבאות ממחישות את ההשפעה של שינוי קנה המידה של רכיבי המפה.

גורם לקביעת קנה מידה פי 1	גורם לקביעת קנה מידה פי 2

highDpi

הפרמטר

מציין אם להחזיר משבצות ברזולוציה גבוהה. אם מגדילים את גורם קנה המידה, highDpi משמש להגדלת גודל המשבצת. בדרך כלל, הגדלת גורם לקביעת קנה מידה מגדילה את המשבצת שמתקבלת לתמונה באותו גודל, מה שמוריד את האיכות. ב-highDpi, גם הגודל של התוצאה גדל, והאיכות נשמרת. ‫DPI הוא קיצור של Dots per Inch (נקודות לאינץ'), ו-High DPI (DPI גבוה) אומר שהמשבצת מעובדת באמצעות יותר נקודות לאינץ' מהרגיל. אם true, אז מספר הפיקסלים בכל אחד מהממדים x ו-y מוכפל בפקטור ההגדלה (כלומר , פי 2 או פי 4). האזור שהמשבצת מכסה לא משתנה. הפרמטר הזה פועל רק עם ערכי scale של 2x או 4x. היא לא משפיעה על משבצות בקנה מידה של 1x.

גורם לקביעת קנה מידה פי 1	גורם לקביעת קנה מידה 2x DPI גבוה

layerTypes

מערך של ערכים שמציין את סוגי השכבות שנוספו למפה. הערכים התקינים הם:

layerRoadmap

חובה אם מציינים terrain כסוג המפה. אפשר גם להוסיף אותו ככיסוי אופציונלי לsatellite סוג המפה. אין השפעה על משבצות של מפות דרכים.

layerStreetview

התכונה הזו מציגה רחובות ומיקומים שבהם אפשר להשתמש ב-Street View, באמצעות קווי מתאר כחולים במפה.

layerTraffic

מציג את מצב התנועה הנוכחי.

styles

מערך של אובייקטים בסגנון JSON שמציינים את המראה ורמת הפירוט של מאפייני המפה, כמו כבישים, פארקים ואזורים בנויים. העיצוב משמש להתאמה אישית של מפת הבסיס הרגילה של Google. הפרמטר styles תקף רק אם סוג המפה הוא roadmap. למידע על תחביר העיצוב המלא, אפשר לעיין במאמר העזר בנושא סגנונות.

overlay

ערך בוליאני שמציין אם צריך לעבד את layerTypes כשכבת-על נפרדת, או לשלב אותו עם התמונות הבסיסיות. כשהערך הוא true, מפת הבסיס לא מוצגת. אם לא הגדרתם layerTypes, המערכת תתעלם מהערך הזה.

לדוגמה, אם מבקשים סוג מפה satellite עם שכבה layerRoadmap, והערך של overlay מוגדר ל-false, מתקבלות משבצות שוות ערך לסוג המפה hybrid שמשמש ב-Maps JavaScript API (התמונה בצד ימין). אותם סוגי מפות ושכבות עם overlay שמוגדר ל-true יוצרים קטע מפה שקוף עם הצגה על גבי מפה, בסגנון שמתאים לשכבת-על מעל צילומי לוויין (התמונה מימין).

overlay: false	‫overlay: true

ה-JSON הבא הוא דוגמה לגוף בקשה טיפוסי שמכיל שדות חובה ושדות אופציונליים.

{
  "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" }
      ]
    }
  ]
}

בדוגמה הזו מוצגת שכבת-על שמתאימה לשילוב עם צילומי לוויין. הדוגמה מכילה גם מפת דרכים וגם שכבת-על של Street View. המפה שנוצרת מוצגת עם שמות ונתונים באנגלית, כמו שמדברים אותה בארצות הברית.

תגובת טוקן לסשן

הקוד הבא ב-JSON הוא דוגמה לגוף תגובה.

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

ברשימה הבאה מופיעות הגדרות של השדות בגוף התשובה.

session

ערך של טוקן סשן שצריך לכלול בכל הבקשות ל-Map Tiles API.

expiry

‫

מחרוזת שמכילה את הזמן (בשניות מאז תקופת ה-epoch) שבו האסימון יפוג. הטוקן לסשן תקף למשך שבועיים מרגע היצירה שלו, אבל המדיניות הזו עשויה להשתנות ללא הודעה מוקדמת.

tileWidth

רוחב האריחים בפיקסלים.

tileHeight

גובה המשבצות בפיקסלים.

imageFormat

‫

פורמט התמונה, שיכול להיות png או jpeg.