إنشاء مسارات وتقديرات لوقت الوصول للمركبات الكبيرة

ملاحظة: تتوفّر ميزة توجيه المركبات الكبيرة لمجموعة محدودة من العملاء. يُرجى التواصل معنا لإبداء اهتمامك.

الفئة المستهدَفة من هذا الدليل: يُرجى قراءة هذا الدليل إذا كنت مطوّرًا ينشئ خدمات لتخطيط الرحلات وتنفيذها باستخدام شاحنات أو مركبات كبيرة أخرى. تشمل حالات الاستخدام ذات الصلة احتساب أوقات السفر والمسافات، أو احتساب الوقت المقدّر للوصول، أو إنشاء مسارات سيتم استخدامها من خلال تطبيق ملاحة.

محتوى هذا الدليل: يوضّح هذا الدليل كيفية استخدام Routes API مع خدمة "توجيه المركبات الكبيرة" لطلب مسارات ومسافة السفر ووقت السفر المتوقّع وتقديرات وقت الوصول التي تأخذ في الاعتبار السمات المحدّدة للمركبة الكبيرة، مثل شاحنة تجارية أو حافلة ركاب.

للحصول على معلومات حول كيفية إجراء عمليات حسابية على مستوى أسطول المركبات الكبيرة باستخدام Route Optimization API، يُرجى الاطّلاع على مستندات Route Optimization Truck Routing.

أهداف الدورة التعليمية

ستتعرَّف على كيفية تنفيذ ما يلي:

• إنشاء طلب توجيه صالح
• حدِّد معلومات المركبة التي تستخدمها في الواقع، وذلك باستخدام الأبعاد والوزن والخصائص الأخرى.
• تفسير الردّ، بما في ذلك رمز المسار وعلامات أمان السفر

المتطلبات الأساسية

1. يجب إنشاء مشروعك على Google Cloud وتفعيل Routes API.
2. يجب توفير مشروعك لخدمة "توجيه المركبات الكبيرة". تتوفّر خدمة توجيه المركبات الكبيرة لمجموعة محدودة من العملاء، يُرجى التواصل معنا لطلب الوصول إلى هذه الخدمة

القيود

قبل البدء، يجب أن تكون على دراية بالقيود والمتطلبات التالية.

• التوفّر الجغرافي: تتوفّر ميزة توجيه المركبات الكبيرة في الولايات المتحدة الـ 48 المتجاورة (متاحة للجميع) واليابان (تجريبية). لا تتوفّر هذه الخدمة في ألاسكا أو هاواي أو الأقاليم التابعة للولايات المتحدة.
• نصائح القيادة والسلامة: يجب ألّا يعتمد السائقون بشكل كامل على المسارات التي تعرضها واجهة برمجة التطبيقات هذه لضمان السلامة أو الالتزام بالقانون. لا نضمن أن تكون الطرق مناسبة للمركبة، وقد يؤدي اتّباعها إلى تعرّض السائقين لمخاطر، مثل الجسور المنخفضة أو الطرق التي يُحظر فيها مرور المركبات الكبيرة.
• المسارات التي يتم تحديدها بأفضل جهد: في بعض الحالات، لا يمكن لواجهة برمجة التطبيقات العثور على مسار يلتزم بشكل كامل بقيود السفر. بدلاً من ذلك، تعرض الخدمة مسارًا "بأفضل ما يمكن"، وقد يمرّ هذا المسار بمناطق محظورة. تحدّد استجابة Routes API هذه الطرق بوضوح في الحقل routeRestrictionsPartiallyIgnored. لذا، عليك التخطيط لمسارك بعناية في هذه الحالات، ويُفضّل استخدام بيانات مصدر أخرى. لا تستخدِم مسارًا تم الإبلاغ عنه كمصدر وحيد للحقيقة عند التخطيط أو التنقّل.
• الميزات غير المتوافقة: لا يتيح توجيه المركبات الكبيرة استخدام ما يلي:
  • أسعار رسوم عبور الشاحنات
  • حدود السرعة
  • تحديد مسار المواد الخطرة المشعّة
• حدود الاستخدام: تخضع جميع الطلبات لحدود الطلبات في الثانية (QPS) العادية.

إنشاء طلب مسار شاحنات

للحصول على مسار شاحنة، عليك إرسال طلب HTTPS إلى نقطة نهاية في واجهة Routes API مع معلَمات محدّدة تصف مركبتك. تنطبق المفاهيم الواردة في هذا القسم على طلبات المسار الفردي ومصفوفة المسارات.

نقاط النهاية

يمكنك استخدام نقطتَي نهاية لتوجيه الشاحنات:

• computeRoutes: لحساب مسار واحد بين نقطة بداية ونقطة نهاية.
• ‫computeRouteMatrix: تحسب هذه الخدمة المسافة والمدة لمصفوفة من نقاط البداية ونقاط الوجهة، ولكنها لا تعرض خطًا متعدد الأضلاع للمسار.

مَعلمات الطلب الرئيسية

في نص الطلب، يجب تضمين المَعلمات التالية لتفعيل توجيه الشاحنات:

• travelMode: اضبط هذه القيمة على TRUCK.
• routingPreference: اضبط هذه القيمة على TRAFFIC_AWARE_OPTIMAL.
• routeModifiers: يحتوي هذا العنصر على العنصر vehicleInfo الذي تحدّد فيه سمات مركبتك. يتم وصف عنصر vehicleInfo بالتفصيل أدناه.

تحديد سمات المركبة

لإرسال طلب، يجب توفير نص الطلب مع كائن vehicleInfo يصف مركبتك. يمكنك اعتبار هذه المعلومات مواصفات تتطابق مع التفاصيل المادية لسيارتك الحقيقية. تتطلّب الخدمة هذه التفاصيل لعرض طرق تراعي القيود المفروضة على الطرق استنادًا إلى سمات مركبتك.

قياسات المركبة

يُرجى تقديم وزن المركبة بالكيلوغرام وأبعادها بالمليمتر، كما هو موضّح في أسماء الحقول. على سبيل المثال، يجب تقديم الارتفاع الإجمالي بوحدة المليمتر (totalHeightMm)، علمًا بأنّ أبعاد الشاحنات غالبًا ما يتم التعبير عنها بوحدة القدم أو المتر، لذا قد يتطلّب ذلك تحويل الوحدات.

التحويل من وحدات القياس الإمبراطورية إلى الوحدات المترية

عند التحويل من الوحدات الإنجليزية، يجب دائمًا مراعاة أبعاد مركبتك المحدّدة إلى جانب الحدود القصوى القياسية لحجم الطرق والأنفاق. وقد يكون ذلك مهمًا بشكل خاص مع القيم الكسرية. استنادًا إلى حجم المركبة الفعلي، يمكن أن يؤدي تقريب قيمة كسرية إلى توجيه مقيّد بشكل مفرط للمركبة.

على سبيل المثال:

• العرض: يبلغ عرض العديد من المقطورات في الولايات المتحدة 8 أقدام و6 بوصات، أي ما يعادل 2,590.8 ملم. يشير التقريب إلى 2,591 ملم إلى أنّ المركبة أكبر من 8 أقدام و6 بوصات، ما يصنّفها كمركبة كبيرة الحجم على الطرق الأمريكية. سيؤدي ذلك إلى إنشاء مسار تم احتسابه وفقًا لقيود مختلفة بشكل كبير عن القيود المقصودة.
• الارتفاع: لن يكون مسار يؤدي إلى أسفل جسر يبلغ ارتفاعه 3.35 متر مناسبًا لشاحنة جرّار عادية يبلغ ارتفاعها 4.11 متر. ومع ذلك، يمكن للشاحنات الصغيرة التي يبلغ طولها حوالي 3 أمتار التنقّل عبر الممر السفلي. وبناءً على ذلك، من المهم تحديد سمات مركبتك بدقة.

في ما يلي مقتطف رمز برمجي يعرض مثالاً على عنصر vehicleInfo:

"vehicleInfo": {
      "totalAxleCount": 5,
      "totalHeightMm": 4114,
      "totalLengthMm": 21945,
      "totalWidthMm": 2590,
      "totalWeightKg": 32658,
      "trailerInfo": [{
        "lengthMm": 16154
      }

حقول عناصر vehicleInfo

يعرض الجدول التالي جميع تعريفات المركبات والحِمل التي يمكنك إرسالها مع الطلب.

الحقل	الوصف	الملاحظات / القيم
totalHeightMm	الحد الأقصى لارتفاع المركبة	بالملليمتر، مع التقريب إلى أقرب عدد صحيح أصغر يمكنك الاطّلاع على التحويل من النظام الإمبراطوري إلى النظام المتري لمزيد من التفاصيل حول التقريب.
totalWidthMm	الحد الأقصى لعرض المركبة	بالملليمتر، مع التقريب إلى أقرب عدد صحيح أصغر
totalLengthMm	الطول الإجمالي للمركبة وأي مقطورات	بالملليمتر، مع التقريب إلى أقرب عدد صحيح أصغر
totalWeightKg	الوزن الإجمالي للمركبة (بما في ذلك المقطورات والحمولة)	بالكيلوغرام، مع التقريب إلى أقرب عدد صحيح أصغر
totalAxleCount	العدد الإجمالي للمحاور في المركبة وأي مقطورات	بالضبط.
‫trailerInfo (اختياري)	مصفوفة من العناصر، عنصر واحد لكل مقطع دعائي	يجب حذف هذه السمة إذا كانت المركبة لا تتضمّن مقطورات، مثل شاحنة نقل البضائع.
‫hazardousGoodsTypes (اختياري)	مصفوفة تحدّد أي مواد خطرة على متن الطائرة	EXPLOSIVES, GASES, FLAMMABLE, COMBUSTIBLE, ORGANIC, POISON, CORROSIVE, ASPIRATION_HAZARD, ENVIRONMENTAL_HAZARD, OTHER

استخدام أقنعة الحقول

للحصول على أفضل النتائج، أدرِج عنوان X-Goog-FieldMask في طلبك لتحديد الحقول التي تريدها في الردّ بدقة. تساهم حقول الإخفاء في تقليل وقت الاستجابة وتضمن تلقّي حقول الإرشادات المهمة. يجب تضمين routes.travelAdvisory.routeRestrictionsPartiallyIgnored في قناع الحقل على الأقل، لأنّ ذلك يشير إلى ما إذا كان المسار يتضمّن قيودًا واحدة أو أكثر تنطبق على مركبتك.

لمزيد من التفاصيل حول FieldMasks مع Routes API، يُرجى الاطّلاع على هذه المقالة.

رسوم العبور

لتفضيل المسارات التي لا تتضمّن رسومًا، حدِّد avoidTolls في السمة routeModifiers ضمن الطلب. لمزيد من المعلومات حول معدِّلات المسار، اطّلِع على مقالة تحديد ميزات المسار التي يجب تجنُّبها.

لا يضمن تحديد avoidTolls توفّر مسارات مجانية في الردّ. في بعض الحالات، يجب استخدام طريق برسوم عبور للتنقّل بين نقطة البداية ونقطة الوصول. إذا أدرجت routes.warnings في fieldmask لطلب بيانات من واجهة برمجة التطبيقات Routes، سيتم وضع تعليقات توضيحية مناسبة على المسارات التي تتضمّن طرقًا خاضعة لرسوم مرور ضمن هذا الحقل.

سلوكيات التوجيه الأخرى

عند ضبط travelMode على TRUCK، تعمل واجهة برمجة التطبيقات تلقائيًا على تحسين المسار بما يناسب قدرة المركبات الكبيرة على المناورة. تتجنّب المسارات التي يتم إنشاؤها المنعطفات على شكل حرف U، وتفضّل بشكل كبير الطرق السريعة والطرق الرئيسية على الطرق الأصغر. وليس عليك ضبط أي معلَمات أو معدِّلات إضافية لتفعيل هذه السلوكيات.

احتساب مسار واحد باستخدام computeRoutes

استخدِم نقطة النهاية computeRoutes لحساب مسار خاص بالشاحنات بين نقطة بداية واحدة ونقطة نهاية واحدة.

مثال على طلب computeRoutes

في ما يلي طلب curl كامل لشاحنة نموذجية نصف مقطورة. يتضمّن هذا المثال نقطة النهاية والعناوين ونص الطلب.

curl --location 'https://routes.googleapis.com/directions/v2:computeRoutes' \
--header 'Content-Type: application/json' \
--header 'X-Goog-Api-Key: YOUR_API_KEY' \
--header 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.routeToken,routes.travelAdvisory.routeRestrictionsPartiallyIgnored' \
--data '{
 "origin": {
    "location": {
      "latLng": {
        "latitude": 40.883274,
        "longitude": -74.704574
      }
    }
  },
  "destination": {
    "location": {
      "latLng": {
        "latitude": 40.991920,
        "longitude": -75.183371
      }
    }
  },
  "travelMode": "TRUCK",
  "routingPreference": "TRAFFIC_AWARE_OPTIMAL",
  "routeModifiers": {
    "vehicleInfo": {
      "totalAxleCount": 5,
      "totalHeightMm": 4114,
      "totalLengthMm": 21945,
      "totalWidthMm": 2590,
      "totalWeightKg": 32658,
      "trailerInfo": [{
        "lengthMm": 16154
      }]
    }
  }
}'

مثال على الردّ computeRoutes

هذا مثال على ردّ على الطلب السابق الموضّح أعلاه. يُرجى العِلم أنّه في العنصر travelAdvisory، لا يتم تضمين العلامة routeRestrictionsPartiallyIgnored. يشير ذلك إلى أنّ المسار غير مصنّف ويُعتقد أنّه يتوافق تمامًا مع سمات المركبة.

{
  "routes": [
    {
      "distanceMeters": 3426,
      "duration": "312s",
      "travelAdvisory": {},
      "routeToken": "CogCCogBChA7b39q54cKGCys_VXaDADjEhgszp8YhZFw0xvzm7SygpvCeIvJ7V0r6XIaJZ6BxNkMa_8HhhqlAci7hYMXi6UCpPgDW-yoAf8gzgHiEYyJAnoiAQU6AQFCB27cD9UCwwdKCMX2Ij7RpxY_eAGqARdUNENZWllLS0tJRGZ2T01QMVptSjRBaxAEGmIKYBIWCAAQAxAGEBMQEhgCQgQaAggFSgIIASIbChdUNENZWmVTc0o0RGZ2T01QMVptSjRBa3ABKAQyJ3RydWNraW5nOjpzZW1pLXRyYWlsZXItdHJ1Y2staGVhdnktc29mdCIVAOzExFsGGGfjVIIY7GXjYbPyONS8EiQiInRydWNraW5nOjpzZW1pLXRyYWlsZXItdHJ1Y2staGVhdnk"
    }
  ]
}

تفسير الردّ computeRoutes

يؤدي الطلب الناجح إلى نقطة النهاية computeRoutes إلى عرض عنصر استجابة JSON يحتوي على مسار واحد أو أكثر.

حقول الردّ الرئيسية

• هندسة المسار المرمّزة: routes.polyline. ويمكن استخدامها لعرض المسار على خريطة.
• مدة الرحلة المقدَّرة: routes.duration (بالثواني) تستخدم مدة رحلة التوجيه للمركبات الكبيرة نموذجًا جديدًا تم تدريبه على سرعات التنقّل المرصودة للشاحنات الفعلية على شبكة الطرق. يمكن استخدامها أيضًا لاحتساب الوقت المقدّر للوصول من خلال إضافة مدة الرحلة المقدّرة إلى وقت المغادرة المتوقّع.
• إجمالي مسافة المسار: routes.distanceMeters (بالمتر)
• الرمز المميّز للمسار: routes.routeToken هذا رمز مميز مبهم يمثّل مسار الرحلة المحسوب بدقة. يمكنك تمرير هذا الرمز المميّز إلى حزمة تطوير البرامج (SDK) الخاصة بخدمة Navigation للتأكّد من أنّ السائق يرى المسار نفسه المخصّص للشاحنات. للحصول على التفاصيل، راجِع أدلة حزمة تطوير البرامج للتنقّل على Android أو iOS.

التحقّق من علامات أمان المسار

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

يعمل هذا الحقل كعلامة للإجابة عن السؤال: "هل تم وضع علامة على هذا المسار للإشارة إلى مشكلة محتملة؟"

• false(أو تم حذفه من الرد): لم يتم الإبلاغ عن المسار. عثر النظام على مسار يُعتقد أنّه متوافق تمامًا مع المَعلمات التي قدّمتها في الطلب.
• true: تم وضع علامة على المسار. تعذّر على النظام العثور على مسار متوافق تمامًا، لذا تم عرض مسار "بأفضل جهد" قد لا يكون آمنًا أو قانونيًا. يجب توخّي الحذر الشديد عند استخدام هذا المسار.

حساب مصفوفة مسارات (computeRouteMatrix)

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

لاستخدام computeRouteMatrix، عليك تحديد vehicleInfo ضمن كل عنصر origin بدلاً من تحديدها في جذر الطلب.

مثال على طلب computeRouteMatrix

{
  "origins": [
    {
      "waypoint": { "location": { "latLng": { "latitude": 32.77, "longitude": -96.85 }}},
      "routeModifiers": { "vehicleInfo": { /* ...vehicle attributes... */ } }
    },
    {
      "waypoint": { "location": { "latLng": { "latitude": 33.61, "longitude": -112.11 }}},
      "routeModifiers": { "vehicleInfo": { /* ...vehicle attributes... */ } }
    }
  ],
  "destinations": [
    { "waypoint": { "location": { "latLng": { "latitude": 35.02, "longitude": -106.64 }}}},
    { "waypoint": { "location": { "latLng": { "latitude": 29.77, "longitude": -95.40 }}}}
  ],
  "travelMode": "TRUCK",
  "routingPreference": "TRAFFIC_AWARE_OPTIMAL"
}

مثال على الردّ computeRouteMatrix

الردّ هو عبارة عن مصفوفة يحتوي كل عنصر فيها على المدة وdistanceMeters لزوج واحد من نقطة الانطلاق والوجهة.

[
  {
    "originIndex": 0,
    "destinationIndex": 1,
    "status": {},
    "distanceMeters": 392372,
    "duration": "14037s",
    "condition": "ROUTE_EXISTS"
  },
  { ... }
]

الخطوات التالية

• توفير اتجاهات مفصّلة: تعرَّف على كيفية استخدام routeToken في حزمة تطوير البرامج للتنقّل على Android أو iOS.
• إجراء تحسين على مستوى أسطول المركبات: استخدِم Route Optimization API مع Large Vehicle Routing.
• مرجع واجهة برمجة التطبيقات: للحصول على قائمة كاملة بجميع الحقول والقيم المحتملة، اطّلِع على مرجع واجهة Routes API.