از نشانه‌های جلسه با Map Tiles API استفاده کنید

توکن جلسه، قطعه داده‌ای ( UUID ) است که در فراخوانی‌های REST برای شناسایی یک جلسه - مجموعه‌ای از تبادل پیام‌های مرتبط - استفاده می‌شود. شما باید یک توکن جلسه را در تمام درخواست‌های مربوط به کاشی‌های دوبعدی و تصاویر نمای خیابان (Street View) قرار دهید. شما آن را به عنوان مقدار پارامتر session که به تمام URLهای درخواست اضافه می‌شود، قرار می‌دهید.

در API مربوط به کاشی‌های نقشه، یک توکن جلسه (session token) نشان‌دهنده‌ی مجموعه‌ای تعریف‌شده از گزینه‌های نمایش است. این بدان معناست که شما مجبور نیستید مجموعه‌ای از گزینه‌های نمایش را با هر درخواست کاشی ارسال کنید. می‌توانید از یک توکن جلسه (session token) در چندین کلاینت استفاده کنید. یک توکن جلسه در حال حاضر به مدت دو هفته از زمان صدور آن معتبر است، اما این ممکن است تغییر کند. شما همیشه می‌توانید زمان انقضای یک توکن جلسه را با نگاه کردن به فیلد 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

کاشی‌های نقشه رنگی استاندارد گوگل مپ.

satellite

تصاویر ماهواره‌ای.

terrain

تصاویر عوارض زمین. هنگام انتخاب terrain به عنوان نوع نقشه، باید نوع لایه layerRoadmap (که در بخش فیلدهای اختیاری توضیح داده شده است) را نیز وارد کنید.

streetview

پانوراماهای نمای خیابان. برای اطلاعات بیشتر، به کاشی‌های نمای خیابان مراجعه کنید.

language

یک برچسب زبان IETF که زبان مورد استفاده برای نمایش اطلاعات روی کاشی‌ها را مشخص می‌کند. برای مثال، en-US زبان انگلیسی را آنطور که در ایالات متحده صحبت می‌شود، مشخص می‌کند.

region

یک شناسه منطقه مخزن داده‌های محلی مشترک (دو حرف بزرگ) که نشان دهنده موقعیت فیزیکی کاربر است. به عنوان مثال، US .

فیلدهای اختیاری

imageFormat

فرمت فایلی که باید برگردانده شود را مشخص می‌کند. مقادیر معتبر jpeg یا png هستند. فایل‌های JPEG از شفافیت پشتیبانی نمی‌کنند، بنابراین برای کاشی‌های روکش توصیه نمی‌شوند. اگر imageFormat را مشخص نکنید، بهترین فرمت برای کاشی به طور خودکار انتخاب می‌شود.

scale

اندازه عناصر نقشه (مانند برچسب‌های جاده) را افزایش می‌دهد، در حالی که اندازه کاشی و ناحیه پوشش کاشی پیش‌فرض را حفظ می‌کند. افزایش مقیاس همچنین تعداد برچسب‌ها روی نقشه را کاهش می‌دهد که باعث کاهش شلوغی می‌شود. مقادیر زیر مقادیر scale معتبر هستند:

• scaleFactor1x : مقدار پیش‌فرض.
• scaleFactor2x : اندازه برچسب را دو برابر می‌کند و برچسب‌های ویژگی‌های جزئی را حذف می‌کند.
• scaleFactor4x : اندازه برچسب را چهار برابر می‌کند و برچسب‌های ویژگی‌های جزئی را حذف می‌کند.

مثال‌های زیر تأثیر مقیاس‌بندی عناصر نقشه را نشان می‌دهند.

ضریب مقیاس ۱x	ضریب مقیاس ۲x

highDpi

مشخص می‌کند که آیا کاشی‌هایی با وضوح بالا برگردانده شوند یا خیر. اگر ضریب مقیاس افزایش یابد، از highDpi برای افزایش اندازه کاشی استفاده می‌شود. معمولاً افزایش ضریب مقیاس، کاشی حاصل را به تصویری با همان اندازه تبدیل می‌کند که کیفیت را کاهش می‌دهد. با highDpi ، اندازه حاصل نیز افزایش می‌یابد و کیفیت حفظ می‌شود. DPI مخفف Dots per Inch است و High DPI به این معنی است که کاشی با استفاده از نقاط بیشتری در هر اینچ نسبت به حالت عادی رندر می‌شود. اگر true ، تعداد پیکسل‌ها در هر یک از ابعاد x و y در ضریب مقیاس (یعنی 2x یا 4x) ضرب می‌شود. مساحت پوشش کاشی بدون تغییر باقی می‌ماند. این پارامتر فقط با مقادیر scale 2x یا 4x کار می‌کند. هیچ تاثیری بر کاشی‌های با مقیاس 1x ندارد.

ضریب مقیاس ۱x	ضریب مقیاس ۲ برابر DPI بالا

layerTypes

آرایه‌ای از مقادیر که انواع لایه‌های اضافه شده به نقشه را مشخص می‌کند. مقادیر معتبر عبارتند از:

layerRoadmap

اگر نوع نقشه را terrain تعیین کنید، الزامی است. همچنین می‌تواند به صورت اختیاری روی نوع نقشه satellite قرار گیرد. هیچ تاثیری روی کاشی‌های نقشه راه ندارد.

layerStreetview

خیابان‌ها و مکان‌های دارای قابلیت نمای خیابان را با استفاده از خطوط آبی روی نقشه نشان می‌دهد.

layerTraffic

وضعیت ترافیک فعلی را نمایش می‌دهد.

styles

آرایه‌ای از اشیاء سبک JSON که ظاهر و سطح جزئیات ویژگی‌های نقشه مانند جاده‌ها، پارک‌ها و مناطق مسکونی را مشخص می‌کند. از سبک‌بندی برای سفارشی‌سازی نقشه پایه استاندارد گوگل استفاده می‌شود. پارامتر styles فقط در صورتی معتبر است که نوع نقشه roadmap باشد. برای مشاهده سینتکس کامل سبک، به مرجع سبک مراجعه کنید.

overlay

یک مقدار بولی که مشخص می‌کند آیا layerTypes باید به عنوان یک پوشش جداگانه رندر شوند یا با تصاویر پایه ترکیب شوند. وقتی true ، نقشه پایه نمایش داده نمی‌شود. اگر هیچ layerTypes تعریف نکرده باشید، این مقدار نادیده گرفته می‌شود.

برای مثال، درخواست یک نوع نقشه satellite با لایه layerRoadmap و تنظیم overlay روی false منجر به ایجاد کاشی‌هایی معادل با نوع نقشه hybrid مورد استفاده در Maps JavaScript API می‌شود (تصویر سمت چپ). همان نقشه و انواع لایه با تنظیم 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" }
      ]
    }
  ]
}

این مثال یک پوشش مناسب برای ترکیب با تصاویر ماهواره‌ای ارائه می‌دهد. این مثال شامل پوشش نقشه راه و نمای خیابان است. نقشه حاصل با نام‌ها و داده‌ها به زبان انگلیسی، همانطور که در ایالات متحده صحبت می‌شود، ارائه می‌شود.

پاسخ توکن جلسه

JSON زیر یک نمونه از بدنه پاسخ است.

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

لیست زیر شامل تعاریف فیلدهای موجود در بدنه پاسخ است.

session

یک مقدار توکن جلسه که باید در تمام درخواست‌های API مربوط به Map Tiles خود لحاظ کنید.

expiry

رشته‌ای که شامل زمان (به ثانیه از زمان شروع) انقضای توکن است. یک توکن جلسه به مدت دو هفته از زمان ایجاد آن معتبر است، اما این خط‌مشی ممکن است بدون اطلاع قبلی تغییر کند.

tileWidth

عرض کاشی‌ها بر حسب پیکسل اندازه‌گیری می‌شود.

tileHeight

ارتفاع کاشی‌ها بر حسب پیکسل اندازه‌گیری می‌شود.

imageFormat

فرمت تصویر، که می‌تواند png یا jpeg باشد.