שימוש באסימוני סשנים עם 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 (מתואר בקטע Optional fields).

streetview

תמונות פנורמה של Street View. מידע נוסף זמין במאמר כרטיסי Street View.

language

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

region

מזהה אזור של Commone Data Repository (שתי אותיות רישיות) שמייצג את המיקום הפיזי של המשתמש. לדוגמה: US.

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

imageFormat

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

scale

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

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

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

גורם קנה מידה 1x	גורם קנה מידה 2

highDpi

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

גורם קנה מידה 1x	גורם קנה מידה פי 2 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: לא נכון	overlay: נכון

קובץ ה-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. המפה שמתקבלת מעובדת עם שמות ונתונים בשפה האנגלית, כפי שהיא נאמרת בארה"ב.

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

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

תגובה של אסימון סשן

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

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

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

session

ערך אסימון סשן שצריך לכלול בכל בקשות ה-API של אריחי המפה.

expiry

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

tileWidth

הרוחב של המשבצות נמדד בפיקסלים.

tileHeight

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

imageFormat

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