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

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

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

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

כדי לבקש אסימון סשן, שולחים בקשת POST ב-HTTPS לנקודת הקצה 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

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

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

imageFormat

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

scale

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

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

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

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

highDpi

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

גורם קנה מידה 1x	גורם לקביעת קנה מידה 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" }
      ]
    }
  ]
}

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

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

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

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

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

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

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

session

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

expiry

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

tileWidth

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

tileHeight

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

imageFormat

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