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