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

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

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

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

تعرض عينة التعليمات البرمجية التالية حمولة بيانات الرحلة عندما يبدأ السائق التنقّل لرحلة من 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
  }
}

ملاحظة: إذا كنت تتلقّى بياناتك باستخدام Google Cloud Pub/Sub، تغلّف الخدمة تعديلات الرحلة في مغلّف رسالة عادية. يحتوي حقل البيانات على حمولة JSON الفعلية لـ Navigation Connect.

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

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

الحالة	الوصف
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 لا يعيدان السائقين تلقائيًا إلى تطبيقك عند الخروج من الجلسة مبكرًا، يجب على السائق النقر يدويًا على زر الرجوع. ملاحظة: إذا استخدم السائق زر الرجوع للعودة إلى تطبيقك بدون الخروج من جلسة التنقّل النشطة، تظل حالة الرحلة ENROUTE. لمزيد من المعلومات، اطّلِع على المقالة التعامل مع التبديل بين التطبيقات في منتصف الرحلة.	لمساعدة السائقين في إكمال رحلتهم، يمكنك مقارنة execution.location بالوجهة. إذا كانت المسافة المتبقية كبيرة، يمكنك توفير زر أو رابط لاستئناف الرحلة أو التبديل إلى وضع المشي.
FAILED	أدى خطأ فني إلى انقطاع الاتصال. يحدث ذلك إذا تعذّر على التطبيق حساب مسار أو إذا ظهر تحذير بشأن السلامة. قد يكون السائق لا يزال يتنقّل، ولكن لن تتلقّى أي تعديلات.	يمكنك الرجوع إلى تتبُّع الحالة يدويًا في تطبيقك.
CLIENT_ERROR	تظهر هذه الحالة لأحد الأسباب التالية: سحب السائق الموافقة. استخدام السائق نظامًا أساسيًا غير متوافق، مثل Android Auto أو Apple CarPlay. إعادة استخدام تطبيقك رمز رحلة لرحلة بوجهة مختلفة. وجود السائق في الولايات المتحدة في أي وقت أثناء الرحلة، ولكن لم يتم تفعيل ميزة مشاركة البيانات في الولايات المتحدة عند التحقّق من تطبيقك أثناء الإعداد.	يمكنك الرجوع إلى تتبُّع الحالة يدويًا في تطبيقك.