وقتی دادههای سفرتان را بازیابی میکنید، پسای شما باردادههای JSON را که جزئیات پیشرفت سفر راننده را نشان میدهد دریافت میکند. این محمولههای داده را تجزیه کنید تا سفر را پایش کنید، سیستمهای اعزام خود را بهروز کنید، و وضعیتهای فعلی سفر را تفسیر کنید تا مرحله بعدی را برای راننده درحین پیشرفت یا هنگام پایان سفر تعیین کنید.
خواندن پایهبار دادهها
Google Maps یا Waze محموله دادههای سفر را به سرورهای 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
}
}
پایش کردن وضعیت سفرهای فعال
برای تأیید شروع موفقیتآمیز و نظارت بر پیشرفت، فیلد
state را در هر
بار داده ارزیابی کنید.
| وضعیت | شرح |
|---|---|
NEW |
سفر ایجاد شده است، اما راننده هنوز ناوبری را شروع نکرده است. |
ENROUTE |
راننده درحال ناوبری فعال به مقصد است. از این وضعیت برای تأیید اینکه سفر با موفقیت اصالتسنجی و شروع شده است استفاده کنید. |
مدیریت ایستگاههای اضافهشده
رانندگان میتوانند درطول پیمایش، به مسیرشان توقفگاه اضافه کنند. اگر این کار را انجام دهند،
Navigation Connect فیلد
execution.stopAddedInRoute
را در پایهبار داده JSON روی true تنظیم میکند. Navigation Connect API
به ردیابی راننده بهسمت مقصد اصلی ادامه میدهد. سنجههایی مثل
زمان برآوردی ورود (ETA)، مسافت، و مدتزمان افزایش مییابد
تا توقفهای اضافهشده را دربرگیرد.
رفتار افزودن ایستگاه به برنامه ناوبری بستگی دارد و با عملکرد استاندارد آن مطابقت دارد:
- Google Maps: رانندگان میتوانند چند توقف به مسیرشان اضافه کنند.
- Waze: رانندگان فقط یک توقف میتوانند اضافه کنند. اگر رانندهای بخواهد توقف دیگری اضافه کند، Waze از او میخواهد بهجای افزودن توقف به مسیر فعلی، جلسه ناوبری جدیدی را شروع کند.
برای پشتیبانی از این ویژگی، نیازی به تغییر ورودیهای پسین ندارید.
عیبیابی مشکلات اصالتسنجی و شروع
اگر وضعیت ENROUTE را دریافت نکردید، احتمالاً خطای اصالتسنجی رخ داده است. دلایل رایج شامل پارامترهای میانای برنامهسازی کاربردی با املای نادرست یا توکن سفر منقضیشده است. زمان انقضای توکن را در پاسخ اولیه CreateTrip بررسی کنید.
اگر وضعیت از NEW به ENROUTE تغییر نکند، ممکن است دستگاه راننده مانع اصالتسنجی شود. Navigation Connect برای این موارد پیام خطا ارسال نمیکند. موارد زیر را بهتأیید برسانید:
- راننده نسخه ۵.۱۵.۵ یا بالاتر Waze یا نسخه ۲۶.۱۴ یا بالاتر Google Maps را نصب کرده باشد.
- راننده از Android Auto یا Apple CarPlay استفاده نمیکند.
- راننده اتصال اینترنت فعال داشته باشد.
مدیریت دادههای مسیر باقیمانده
اگر گزارشدهی مسیر باقیمانده را درطول ایجاد سفر فعال کرده باشید، بخش پشتی شما چندخطی مسیر باقیمانده و شرایط ترافیک همزمان را از مکان فعلی راننده تا مقصد نهایی او دریافت میکند. رانندگان به Waze نسخه ۵.۲۰.۰.۲ یا جدیدتر در Android، نسخه ۵.۲۰.۰.۱ یا جدیدتر در iOS، یا Google Maps برای Android نسخه ۲۶.۲۷ یا جدیدتر نیاز دارند.
میتوانید این دادهها را برای تقویت چندین ویژگی در برنامههایتان دریافت و پردازش کنید، ازجمله نمونههای زیر:
- نقشههای ردیابی زنده Power: چندخطی مسیر باقیمانده را در نقشه وب یا تلفن همراه مشترینما ارائه دهید تا دیدی از سفر راننده ارائه شود.
- بهبود دقت زمان تخمینی ورود: چندخطی منطبق بر جاده و سرعتهای بازه ترافیک را ترکیب کنید تا پیشبینیهای ورود تحویل یا لجستیک داخلی را بهبود بخشید.
- تحلیل رعایت مسیر: هندسه مسیر باقیمانده را با مسیرهای اعزام موردانتظار مقایسه کنید تا میزان پایبندی راننده را ارزیابی کنید (برای جزئیات بیشتر درباره اینکه چرا مسیرهای همزمان و ازپیش محاسبهشده ممکن است متفاوت باشند، به پرسشگان مراجعه کنید).
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 میتواند اندازه بار مفید را بهطور قابلتوجهی افزایش دهد (تا ۱۳-۱۴ کیلوبایت برای هر پیام). اگر بهروزرسانیهای با بسامد بالا دریافت میکنید، این حجم میتواند بار پردازش پسزمینه و هزینههای استفاده را افزایش دهد.
برای بهینهسازی جاریسازی، از پارامتر
pubsubFieldMask
در شیء TripConfig
درطول ایجاد سفر استفاده کنید تا فیلدهای سنگین را مستثنی کنید. برای جزئیات، پیکربندیهای
اختیاری را ببینید.
رسیدگی به انحراف از مسیر (فقط Waze)
رانندگان به Waze نسخه ۵.۲۲ یا بالاتر نیاز دارند.
اگر گزارش انحراف از مسیر را درطول ایجاد سفر فعال کرده باشید، وقتی راننده از مسیر خارج میشود، API فراداده انحراف از مسیر را برمیگرداند. میتوانید به این دادهها از روشهای زیر دسترسی پیدا کنید:
- درصورت درخواست: روش
GetTripرا فراخوانی کنید. سرور آخرین وضعیت انحراف شناختهشده را حفظ میکند. - بیدرنگ: در Google Cloud Pub/Sub مشترک شوید. این سرویس بهروزرسانیهای انحراف را بااستفاده از رویداد
updated_tripموجود ظرف ۵ ثانیه پساز شناسایی منتشر میکند.
خواندن بار داده انحراف
شیء last_route_deviation فراداده زیر را برای کمک به شما در تحلیل رویداد ارائه میدهد.
| فیلد | نوع | شرح |
|---|---|---|
location |
LatLng |
مختصات طول و عرض جغرافیایی جایی که دستگاه کارخواه انحراف را ثبت کرده است. |
source |
TriggerSource |
دلیل انحراف. از این برای تعیین اینکه آیا راننده اقدام غیرمنتظرهای انجام داده یا از راهنمایی سیستم پیروی کرده است استفاده کنید:
|
client_timestamp |
Timestamp |
زمانی که دستگاه کارخواه انحراف را شناسایی کرد. |
server_timestamp |
Timestamp |
زمانی که سرور بهروزرسانی انحراف را پردازش کرد. |
مدیریت وضعیتهای پایان سفر
وقتی راننده به مقصد میرسد یا ناوبری را متوقف میکند، بار داده یکی از حالتهای پایانی زیر را برمیگرداند. از این وضعیتها برای راهاندازی مراحل بعدی مناسب در برنامهتان استفاده کنید.
| وضعیت | شرح | اقدام توصیهشده |
|---|---|---|
ARRIVED |
راننده به مقصد رسید. | remainingDistanceMeters را بررسی کنید. اگر راننده در نزدیکی مقصد پارک کرده است اما نه در مختصات دقیق، ارائه مسیر پیادهروی در برنامهتان را مدنظر قرار دهید. |
SUSPENDED |
راننده پیشاز رسیدن به مقصد، بهصورت دستی از ناوبری گامبهگام خارج شد. ازآنجاییکه Google Maps یا Waze وقتی رانندگان زودتر از موعد از جلسه خارج میشوند، آنها را بهطور خودکار به برنامه شما برنمیگرداند، راننده باید بهطور دستی روی دکمه بازگشت تکضرب بزند. |
برای کمک به رانندگان در تکمیل سفرشان،
execution.location را با مقصد مقایسه کنید. اگر مسافت
باقیمانده است، دکمه یا پیوندی برای ازسر گرفتن سفر یا رفتن به
حالت پیادهروی ارائه دهید. |
FAILED |
خطای فنی اتصال را قطع کرد. این اتفاق زمانی میافتد که برنامه نتواند مسیری را محاسبه کند یا هشدار ایمنی نشان داده شود. ممکن است راننده همچنان درحال پیمایش باشد، اما شما بهروزرسانی دریافت نخواهید کرد. | به ردیابی وضعیت دستی در برنامهتان برگردید. |
CLIENT_ERROR |
این وضعیت بهدلیل یکی از موارد زیر نشان داده میشود:
|
به ردیابی وضعیت دستی در برنامهتان برگردید. |