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

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

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

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

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

כדי לבקש אסימון סשן, צריך לשלוח בקשת 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 (כפי שמתואר בקטע Optional שדות).

streetview

פנורמות Street View. למידע נוסף, קראו את משבצות Street View.

language

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

region

מזהה אזור (שתי אותיות רישיות) ב-Common Location Data Repository שמייצג את המיקום הפיזי של המשתמש. לדוגמה: US.

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

imageFormat

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

scale

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

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

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

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

highDpi

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

גורם קנה מידה 1x	גורם קנה מידה 2x 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: לא נכון	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" }
      ]
    }
  ]
}

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

apiOptions: מערך ערכים שמציין אפשרויות נוספות ליישום. האפשרויות הנתמכות הן:

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

תגובה לאסימון הסשן

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

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

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

session

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

expiry

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

tileWidth

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

tileHeight

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

imageFormat

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