وقتی دادههای سفر خود را بازیابی میکنید ، backend شما فایلهای JSON را دریافت میکند که جزئیات پیشرفت سفر راننده را نشان میدهد. این فایلهای JSON را تجزیه کنید تا سفر را رصد کنید، سیستمهای اعزام خود را بهروزرسانی کنید و وضعیت فعلی سفر را تفسیر کنید تا گام بعدی راننده را در حین پیشرفت یا پایان سفر تعیین کنید.
بار داده را بخوانید
گوگل مپ یا ویز، دادههای سفر را هنگام شروع ناوبری راننده، به صورت دورهای در طول مسیر (به طور پیشفرض هر ۶۰ ثانیه) و هنگامی که راننده به مقصد میرسد، به سرورهای Navigation Connect ارسال میکنند. هر پیام JSON حاوی دادههای سفر مربوطه، از جمله مختصات جادهای ثبت شده راننده، مسافت طی شده و زمان تخمینی رسیدن (ETA) است.
نمونه کد زیر، دادههای سفر را برای زمانی که راننده ناوبری را برای سفری از کینگز کراس به سنترال سنت گیلز شروع میکند، نشان میدهد.
{
"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
}
}
وضعیت سفرهای فعال را رصد کنید
برای تأیید شروع موفقیتآمیز و نظارت بر پیشرفت، فیلد وضعیت را در هر payload ارزیابی کنید.
| وضعیت | توضیحات |
|---|---|
NEW | سفر ایجاد شده است، اما راننده هنوز مسیریابی را شروع نکرده است. |
ENROUTE | راننده به طور فعال در حال حرکت به سمت مقصد است. از این وضعیت برای تأیید تأیید و شروع موفقیتآمیز سفر استفاده کنید. |
مدیریت ایستگاههای اضافه شده
رانندگان میتوانند در طول پیمایش، ایستگاههایی را به مسیر خود اضافه کنند. در این صورت، Navigation Connect فیلد execution.stopAddedInRoute را در داده JSON روی true تنظیم میکند. رابط برنامهنویسی کاربردی Navigation Connect همچنان راننده را به سمت مقصد اصلی ردیابی میکند. معیارهایی مانند زمان تخمینی رسیدن (ETA)، مسافت و مدت زمان برای شامل شدن ایستگاههای اضافه شده افزایش مییابند.
نحوهی افزودن ایستگاهها به برنامهی ناوبری بستگی دارد و با عملکرد استاندارد آن مطابقت دارد:
- نقشههای گوگل: رانندگان میتوانند چندین ایستگاه به مسیر خود اضافه کنند.
- ویز: رانندگان فقط میتوانند یک ایستگاه اضافه کنند. اگر رانندهای سعی کند ایستگاه دیگری اضافه کند، ویز به جای اضافه کردن ایستگاه به مسیر فعلی، از او میخواهد که یک جلسه ناوبری جدید را شروع کند.
برای پشتیبانی از این ویژگی، نیازی به تنظیم ورودیهای backend خود ندارید.
عیبیابی احراز هویت و شروع مشکلات
اگر وضعیت ENROUTE را دریافت نکردید، احتمالاً خطای احراز هویت رخ داده است. دلایل رایج شامل پارامترهای API با املای اشتباه یا توکن سفر منقضی شده است. زمان انقضای توکن را در پاسخ اولیه CreateTrip خود بررسی کنید.
اگر وضعیت از NEW به ENROUTE تغییر نکرد، ممکن است دستگاه راننده از احراز هویت جلوگیری کند. Navigation Connect برای این موارد پیام خطا ارسال نمیکند. موارد زیر را بررسی کنید:
- درایور، Waze نسخه ۵.۱۵.۵ یا بالاتر یا Google Maps نسخه ۲۶.۱۴ یا بالاتر را نصب کرده است.
- راننده از اندروید اتو یا اپل کارپلی استفاده نمیکند.
- راننده اتصال اینترنتی فعال دارد.
مدیریت دادههای مسیر باقیمانده (فقط در Waze)
اگر گزارشدهی مسیر باقیمانده را در حین ایجاد سفر فعال کرده باشید، بخش مدیریت شما، چندخطی مسیر فعال و شرایط ترافیک لحظهای را از موقعیت فعلی راننده تا مقصد نهاییاش دریافت میکند.
شما میتوانید این دادهها را دریافت و پردازش کنید تا چندین ویژگی را در برنامههای خود فعال کنید، از جمله مثالهای زیر:
- نقشههای ردیابی زنده را فعال کنید : چندخطی مسیر باقیمانده را روی نقشه وب یا موبایل که در معرض دید مشتری است، نمایش دهید تا دید بهتری از مسیر راننده فراهم شود.
- افزایش دقت ETA : با ترکیب نمودار چندخطی ثبتشده در جاده و سرعتهای بازه ترافیک، پیشبینیهای لجستیک داخلی یا زمان رسیدن محمولهها را بهبود بخشید.
- تحلیل انطباق با مسیریابی : هندسه مسیر باقیمانده را با مسیرهای اعزام مورد انتظار مقایسه کنید تا میزان پایبندی راننده را ارزیابی کنید.
Navigation Connect جزئیات مسیر باقیمانده را در فیلد execution.remainingRoute برمیگرداند، چه شما یک درخواست GetTrip ارسال کنید و چه با استفاده از Google Cloud Pub/Sub بهروزرسانیهای مبتنی بر رویداد را دریافت کنید. با این حال، نحوه قالببندی و ساختاردهی payload این دادهها به روش بازیابی مورد استفاده شما بستگی دارد.
روش 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 شما میتواند حجم payload را به میزان قابل توجهی افزایش دهد (تا ۱۳ تا ۱۴ کیلوبایت در هر پیام). اگر بهروزرسانیهای مکرر دریافت کنید، این حجم میتواند بار پردازش backend و هزینههای استفاده را افزایش دهد.
برای بهینهسازی جریان خود، در طول ایجاد سفر از پارامتر pubsubFieldMask در شیء TripConfig خود استفاده کنید تا فیلدهای سنگین را حذف کنید. برای جزئیات بیشتر، به تنظیمات اختیاری مراجعه کنید.
مدیریت وضعیتهای پایان سفر
وقتی راننده به مقصد میرسد یا پیمایش را متوقف میکند، payload یکی از حالتهای پایانی زیر را برمیگرداند. از این وضعیتها برای شروع مراحل بعدی مناسب در برنامه خود استفاده کنید.
| وضعیت | توضیحات | اقدام توصیه شده |
|---|---|---|
ARRIVED | راننده به مقصد رسید. | remainingDistanceMeters بررسی کنید. اگر راننده در نزدیکی پارک کرده اما مختصات دقیق را ندارد، ارائه مسیرهای پیادهروی در برنامه خود را در نظر بگیرید. |
SUSPENDED | راننده قبل از رسیدن به مقصد، به صورت دستی از ناوبری گام به گام خارج شد. از آنجا که گوگل مپس یا ویز هنگام خروج زودهنگام رانندگان از برنامه، آنها را به طور خودکار به برنامه شما باز نمیگردانند، راننده باید به صورت دستی دکمه بازگشت را لمس کند. | برای کمک به رانندگان در تکمیل سفرشان، execution.location با مقصد مقایسه کنید. اگر مسافت باقی مانده است، دکمه یا لینکی برای از سرگیری سفر یا تغییر به حالت پیادهروی ارائه دهید. |
FAILED | یک خطای فنی اتصال را قطع کرد. این اتفاق زمانی رخ میدهد که برنامه نتواند مسیر را محاسبه کند یا یک هشدار ایمنی ظاهر شود. ممکن است راننده هنوز در حال پیمایش باشد، اما شما بهروزرسانیها را دریافت نخواهید کرد. | به ردیابی دستی وضعیت در برنامه خود برگردید. |
CLIENT_ERROR | این وضعیت به یکی از دلایل زیر ظاهر میشود:
| به ردیابی دستی وضعیت در برنامه خود برگردید. |