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

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

region

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

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

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

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

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

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

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

يوفر هذا المثال تراكبًا مناسبًا للدمج مع صور القمر الصناعي. يحتوي هذا المثال على كلٍّ من خارطة طريق وتراكب "التجوّل الافتراضي". يتم عرض الخريطة الناتجة مع الأسماء والبيانات باللغة الإنجليزية، كما يتم قولها في الولايات المتحدة.

استجابة الرمز المميز للجلسة

ملف JSON التالي هو مثال على نص الاستجابة.

{
  "session": "IgAAAHGU9jnAU4KOAfwY3Bcd6eH_WxQsyocSBAdUnAr9pnvTTNXtF9c_27RBo94ytEXTDg",
  "expiry": "1361828036",
  "tileWidth": 256,
  "tileHeight": 256,
  "imageFormat": "png"
}

تحتوي القائمة التالية على تعريفات الحقول في نص الاستجابة.

session
قيمة الرمز المميّز للجلسة التي يجب تضمينها في جميع طلبات واجهة برمجة التطبيقات لمربّعات الخريطة.
expiry
سلسلة تحتوي على الوقت الذي تنتهي فيه صلاحية الرمز المميّز (بالثواني منذ تاريخ بدء الصلاحية) يكون الرمز المميّز للجلسة صالحًا لمدة أسبوعين من وقت إنشائه، ولكن قد تتغير هذه السياسة بدون إشعار.
tileWidth
يتم قياس عرض المربّعات بالبكسل.
tileHeight
يتم قياس ارتفاع المربّعات بالبكسل.
imageFormat
تنسيق الصورة، الذي يمكن أن يكون png أو jpeg