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

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

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

הערה: צריך להשתמש באסימוני סשן כדי לקבל משבצות דו-ממדיות וכרטיסי Street View. אבל לא לקבלת משבצות בתלת-ממד.

בקשה לאסימון סשן

כדי לבקש אסימון סשן, שולחים בקשת 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

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

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

imageFormat

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

scale

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

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

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

גורם קנה מידה 1x	גורם קנה מידה 2

highDpi

ההגדרה קובעת אם להחזיר משבצות ברזולוציה גבוהה. אם הגורם לקביעת קנה המידה הוא גדל, הפונקציה highDpi משמשת להגדלת המשבצת. בדרך כלל, הגדלת גורם קנה המידה מגדילה את האריח שמתקבל לתמונה של בגודל זהה, מה שמקטין את האיכות. עם highDpi, גם הגודל שמתקבל גדל, שומר על האיכות. פירוש ראשי התיבות DPI הוא Dots per Inch ו-High DPI הרינדור של האריח מתבצע באמצעות יותר נקודות לאינץ' מהרגיל. אם הערך שלו הוא true, הערך של מספר הפיקסלים בכל אחד מהמאפיינים x ו-y מוכפל בקנה מידה או 2x או 4x. שטח הכיסוי של המשבצת נשאר ללא שינוי. הפרמטר הזה פועל רק עם ערכי scale של 2x או 4x. אין לזה השפעה על 1x מספר משבצות.

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

overlay: לא נכון	overlay: נכון

קובץ ה-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

ערך אסימון סשן שצריך לכלול בכל ה-API של אריחי המפה בבקשות.

expiry

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

tileWidth

הרוחב של המשבצות נמדד בפיקסלים.

tileHeight

הגובה של המשבצות, שנמדד בפיקסלים.

imageFormat

פורמט התמונה, יכול להיות png או jpeg.