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

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

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

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

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

ستتعرّف على كيفية إجراء ما يلي:

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

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

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.3 متر لن يكون مناسبًا لشاحنة جرّار ومقطورة بارتفاع 4.1 متر. ومع ذلك، فإن الشاحنات الصندوقية الأصغر حجمًا التي يبلغ طولها حوالي 10 أقدام ستكون قادرة على التنقل في الممر السفلي. لذلك، من المهم تحديد سمات مركباتك بدقة.

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

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

‫vehicleInfo حقل كائن

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

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

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

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

رسوم العبور

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

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

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

عند ضبط 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"

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

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

تفسير ردّ computeRoutes

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

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

• الشكل الهندسي للمسار المرمّز: routes.polyline ويمكن استخدام ذلك لعرض المسار على الخريطة.
• المدة المقدَّرة للرحلة: routes.duration (بالثواني) تستخدم مدة رحلة توجيه المركبات الكبيرة نموذجًا جديدًا تم تدريبه على سرعات السفر المرصودة للشاحنات الفعلية على شبكة الطرق. ويمكن استخدامها أيضًا لاحتساب الوقت المقدَّر للوصول من خلال إضافة المدة المقدَّرة للرحلة إلى وقت المغادرة المتوقَّع.
• إجمالي مسافة المسار: routes.distanceMeters (بالأمتار)
• رمز المسار: routes.routeToken هذا رمز مميّز غير شفاف يمثّل المسار المحسوب بدقة. يمكنك تمرير هذا الرمز المميّز إلى حزمة تطوير البرامج (SDK) الخاصة بالتنقّل لضمان عرض المسار نفسه المخصّص للشاحنة للسائق. لمعرفة التفاصيل، يُرجى الاطّلاع على أدلة حزمة تطوير البرامج (SDK) للتنقّل على أجهزة 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 في حزمة تطوير البرامج (SDK) للتنقّل على أجهزة Android أو iOS.
• إجراء تحسين على مستوى الأسطول: استخدِم Route Optimization API مع ميزة "توجيه المركبات الكبيرة".
• مرجع واجهة برمجة التطبيقات: للاطّلاع على قائمة كاملة بجميع الحقول والقيم المحتملة، يُرجى مراجعة مرجع Routes API.