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

عند استرداد بيانات رحلتك، يتلقّى الخلفية حمولات 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.

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

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

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

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

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

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

• خرائط 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 أثناء إنشاء الرحلة لاستبعاد الحقول الكبيرة. لمزيد من التفاصيل، يُرجى الاطّلاع على الإعدادات الاختيارية.

التعامل مع الانحرافات عن المسار (‫Waze فقط)

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

• عند الطلب: استدعِ طريقة GetTrip. يحتفظ الخادم بآخر حالة معروفة للانحراف.
• في الوقت الفعلي: اشترِك في Google Cloud Pub/Sub. تنشر الخدمة تعديلات الانحراف باستخدام الحدث updated_trip الحالي في غضون 5 ثوانٍ من رصد الانحراف.

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

يوفّر عنصر last_route_deviation البيانات الوصفية التالية لمساعدتك في تحليل الحدث.

الحقل	النوع	الوصف
location	LatLng	تمثّل هذه السمة إحداثيات خط العرض وخط الطول التي سجّل فيها الجهاز العميل الانحراف.
source	TriggerSource	سبب الانحراف استخدِم هذا الحقل لتحديد ما إذا كان برنامج التشغيل قد اتّخذ إجراءً غير متوقّع أو اتّبع إرشادات النظام: DRIVER_INITIATED_REROUTE: اتّخذ السائق قرارًا نشطًا (على سبيل المثال، اتّخاذ منعطف خاطئ أو اختيار مسار جديد يدويًا). ‫SYSTEM_INITIATED_REROUTE: احتسب تطبيق التنقّل مسارًا جديدًا (على سبيل المثال، بسبب تغيُّر حالة حركة المرور أو إغلاق الطرق).
client_timestamp	Timestamp	الوقت الذي رصد فيه الجهاز العميل الانحراف.
server_timestamp	Timestamp	الوقت الذي عالج فيه الخادم تعديل الانحراف.

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

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

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