שימוש באסימוני סשנים עם 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 שמשמש בממשק API של JavaScript במפות Google (התמונה הימנית). כשמשתמשים באותם סוגי מפה ושכבה עם הערך true ב-overlay, מתקבלת משבצת שקופה עם שכבת-על של מפה, בסגנון שמתאים להצגה על גבי תמונות לוויין (התמונה השמאלית).

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.