واجهة برمجة التطبيقات لنظرة عامة على المسار

Route Overview API هي إحدى منتجات مشروع Last Mile Fleet Solution وهو مُصمَّم استنادًا إلى DriverSDK. من خلال هذه الميزة، يمكنك استرداد معلومات المسار لمركبة معيّنة، سواء من خلال عملية جلب لمرّة واحدة أو بشكل مستمر من خلال استخدام أداة تتبّع للتحديثات. تتيح واجهة برمجة التطبيقات Route Overview API الأنواع التالية من المعلومات:

  • خطة المسار الكامل، بما في ذلك مواقع محطات المركبات وأوقات السفر والمسافات
  • المسار المتعدد الخطوط بين كل محطة.

يوضّح هذا المستند خطوات الدمج مع واجهة برمجة التطبيقات لتطبيقك.

المتطلبات الأساسية

  • يجب تشغيل تطبيق Android باستخدام قناة الإصدار الأولي من الإصدار 4.1.0 من DriverSDK أو الإصدار الأعلى. تتوفّر قناة ألفا باستخدام transportation-driver-alpha لمعرّف Maven الذي يضم أدوات Maven.
  • تستهلك واجهة برمجة التطبيقات معلومات المسارات التي يوفّرها Fleet Engine عبر واجهة Deliveries API. ويمكن توفير ذلك من خلال واجهات برمجة التطبيقات في DriverSDK (DeliveryDriverApi) أو مباشرةً إلى Fleet Engine.

خطوات الدمج

يتناول هذا القسم الخطوات الأساسية اللازمة لدمج تطبيق برامج تشغيل Android مع واجهة برمجة التطبيقات. تتضمن هذه التعليمات الافتراضات التالية:

  • لديك تطبيق Android حالي تم دمجه من قبل مع Driver SDK
  • لقد أعددت DeliveryDriverApi في تطبيقك باستخدام كائن سياق يمكنك العثور عليه

للحصول على مزيد من التفاصيل، راجِع بدء استخدام Driver SDK لنظام التشغيل Android.

الخطوة 0 - إعداد المسار

يمكنك تخطّي هذه الخطوة إذا سبق لك إعداد Fleet Engine ويمكنك تحديد إجراءات توقّف المركبات ومهام التسليم.

لتحميل معلومات عن مكان التوقّف والمهمة إلى Fleet Engine، عليك اختيار مركبة توصيل مخصّصة لمسار صالح. وذلك لأنّ Route Overview API تتطلب مسارات صالحة لاسترجاع البيانات. وتتكون المسارات الصالحة من سلسلة من نقاط الطرق والمحطات، ولا يمكن أن توجد محطة إلا إذا كانت بها مهمة مرتبطة واحدة على الأقل. راجِع دليل دمج واجهة برمجة تطبيقات Fleet Engine للحصول على مزيد من المعلومات.

الخطوة 1 - إعداد واجهة برمجة التطبيقات

بعد إنشاء مسار صالح يضم محطات التوقف والمهام المرتبطة بها، يمكنك تهيئة Route Overview API. توفر التهيئة إطار العمل الضروري للتوصيل بين Fleet Engine وواجهة برمجة التطبيقات. يجب إعداد Route Overview API باستخدام كائن السياق نفسه الذي استخدمته لإعداد DeliveryDriverApi في DriverSDK، لأنّ العنصر يشير إلى رقم تعريف المركبة نفسه الذي تم تحديده سابقًا في عنصر DriverContext. يوضّح المثال التالي كيفية إنشاء مثيل RouteOverviewApi.


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

الخطوة 2: تسجيل المركبة لأحداث تغيير المسار

الآن وبعد إعداد واجهة برمجة التطبيقات، يمكنك استخدام الكائن VehicleRouteOverview للتفاعل مع إمكانات النظرة العامة على المسار. يتيح هذا الإجراء لتطبيقك استهلاك معلومات المسار التي قدّمتها أثناء إعداد المسار. استخدام أداة معالجة أحداث واجهة برمجة التطبيقات لتسهيل تعديلات الأحداث واسترداد المسار

يحدث تغيير المسار عندما يتم تعديل المسار إلى أي من المحطات المخصصة للمركبة، أو إعادة ترتيب المحطة، أو تحديث Fleet Engine لمعلومات الوقت المقدر للوصول.


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

الخطوة 3: تفعيل واجهة برمجة التطبيقات

بعد أن أصبحت جاهزًا للاطّلاع على معلومات عن المسارات، عليك تفعيل واجهة برمجة التطبيقات للسماح لها بالاستجابة إلى أحداث المركبات. تجدر الإشارة إلى أنّه يتم إعداد واجهة برمجة التطبيقات في حالة غير مُفعَّلة لتجنُّب الاستهلاك غير الضروري لمعدل نقل البيانات للشبكة.

vehicleRouteOverview.setRouteOverviewEnabled(true);

يمكنك إيقاف هذه التعديلات مؤقتًا في أيّ وقت من خلال استدعاء الطريقة نفسها بالقيمة false.

الخطوة 4 - رسم المسار على خريطة Google

بعد الحصول على قائمة RouteToVehicleStop، يمكنك استخدامها في تطبيقك. على سبيل المثال، يمكنك رسم المسار المتعدد الخطوط للمسار في مثيل "خرائط Google". يوضح مقتطف الرمز التالي مثالاً يرسم الخط المتعدد للمسار على عرض الخريطة ويضيف علامات أعلى كل موقع محطة.

    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();

محو مثيل واجهة برمجة التطبيقات Route Overview API

إذا لم تعُد هناك حاجة إلى "نظرة عامة على المسار" أو إذا تم تغيير معرّف المركبة التي يتم تتبّعها، يمكنك استدعاء واجهة برمجة التطبيقات هذه لمحو المراجع الداخلية.

vehicleRouteOverview.clearInstance();