الرمز المميّز للجلسة هو جزء من البيانات (UUID) يُستخدَم في طلبات REST لتحديد جلسة، وهي سلسلة من عمليات تبادل الرسائل ذات الصلة. يجب تضمين رمز مميّز للجلسة في جميع طلبات الحصول على مربّعات ثنائية الأبعاد وصور "التجوّل الافتراضي".
ويمكنك تضمينه كقيمة لمَعلمة 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- صور بانوراما في "التجوّل الافتراضي" لمزيد من المعلومات، يُرجى الاطّلاع على مربّعات "التجوّل الافتراضي".
languageعلامة لغة IETF تحدّد اللغة المستخدَمة لعرض المعلومات على المربّعات. على سبيل المثال، يحدّد الرمز
en-USاللغة الإنجليزية كما يتم التحدث بها في الولايات المتحدة.regionمعرّف منطقة مستودع بيانات اللغة الشائعة (حرفان كبيران) يمثّل الموقع الجغرافي للمستخدم. مثلاً:
US
حقول اختيارية
imageFormat- يحدّد تنسيق الملف المطلوب عرضه. القيمتان الصالحتان هما
jpegأوpng. لا تتيح ملفات JPEG الشفافية، لذا لا يُنصح باستخدامها في مربّعات التراكب. في حال عدم تحديدimageFormat، سيتم اختيار أفضل تنسيق للقسم تلقائيًا. scaleيؤدي هذا الخيار إلى زيادة حجم عناصر الخريطة (مثل تصنيفات الطرق)، مع الاحتفاظ بحجم المربّع ومنطقة التغطية للمربّع التلقائي. تؤدي زيادة المقياس أيضًا إلى تقليل عدد التصنيفات على الخريطة، مما يقلل من الفوضى. القيم التالية هي قيم صالحة لسمة
scale:-
scaleFactor1x: الإعداد التلقائي -
scaleFactor2x: يضاعف حجم التصنيف ويزيل تصنيفات الميزات الثانوية. -
scaleFactor4x: يضاعف حجم التصنيف أربع مرات ويزيل تصنيفات المعالم الثانوية.
-
توضّح الأمثلة التالية تأثير تغيير حجم عناصر الخريطة.
| عامل القياس 1x | عامل القياس 2x |
|---|---|
 |
 |
highDpi- تحدّد هذه المَعلمة ما إذا كان سيتم عرض مربّعات عالية الدقة. في حال زيادة عامل القياس، يتم استخدام
highDpiلزيادة حجم المربّع. عادةً، تؤدي زيادة عامل القياس إلى تكبير المربّع الناتج إلى صورة بالحجم نفسه، ما يقلل من الجودة. باستخدام ميزة "highDpi"، يتم أيضًا زيادة حجم الصورة الناتجة مع الحفاظ على جودتها. يرمز الاختصار DPI إلى النقاط لكل بوصة، وتعني النقاط العالية لكل بوصة أنّ المربّع يتم عرضه باستخدام نقاط لكل بوصة أكثر من المعتاد. إذا كانت القيمةtrue، يتم ضرب عدد وحدات البكسل في كل من البُعدين x وy في عامل القياس (أي 2x أو 4x). تبقى منطقة تغطية المربّع بدون تغيير. لا تعمل هذه المَعلمة إلا مع قيمscaleالتي تبلغ 2x أو 4x. ولا يؤثّر في المربّعات التي تستخدم المقياس 1x.
| عامل القياس 1x | عامل القياس 2x High DPI |
|---|---|
|
 |
layerTypesمصفوفة من القيم تحدّد أنواع الطبقات المُضافة إلى الخريطة القيم الصالحة هي:
layerRoadmap- مطلوبة في حال تحديد
terrainكنوع الخريطة. ويمكن أيضًا اختياريًا تراكبها على نوع الخريطةsatellite. ولا يؤثّر في مربّعات خريطة الطريق. layerStreetview- تعرض هذه الطبقة الشوارع والمواقع الجغرافية التي تتوفّر فيها ميزة "التجوّل الافتراضي" باستخدام خطوط زرقاء على الخريطة.
layerTraffic- يعرض هذا الخيار أحوال حركة المرور الحالية.
stylesمصفوفة من عناصر نمط JSON التي تحدّد مظهر ومستوى تفاصيل عناصر الخريطة، مثل الطرق والمتنزهات والمناطق المبنية. يتم استخدام التصميم لتخصيص الخريطة الأساسية العادية من Google. تكون المَعلمة
stylesصالحة فقط إذا كان نوع الخريطة هوroadmap. للاطّلاع على البنية الكاملة للنمط، يُرجى مراجعة مرجع النمط.overlayقيمة منطقية تحدّد ما إذا كان يجب عرض
layerTypesكتراكب منفصل أو دمجه مع الصور الأساسية. عندما تكون قيمة السمةtrue، لا يتم عرض الخريطة الأساسية. إذا لم تحدّد أيlayerTypes، سيتم تجاهل هذه القيمة.
على سبيل المثال، يؤدي طلب نوع الخريطة satellite مع طبقة layerRoadmap وضبط overlay على false إلى الحصول على مربّعات مكافئة لنوع الخريطة hybrid المستخدَم في Maps JavaScript API (الصورة اليمنى). يؤدي استخدام أنواع الخرائط والطبقات نفسها مع ضبط overlay على true إلى ظهور مربّع شفاف مع تراكب خريطة، تم تصميمه بشكل مناسب للتراكب فوق صور القمر الصناعي (الصورة اليسرى).
overlay: false |
overlay: 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.