שימוש באסימוני סשנים עם 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 מייצג נקודות לאינץ', ו-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.