پردازش داده‌های سفر

وقتی داده‌های سفرتان را بازیابی می‌کنید، پسای شما بارداده‌های 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 دلیل انحراف. از این برای تعیین اینکه آیا راننده اقدام غیرمنتظره‌ای انجام داده یا از راهنمایی سیستم پیروی کرده است استفاده کنید:
  • DRIVER_INITIATED_REROUTE: راننده انتخاب فعالی انجام داده است (برای مثال، پیچیدن اشتباه یا انتخاب دستی مسیر جدید).
  • SYSTEM_INITIATED_REROUTE: برنامه ناوبری مسیر جدیدی را محاسبه کرد (برای مثال، به‌دلیل تغییر شرایط ترافیک یا بسته شدن جاده).
client_timestamp Timestamp زمانی که دستگاه کارخواه انحراف را شناسایی کرد.
server_timestamp Timestamp زمانی که سرور به‌روزرسانی انحراف را پردازش کرد.

مدیریت وضعیت‌های پایان سفر

وقتی راننده به مقصد می‌رسد یا ناوبری را متوقف می‌کند، بار داده یکی از حالت‌های پایانی زیر را برمی‌گرداند. از این وضعیت‌ها برای راه‌اندازی مراحل بعدی مناسب در برنامه‌تان استفاده کنید.

وضعیت شرح اقدام توصیه‌شده
ARRIVED راننده به مقصد رسید. remainingDistanceMeters را بررسی کنید. اگر راننده در نزدیکی مقصد پارک کرده است اما نه در مختصات دقیق، ارائه مسیر پیاده‌روی در برنامه‌تان را مدنظر قرار دهید.
SUSPENDED راننده پیش‌از رسیدن به مقصد، به‌صورت دستی از ناوبری گام‌به‌گام خارج شد.
ازآنجایی‌که Google Maps یا Waze وقتی رانندگان زودتر از موعد از جلسه خارج می‌شوند، آن‌ها را به‌طور خودکار به برنامه شما برنمی‌گرداند، راننده باید به‌طور دستی روی دکمه بازگشت تک‌ضرب بزند.
برای کمک به رانندگان در تکمیل سفرشان، execution.location را با مقصد مقایسه کنید. اگر مسافت باقی‌مانده است، دکمه یا پیوندی برای ازسر گرفتن سفر یا رفتن به حالت پیاده‌روی ارائه دهید.
FAILED خطای فنی اتصال را قطع کرد. این اتفاق زمانی می‌افتد که برنامه نتواند مسیری را محاسبه کند یا هشدار ایمنی نشان داده شود. ممکن است راننده همچنان درحال پیمایش باشد، اما شما به‌روزرسانی دریافت نخواهید کرد. به ردیابی وضعیت دستی در برنامه‌تان برگردید.
CLIENT_ERROR این وضعیت به‌دلیل یکی از موارد زیر نشان داده می‌شود:
  • راننده رضایتش را لغو می‌کند.
  • راننده از پلاتفرم پشتیبانی‌نشده‌ای مثل Android Auto یا Apple CarPlay استفاده می‌کند.
  • برنامه‌تان از یک کد سفر در سفرهای جداگانه استفاده مجدد می‌کند. برای مثال، Navigation Connect درخواست‌هایی را که مقصد سفر را تغییر می‌دهند یا سفر تکمیل‌شده‌ای را به‌روز می‌کنند رد می‌کند.
  • راننده در هر نقطه‌ای از سفر در ایالات متحده باشد، اما وقتی برنامه‌تان را درطول راه‌اندازی تأیید کردید، هم‌رسانی داده در ایالات متحده را در برنامه‌تان فعال نکرده باشید.
به ردیابی وضعیت دستی در برنامه‌تان برگردید.