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

الرمز المميّز للجلسة هو جزء من البيانات (UUID) الذي يتم استخدامه في طلبات REST لتحديد الجلسة، وهي سلسلة من عمليات تبادل الرسائل ذات الصلة. يجب تضمين رمز أمان الجلسة في جميع طلبات الحصول على مربّعات ثنائية الأبعاد وصور "التجوّل الافتراضي". يمكنك تضمينها كقيمة لمَعلمة session يتم إلحاقها بجميع عناوين URL للطلبات.

في Map Tiles API، يمثّل رمز الجلسة مجموعة محدّدة من options. display. وهذا يعني أنّه ليس عليك إرسال مجموعة من خيارات العرض مع كل طلب مربّع. يمكنك استخدام رمز الجلسة نفسه في عملاء متعدّدين. يكون الرمز المميّز للجلسة صالحًا حاليًا لمدة أسبوعين من وقت إصداره، ولكن قد يتغيّر ذلك. يمكنك متى شئت التحقّق من وقت انتهاء صلاحية رمز علامة التمييز للجلسة من خلال الاطّلاع على الحقل expiry في رسالة الاستجابة.

ملاحظة: يجب استخدام الرموز المميّزة للجلسة للحصول على المربّعات ثنائية الأبعاد ومربّعات "التجوّل الافتراضي"، ولكن ليس للحصول على المربّعات الثلاثية الأبعاد.

طلب الرمز المميّز للجلسة

لطلب رمز مميز للجلسة، أرسِل طلب POST عبر HTTPS إلى نقطة النهاية 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

معرّف منطقة Common Locale Data Repository (حرفان كبيران) يمثّل الموقع الجغرافي للمستخدم مثلاً: US

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

imageFormat

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

scale

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

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

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

عامل التحجيم 1x	عامل التحجيم 2x

highDpi

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

overlay: false	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.