استخدام الرموز المميزة للجلسات مع 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

مشاهد بانورامية في "التجوّل الافتراضي" لمزيد من المعلومات، يُرجى الاطّلاع على ألواح "التجوّل الافتراضي".

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.