الرمز المميّز للجلسة هو جزء من البيانات (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
علامة لغة ITF التي تحدّد اللغة المستخدَمة لعرض المعلومات على المربّعات. على سبيل المثال، تحدّد السمة
en-US
اللغة الإنجليزية على أنّها المستخدمة في الولايات المتحدة.region
معرّف لمستودع بيانات اللغة المحلية المشترك (حرفان كبيران) يمثّل الموقع الجغرافي للمستخدم مثلاً:
US
حقول اختيارية
imageFormat
- يحدد تنسيق الملف المطلوب عرضه. والقيم الصالحة هي
jpeg
أوpng
. لا تدعم ملفات JPEG الشفافية، لذلك لا يوصى بها لمربعات التراكب. إذا لم تحدّدimageFormat
، سيتم اختيار أفضل تنسيق للمربّع تلقائيًا. scale
يمكنك زيادة حجم عناصر الخريطة (مثل تصنيفات الطرق)، مع الاحتفاظ بحجم المربّع ومساحة التغطية للمربّع التلقائي. تؤدي زيادة المقياس أيضًا إلى تقليل عدد التسميات على الخريطة، مما يقلل من الفوضى. والقيم التالية هي قيم
scale
صالحة:scaleFactor1x
: الخيار التلقائي.scaleFactor2x
: لمضاعفة حجم التصنيف وإزالة تصنيفات الميزات الثانوية.scaleFactor4x
: مضاعفة حجم التصنيف بأربعة وإزالة تصنيفات الميزات الثانوية.
توضح الأمثلة التالية تأثير تحجيم عناصر الخريطة.
عامل المقياس 1x | عامل المقياس 2x |
---|---|
highDpi
- يحدد هذا الإعداد ما إذا كان سيتم عرض مربّعات عالية الدقة. إذا تمت زيادة عامل المقياس،
يتم استخدام
highDpi
لزيادة حجم المربّع. عادةً، تؤدي زيادة عامل المقياس إلى تكبير المربّع الناتج إلى صورة بالحجم نفسه، ما يقلّل من الجودة. باستخدامhighDpi
، يزداد أيضًا الحجم الناتج، ما يحافظ على الجودة. يشير الاختصار DPI إلى النقاط لكل بوصة، فيما تعني النقاط العالية لكل بوصة أنه يتم عرض المربع باستخدام عدد أكبر من النقاط لكل بوصة من المعتاد. إذا كانتtrue
، يتم ضرب عدد وحدات البكسل في كل من البُعدين "س" و"ص" في عامل المقياس (أي 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
المستخدَم في 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" }
]
}
]
}
يوفر هذا المثال تراكبًا مناسبًا للدمج مع صور القمر الصناعي. يحتوي هذا المثال على كلٍّ من خارطة طريق وتراكب "التجوّل الافتراضي". يتم عرض الخريطة الناتجة مع الأسماء والبيانات باللغة الإنجليزية، كما يتم قولها في الولايات المتحدة.
apiOptions
: مصفوفة من القيم تحدّد خيارات إضافية لتطبيقها.
الخيارات المتاحة هي:
MCYJ5E517XR2JC
- تفعيل نمط الخريطة الجديد. وخلال فترة التفعيل، سيتم تطبيق النمط الحالي على طلباتك ما لم يتم تحديد هذه القيمة.
استجابة الرمز المميز للجلسة
ملف JSON التالي هو مثال على نص الاستجابة.
{
"session": "IgAAAHGU9jnAU4KOAfwY3Bcd6eH_WxQsyocSBAdUnAr9pnvTTNXtF9c_27RBo94ytEXTDg",
"expiry": "1361828036",
"tileWidth": 256,
"tileHeight": 256,
"imageFormat": "png"
}
تحتوي القائمة التالية على تعريفات الحقول في نص الاستجابة.
session
- قيمة الرمز المميّز للجلسة التي يجب تضمينها في جميع طلبات واجهة برمجة التطبيقات لمربّعات الخريطة.
expiry
- سلسلة تحتوي على الوقت الذي تنتهي فيه صلاحية الرمز المميّز (بالثواني منذ تاريخ بدء الصلاحية) يكون الرمز المميّز للجلسة صالحًا لمدة أسبوعين من وقت إنشائه، ولكن قد تتغير هذه السياسة بدون إشعار.
tileWidth
- يتم قياس عرض المربّعات بالبكسل.
tileHeight
- يتم قياس ارتفاع المربّعات بالبكسل.
imageFormat
- تنسيق الصورة، الذي يمكن أن يكون
png
أوjpeg