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

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

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

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

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

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

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

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

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

القيود

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

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

احتساب مسار واحد باستخدام 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) الخاصة بالتنقّل لضمان عرض المسار نفسه المخصّص للشاحنة للسائق. لمزيد من التفاصيل، يُرجى الاطّلاع على أدلة حزمة تطوير البرامج (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 مع Large Vehicle Routing.
• مرجع واجهة برمجة التطبيقات: للحصول على قائمة كاملة بجميع الحقول والقيم المحتملة، يُرجى الاطّلاع على مرجع Routes API.