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

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

مراقبة حالات الرحلات النشطة

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

الحالة الوصف
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.
  • أن يكون لدى السائق اتصال نشط بالإنترنت

التعامل مع بيانات المسار المتبقية

إذا فعّلت ميزة إعداد تقارير المسار المتبقّي أثناء إنشاء الرحلة، ستتلقّى الخلفية الخطوط المتعدّدة للمسار المتبقّي وأحوال حركة المرور في الوقت الفعلي من الموقع الجغرافي الحالي للسائق إلى وجهته النهائية. يحتاج السائقون إلى الإصدار 5.20.0.2 من تطبيق Waze أو إصدار أحدث على أجهزة Android، أو الإصدار 5.20.0.1 أو إصدار أحدث على أجهزة iOS، أو الإصدار 26.27 من تطبيق "خرائط Google" لأجهزة Android أو إصدار أحدث.

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

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

تعرض 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 فقط)

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