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

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

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

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

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

  • يجب تشغيل تطبيق Android باستخدام القناة الإصدار الأولي من DriverSDK v4.1.0 أو الإصدار الأعلى. تتوفر قناة ألفا باستخدام transportation-driver-alpha لـ Maven ArtifactId.
  • تستهلك واجهة برمجة التطبيقات معلومات المسار التي يوفّرها Fleet Engine عبر واجهة برمجة التطبيقات Deliveries. ويمكن توفيره من خلال واجهات برمجة التطبيقات على 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

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

vehicleRouteOverview.clearInstance();