שימוש באסימוני סשנים עם 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
‫
Specifies the file format to return. הערכים התקינים הם jpeg או png. קובצי JPEG לא תומכים בשקיפות, ולכן לא מומלץ להשתמש בהם במשבצות של שכבות-על. אם לא מציינים imageFormat, הפורמט הכי מתאים לאריח נבחר באופן אוטומטי.
scale

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

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

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

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