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

מפתחים באזור הכלכלי האירופי (EEA)

אסימון סשן הוא נתון (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 Tiles.
language

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

region

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

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

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

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

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

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

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

overlay: false overlay: true
השכבה העליונה מוגדרת כ-false השכבה העליונה מוגדרת כ-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" }
      ]
    }
  ]
}

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

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

הנה דוגמה לגוף של תגובה בפורמט JSON.

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

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

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