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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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