Route Overview API

Route Overview API یک محصول Last Mile Fleet Solution است که بر روی DriverSDK ساخته شده است. با استفاده از آن، می توانید اطلاعات مسیر را برای یک وسیله نقلیه خاص، یا به صورت یک بار واکشی یا به طور مداوم با استفاده از شنونده برای به روز رسانی، بازیابی کنید. Route Overview API از انواع اطلاعات زیر پشتیبانی می کند:

  • طرح کامل مسیر، شامل مکان های توقف وسیله نقلیه، زمان سفر، مسافت ها
  • مسیر چند خطی بین هر ایستگاه.

این سند مراحل یکپارچه سازی با API را برای برنامه شما شرح می دهد.

پیش نیازها

  • شما باید برنامه اندروید خود را با استفاده از کانال آلفا DriverSDK نسخه 4.1.0 یا بالاتر اجرا کنید. کانال آلفا با استفاده از transportation-driver-alpha برای Maven artifactId در دسترس است.
  • API اطلاعات مسیر ارائه شده توسط Fleet Engine را از طریق Deliveries API مصرف می کند. این را می توان از طریق APIهای موجود در DriverSDK ( DeliveryDriverApi ) یا مستقیماً به Fleet Engine ارائه کرد.

مراحل ادغام

این بخش مراحل اساسی مورد نیاز برای ادغام برنامه درایور اندروید شما با API را پوشش می دهد. این دستورالعمل ها دارای مفروضات زیر هستند:

  • شما یک برنامه اندروید موجود دارید که قبلاً با Driver SDK ادغام شده است
  • شما DeliveryDriverApi در برنامه خود با یک شی زمینه که می توانید پیدا کنید مقداردهی اولیه کرده اید

برای جزئیات بیشتر به شروع کار با Driver SDK برای Android مراجعه کنید.

مرحله 0 - راه اندازی مسیر

اگر قبلاً Fleet Engine را راه‌اندازی کرده‌اید و می‌توانید توقف خودرو و وظایف تحویل را ایجاد کنید، می‌توانید این مرحله را نادیده بگیرید.

برای بارگیری اطلاعات توقف و وظیفه در Fleet Engine، به یک وسیله نقلیه تحویلی نیاز دارید که به یک مسیر معتبر اختصاص داده شده باشد. دلیل آن این است که Route Overview API به مسیرهای معتبر برای واکشی داده نیاز دارد. مسیرهای معتبر از مجموعه ای از ایستگاه های بین راه و ایستگاه ها تشکیل شده اند و یک توقف تنها در صورتی می تواند وجود داشته باشد که حداقل یک وظیفه مرتبط داشته باشد. برای اطلاعات بیشتر به راهنمای ادغام API Fleet Engine مراجعه کنید.

مرحله 1 - API را راه اندازی کنید

هنگامی که یک مسیر معتبر با توقف ها و وظایف مرتبط ایجاد کردید، می توانید Route Overview API را مقداردهی اولیه کنید. Initialization چارچوب لازم برای اتصال بین Fleet Engine و API را فراهم می کند. Route Overview API باید با همان شی متنی که برای مقداردهی اولیه DeliveryDriverApi در DriverSDK استفاده کردید مقداردهی شود، زیرا شی به همان شناسه وسیله نقلیه که قبلاً در شی DriverContext شما تعریف شده است اشاره دارد. مثال زیر نحوه ایجاد یک نمونه از RouteOverviewApi را نشان می دهد.


RouteOverviewApi api = RouteOverviewApi.getInstance();
if (api == null) {
    api = RouteOverviewApi.createInstance(context);
}

مرحله 2 - وسیله نقلیه را برای رویدادهای تغییر مسیر ثبت کنید

اکنون که API را مقداردهی اولیه کرده اید، می توانید از شی VehicleRouteOverview برای تعامل با قابلیت های نمای کلی مسیر استفاده کنید. این به برنامه شما اجازه می دهد تا اطلاعات مسیری را که در طول راه اندازی مسیر ارائه کرده اید، مصرف کند. از شنونده رویداد API برای تسهیل به روز رسانی رویداد و بازیابی مسیر استفاده کنید.

یک رویداد تغییر مسیر زمانی رخ می دهد که مسیر هر یک از توقف های اختصاص داده شده به وسیله نقلیه به روز شود، یک توقف دوباره مرتب شود، یا زمانی که Fleet Engine اطلاعات ETA را به روز می کند.


vehicleRouteOverview.addOnRouteChangedEventListener(event -> {
    // handle route update events
});

مرحله 3 - API را فعال کنید

اکنون که آماده مصرف اطلاعات مسیر هستید، باید API را فعال کنید تا به رویدادهای وسیله نقلیه پاسخ دهد. به یاد داشته باشید که API در حالت غیرفعال تنظیم شده است تا از مصرف غیرضروری پهنای باند شبکه جلوگیری شود.

automjetRouteOverview.setRouteOverviewEnabled(true);

می‌توانید هر زمان که بخواهید با فراخوانی همان روش با مقدار false ، این به‌روزرسانی‌ها را متوقف کنید.

مرحله 4 - مسیر را روی نقشه گوگل ترسیم کنید

هنگامی که لیستی از RouteToVehicleStop را دریافت کردید، می توانید از آن در برنامه خود استفاده کنید. برای مثال، می‌توانید مسیر چند خطی مسیر را در یک نمونه Google Map رسم کنید. قطعه کد زیر نمونه ای را نشان می دهد که چند خط مسیر را در نمای نقشه ترسیم می کند و نشانگرهایی را در بالای هر مکان توقف اضافه می کند.

    GoogleMap googleMap = … // Instance of the Map view you are using
    ImmutableList<RouteToVehicleStop> route = event.newRoute();

    PolylineOptions routePolyline = new PolylineOptions().color(Color.BLUE);
    for (RouteToVehicleStop stop : route) {
        routePolyline.addAll(stop.path());

        MarkerOptions marker =
            new MarkerOptions().position(stop.vehicleStop().getWaypoint().getPosition());
        googleMap.addMarker(marker);
    }

    googleMap.addPolyline(routePolyline);
}

اسکرین شات تصویری از نمای کلی مسیر را نشان می دهد

این منجر به نمای مشابه تصویر سمت راست می شود:

مرحله 5 - یک عکس فوری از مسیر دریافت کنید

اگر می‌خواهید برنامه شما یک تماس یک‌باره برای بازیابی یک عکس فوری از اطلاعات مسیر فعلی صادر کند، می‌توانید از روش زیر برای بازیابی آن داده‌ها استفاده کنید:

ListenableFuture<ImmutableList<RouteToVehicleStop> future = vehicleRouteOverview.getRouteToVehicleStops();
ImmutableList<RouteToVehicleStop> stops = future.get();

می توانید این کار را به جای اشتراک در به روز رسانی مسیرها از طریق شنوندگان رویداد انجام دهید.

مرحله 6 - تمیز کردن

اگر برنامه شما دیگر به عملکرد نمای کلی مسیر نیاز ندارد، باید مطمئن شوید که آن را پاکسازی کرده اید. انجام پاکسازی از مصرف غیرضروری حافظه، پردازش و شبکه در برنامه شما جلوگیری می کند.

یک شنونده رویداد خاص را حذف کنید

وقتی شنونده خاصی دیگر لازم نیست، باید شنونده رویداد را حذف کنید.

vehicleRouteOverview.removeOnRouteChangedEventListener(listener);

همه شنوندگان رویداد را پاک کنید

به‌عنوان بخشی از روال پاکسازی خود، می‌توانید همه شنوندگان رویدادهای مختلف ثبت‌شده را به‌طور هم‌زمان حذف کنید.

vehicleRouteOverview.clearEventListeners();

پاک کردن نمونه API نمای کلی مسیر

هر زمان که Route Overview دیگر مورد نیاز نیست یا شناسه وسیله نقلیه ردیابی شده تغییر کرده است، می توانید برای پاک کردن مراجع داخلی با این API تماس بگیرید.

vehicleRouteOverview.clearInstance();