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

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

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

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

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

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

خطوات الدمج

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

• لديك تطبيق Android حالي تم دمجه مع حزمة تطوير البرامج (SDK) لبرنامج التشغيل
• لقد أعددت DeliveryDriverApi في تطبيقك من خلال سياق. الذي يمكنك العثور عليه

عرض بدء استخدام Driver SDK لنظام التشغيل Android لمزيد من التفاصيل.

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

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

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

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

بعد إنشاء مسار صالح مع المحطات والمهام المرتبطة، يمكنك لتهيئة واجهة برمجة تطبيقات Route Overview. توفّر عملية الإعداد إطار العمل اللازمة للاتصال بين Fleet Engine وواجهة برمجة التطبيقات. المسار يجب تهيئة واجهة برمجة تطبيقات نظرة عامة باستخدام كائن السياق نفسه الذي استخدمته إعداد 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();