التعامل مع بيانات الرحلات

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

قراءة حمولة البيانات

ترسِل "خرائط Google" أو Waze حمولات بيانات الرحلة إلى خوادم Navigation Connect عندما يبدأ السائق التنقّل، وبشكل دوري على طول المسار (كل 60 ثانية تلقائيًا)، وعند وصول السائق إلى الوجهة. تحتوي كل رسالة JSON على بيانات الرحلة ذات الصلة، بما في ذلك الإحداثيات التي تم ضبطها على الطريق والمسافة المقطوعة والوقت المقدَّر للوصول (ETA). بما أنّ هذه التعديلات تعكس المسار النشط في الوقت الفعلي للسائق، قد تختلف عن المسارات التي تم احتسابها مسبقًا من قِبل النظام الخلفي (راجِع الأسئلة الشائعة).

تعرض عينة التعليمات البرمجية التالية حمولة بيانات الرحلة عندما يبدأ السائق التنقّل لرحلة من King's Cross إلى Central St. Giles.

{
  "name": "projects/123456/trips/221B9CD6-4146-4CBF-9556-853817654938",
  "state": "ENROUTE",
  "execution": {
    "origin": {
      "point": {
        "latitude": 51.5333329,
        "longitude": -0.1265845
      }
    },
    "destination": {
      "point": {
        "latitude": 51.515598,
        "longitude": -0.1277623
      }
    },
    "location": {
      "point": {
        "latitude": 51.5333329,
        "longitude": -0.1265845
      },
      "sourceTime": "2025-05-30T12:37:26Z",
      "serverTime": "2025-05-30T12:37:26.221069Z"
    },
    "traveledDuration": "0s",
    "remainingDuration": "990s",
    "traveledDistanceMeters": 0,
    "remainingDistanceMeters": 2879,
    "stopAddedInRoute": false
  }
}

تتبُّع حالات الرحلة النشطة

للتأكّد من بدء الرحلة بنجاح وتتبُّع تقدّمها، قيِّم حقل الحالة في كل حمولة.

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

التعامل مع المحطات المُضافة

يمكن للسائقين إضافة محطات إلى مسارهم أثناء التنقّل. إذا فعلوا ذلك، يضبط Navigation Connect حقل execution.stopAddedInRoute على true في حمولة بيانات JSON. يواصل Navigation Connect API تتبُّع السائق نحو الوجهة الأصلية. تزداد المقاييس، مثل الوقت المقدَّر للوصول والمسافة والمدة، لتشمل المحطات المُضافة.

يعتمد سلوك إضافة المحطات على تطبيق التنقّل ويتطابق مع وظائفه العادية:

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

لست بحاجة إلى تعديل مدخلات النظام الخلفي لدعم هذه الميزة.

تحديد مشاكل المصادقة والبدء وحلّها

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

إذا لم تتغيّر الحالة من NEW إلى ENROUTE، قد يمنع جهاز السائق المصادقة. لا يرسِل Navigation Connect رسائل خطأ في هذه الحالات. تحقَّق مما يلي:

  • تثبيت الإصدار 5.15.5 من Waze أو إصدار أحدث، أو الإصدار 26.14 من "خرائط Google" أو إصدار أحدث على جهاز السائق.
  • عدم استخدام السائق Android Auto أو Apple CarPlay.
  • توفُّر اتصال نشط بالإنترنت لدى السائق.

التعامل مع بيانات المسار المتبقية (في Waze فقط)

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

يمكنك إدخال هذه البيانات ومعالجتها لتشغيل عدة ميزات في تطبيقاتك، بما في ذلك الأمثلة التالية:

  • تشغيل خرائط التتبُّع المباشر: يمكنك عرض خطوط المسار المتبقي المتعددة على خريطة ويب أو خريطة على الأجهزة الجوّالة تظهر للعملاء لتوفير معلومات حول رحلة السائق.
  • تحسين دقة الوقت المقدَّر للوصول: يمكنك الجمع بين الخطوط المتعددة التي تم ضبطها على الطريق وسرعات الفواصل الزمنية لحركة المرور لتحسين الخدمات اللوجستية الداخلية أو توقّعات الوصول للتوصيل.
  • تحليل مدى الامتثال للتوجيه: يمكنك مقارنة هندسة المسار المتبقي بـ مسارات الإرسال المتوقّعة لتقييم مدى التزام السائق (راجِع الأسئلة الشائعة للحصول على تفاصيل حول سبب اختلاف المسارات في الوقت الفعلي والمسارات التي تم احتسابها مسبقًا).

يعرِض Navigation Connect تفاصيل المسار المتبقي في حقل execution.remainingRoute، سواء أرسلت طلب GetTrip أو تلقّيت تعديلات مستندة إلى الأحداث باستخدام Google Cloud Pub/Sub. ومع ذلك، يعتمد تنسيق البيانات وبنيتها في الحمولة على طريقة الاسترداد التي تستخدمها.

طريقة GetTrip

عند استدعاء طريقة GetTrip، يعتمد تنسيق الاستجابة للخطوط المتعددة على المَعلمة routePolylineFormat التي حدّدتها في طلبك. لمزيد من المعلومات، راجِع تخصيص تنسيقات الخطوط المتعددة.

بالنسبة إلى جميع تنسيقات الخطوط المتعددة، يعرِض Navigation Connect حركة المرور كقائمة منفصلة من عناصر SpeedReadingInterval في حقل execution.remainingRoute.trafficInformation. تربط هذه العناصر فئات حركة المرور بفهارس الخطوط المتعددة باستخدام القيم التالية:

  • startPolylinePointIndex: الفهرس الأولي للفاصل الزمني لحركة المرور على الخطوط المتعددة.
  • endPolylinePointIndex: الفهرس النهائي للفاصل الزمني لحركة المرور.
  • speed: فئة حركة المرور لهذا المقطع: NORMAL أو SLOW أو TRAFFIC_JAM.

تعديلات Google Cloud Pub/Sub

عند استرداد بيانات الرحلة باستخدام Pub/Sub، تعرِض التعديلات دائمًا بيانات المسار المتبقي بتنسيق GeoJSON موحّد FeatureCollection في حقل execution.remainingRoute.

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

الاطّلاع على مثال على حمولة Pub/Sub

تعرض عينة التعليمات البرمجية التالية بنية GeoJSON التي يتم عرضها في حقل execution.remainingRoute ضمن عنصر updatedTrip لرسالة Pub/Sub:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [-122.3934, 37.7955],
          [-122.4010, 37.7980]
        ]
      },
      "properties": {
        "speed": "SLOW"
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [-122.4010, 37.7980],
          [-122.4058, 37.8025],
          [-122.4187, 37.8021]
        ]
      },
      "properties": {
        "speed": "NORMAL"
      }
    }
  ]
}

تحسين حجم الحمولة

بما أنّ مصفوفات الإحداثيات كبيرة، يمكن أن يؤدي تضمين بيانات المسار المتبقي في رسائل Pub/Sub إلى زيادة حجم الحمولة بشكل كبير (ما يصل إلى 13 إلى 14 كيلوبايت لكل رسالة). إذا كنت تتلقّى تعديلات عالية التردد، يمكن أن يؤدي هذا الحجم إلى زيادة حمل المعالجة في النظام الخلفي وتكاليف الاستخدام.

لتحسين البث، استخدِم المَعلمة pubsubFieldMask في عنصر TripConfig أثناء إنشاء الرحلة لاستبعاد الحقول الكبيرة. لمزيد من التفاصيل، راجِع عمليات الضبط الاختيارية.

التعامل مع حالات انتهاء الرحلة

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

الحالة الوصف الإجراء المقترَح
ARRIVED وصل السائق إلى الوجهة. تحقَّق من remainingDistanceMeters. إذا أوقف السائق سيارته في مكان قريب ولكن ليس عند الإحداثيات الدقيقة، ننصحك بتوفير اتجاهات المشي في تطبيقك.
SUSPENDED أغلق السائق يدويًا ميزة التنقّل باستخدام اتّجاهات مفصّلة قبل الوصول إلى الوجهة.
بما أنّ "خرائط Google" أو Waze لا يعيدان السائقين تلقائيًا إلى تطبيقك عند الخروج من الجلسة مبكرًا، يجب على السائق النقر يدويًا على زر الرجوع. 		لمساعدة السائقين في إكمال رحلتهم، قارِن execution.location بالوجهة. إذا كانت هناك مسافة متبقية، ننصحك بتوفير زر أو رابط لاستئناف الرحلة أو التبديل إلى وضع المشي.
FAILED أدى خطأ فني إلى مقاطعة الاتصال. يحدث ذلك إذا تعذّر على التطبيق احتساب مسار أو إذا ظهر تحذير بشأن السلامة. قد يكون السائق لا يزال يتنقّل، ولكن لن تتلقّى تعديلات. يمكنك الرجوع إلى تتبُّع الحالة يدويًا في تطبيقك.
CLIENT_ERROR تظهر هذه الحالة لأحد الأسباب التالية: يمكنك الرجوع إلى تتبُّع الحالة يدويًا في تطبيقك.