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

الرمز المميز للجلسة هو جزء من البيانات ( UUID) يُستخدم في استدعاءات REST لتحديد الجلسة: a سلسلة من تبادلات الرسائل ذات الصلة. يجب تضمين رمز مميز للجلسة في جميع طلبات للحصول على مربّعات ثنائية الأبعاد وصور "التجوّل الافتراضي" يتم إدراجه كقيمة معلَمة 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، تكون عدد وحدات البكسل في كل من الأبعاد (س) و(ص) تم ضربه في المقياس العامل (أي 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: خطأ	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.