استخدام الرموز المميزة للجلسات مع Map Tiles API

مطوّرو المنطقة الاقتصادية الأوروبية

رمز الجلسة المميّز هو جزء من البيانات (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
صور بانورامية من Street View. لمزيد من المعلومات، راجع بلاطات عرض الشارع.
language

علامة لغة IETF التي تحدد اللغة المستخدمة لعرض المعلومات على المربعات. على سبيل المثال، يحدّد الرمز en-US اللغة الإنجليزية كما يتم التحدّث بها في الولايات المتحدة.

region

معرف منطقة مستودع بيانات الموقع المشترك (حرفان كبيران) يمثل الموقع الفعلي للمستخدم. مثلاً: US

الحقول الاختيارية

imageFormat
تحدّد هذه السمة تنسيق الملف الذي سيتم عرضه. القيم الصالحة هي jpeg أو png. لا تتوافق ملفات JPEG مع الشفافية، لذا لا يُنصح باستخدامها مع مربّعات التراكب. إذا لم تحدّد imageFormat، سيتم تلقائيًا اختيار أفضل تنسيق للمربّع.
scale

تزيد هذه السمة حجم عناصر الخريطة (مثل تصنيفات الطرق)، مع الاحتفاظ بحجم المربّع ومساحة التغطية للمربّع التلقائي. تؤدي زيادة المقياس أيضًا إلى تقليل عدد التصنيفات على الخريطة، ما يقلّل من الازدحام. في ما يلي قيم scale الصالحة:

  • scaleFactor1x: القيمة التلقائية
  • ‫scaleFactor2x: يضاعف حجم التصنيف ويزيل تصنيفات المعالم الثانوية.
  • ‫scaleFactor4x: يضاعف حجم التصنيف أربع مرات ويزيل تصنيفات الميزات الثانوية.

توضّح الأمثلة التالية تأثير تغيير حجم عناصر الخريطة.

عامل التحجيم 1x عامل التحجيم 2x
خريطة تعرض عامل القياس 1x خريطة تعرض عامل التحجيم 2x
highDpi
تحدّد هذه السمة ما إذا كان سيتم عرض مربّعات بدقة عالية. في حال زيادة عامل المقياس، يتم استخدام highDpi لزيادة حجم المربّع. في العادة، تؤدي زيادة عامل القياس إلى تكبير المربّع الناتج إلى صورة بالحجم نفسه، ما يؤدي إلى خفض الجودة. باستخدام highDpi، يزداد الحجم الناتج أيضًا، ما يحافظ على الجودة. يشير مصطلح DPI إلى "النقاط في البوصة"، ويعني مصطلح High DPI أنّ المربّع يتم عرضه باستخدام عدد أكبر من النقاط في البوصة مقارنةً بالحالة العادية. إذا كانت القيمة true، يتم ضرب عدد وحدات البكسل في كل من البُعدَين x وy في عامل القياس (أي 2x أو 4x). لن تتغيّر منطقة تغطية البلاطة. لا تعمل هذه المَعلمة إلا مع قيم scale التي تبلغ 2x أو 4x. ليس لهذا الإعداد أي تأثير في المربّعات ذات المقياس 1x.
عامل التحجيم 1x عامل التحجيم 2x High DPI
خريطة معروضة بدقة عادية الخريطة معروضة بدقة عالية تبلغ ضعف دقة 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
تم ضبط قيمة التراكب على "خطأ" تم ضبط Overlay على "صحيح"

في ما يلي مثال على نص طلب نموذجي يحتوي على الحقول المطلوبة والاختيارية.

{
  "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