الرمز المميّز للجلسة هو جزء من البيانات (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 إلى النقاط لكل بوصة، ويعني ارتفاع النقاط لكل بوصة (DPI) أنه يتم عرض المربّعات باستخدام عدد أكبر من النقاط لكل بوصة مقارنةً بالبوصة العادية. إذا كانتtrue، يتم ضرب عدد البكسل في كل من الأبعاد x وy في عامل القياس (أي 2x أو 4x). تظل منطقة تغطية المربّع بدون تغيير. لا تعمل هذه المعلمة إلا مع قيمscaleالتي تكون 2x أو 4x. ليس له أي تأثير على مربعات مقياس 1x.
| عامل المقياس 1x | عامل المقياس 2x عدد النقاط لكل بوصة (DPI) عالية |
|---|---|
layerTypesمصفوفة من القيم تحدد أنواع الطبقات التي تمت إضافتها إلى الخريطة. القيم الصالحة هي:
layerRoadmap- مطلوب عند تحديد
terrainكنوع الخريطة. ويمكن أيضًا تضمينها اختياريًا على نوع الخريطةsatellite. ليس له أي تأثير في مربّعات خارطة الطريق. layerStreetview- تعرض الشوارع والمواقع الجغرافية التي تم تفعيل ميزة "التجوّل الافتراضي" فيها باستخدام مخططات زرقاء على الخريطة.
layerTraffic- عرض أحوال حركة المرور الحالية
stylesيشير ذلك المصطلح إلى مصفوفة من كائنات نمط JSON التي تحدِّد مظهر ميزات الخريطة ومستوى تفاصيلها، مثل الطرق والمنتزهات والمناطق المبنية. يُستخدم النمط لتخصيص خريطة Google الأساسية القياسية. تكون المعلمة
stylesصالحة فقط إذا كان نوع الخريطةroadmap. للاطّلاع على بنية النمط الكاملة، راجِع مرجع الأنماط.overlayقيمة منطقية تحدد ما إذا كان يجب عرض
layerTypesكتراكب منفصل، أو دمجها مع الصور الأساسية. أما عندماtrue، فلا يتم عرض الخريطة الأساسية. إذا لم تكن قد حدّدت أيlayerTypes، سيتم تجاهل هذه القيمة.
على سبيل المثال، عند طلب نوع الخريطة satellite مع طبقة layerRoadmap، وضبط overlay على false يؤدّي إلى ظهور مربّعات مكافئة لنوع الخريطة hybrid المستخدَم في واجهة برمجة تطبيقات JavaScript للخرائط (الصورة على اليمين). عند ضبط النوع 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" }
]
}
]
}
يقدم هذا المثال تراكبًا مناسبًا للدمج مع صور الأقمار الصناعية. يحتوي المثال على خارطة طريق وتراكب صور "تجوّل افتراضي". يتم عرض الخريطة الناتجة مع الأسماء والبيانات باللغة الإنجليزية، كما هي مكتوب في الولايات المتحدة.
apiOptions: مصفوفة من القيم تحدد خيارات إضافية لتطبيقها.
الخيارات المتاحة هي:
MCYJ5E517XR2JC- الاشتراك في نمط الخريطة الجديد. خلال فترة التفعيل، سيتم تطبيق النمط الحالي على طلباتك ما لم يتم تحديد هذه القيمة.
ردّ الرمز المميّز للجلسة
مثال على نص الاستجابة هو JSON التالي.
{
"session": "IgAAAHGU9jnAU4KOAfwY3Bcd6eH_WxQsyocSBAdUnAr9pnvTTNXtF9c_27RBo94ytEXTDg",
"expiry": "1361828036",
"tileWidth": 256,
"tileHeight": 256,
"imageFormat": "png"
}
تحتوي القائمة التالية على تعريفات للحقول في نص الاستجابة.
session- قيمة للرمز المميّز للجلسة يجب تضمينها في جميع طلبات واجهة برمجة التطبيقات Map Tiles API
expiry- سلسلة تحتوي على الوقت (بالثواني منذ الحقبة) الذي تنتهي فيه صلاحية الرمز المميّز. يكون الرمز المميز للجلسة صالحًا لمدة أسبوعين من وقت إنشائه، ولكن هذه السياسة قد تتغير بدون إشعار.
tileWidth- عرض المربّعات بالبكسل.
tileHeight- يتم قياس ارتفاع المربّعات بالبكسل.
imageFormat- تنسيق الصورة، والذي يمكن أن يكون
pngأوjpeg.