API ภาพรวมเส้นทาง

RouteOverview API คือผลิตภัณฑ์โซลูชันสุดท้าย (เส้นทางสุดท้าย) ที่สร้างขึ้นบน DriverSDK คุณสามารถใช้ Listener เพื่อเรียกข้อมูลเส้นทางของรถคันหนึ่ง ไม่ว่าจะเป็นการดึงข้อมูลแบบครั้งเดียวหรือแบบต่อเนื่องโดยใช้ Listener เพื่ออัปเดตข้อมูล RouteOverview API รองรับข้อมูลประเภทต่อไปนี้

  • แผนเส้นทางทั้งหมด รวมถึงตำแหน่งป้ายจอดรถ เวลาเดินทาง ระยะทาง
  • เส้นทางเส้นประกอบของเส้นทางระหว่างจุดแวะพักแต่ละแห่ง

เอกสารนี้จะอธิบายขั้นตอนการผสานรวมกับ API สำหรับแอปพลิเคชันของคุณ

ข้อกำหนดเบื้องต้น

  • คุณต้องเรียกใช้แอปพลิเคชัน Android โดยใช้แชแนลอัลฟ่าของ DriverSDK v4.1.0 หรือสูงกว่า เวอร์ชันอัลฟ่าพร้อมใช้งานโดยใช้ transportation-driver-alpha สำหรับ ArtifactId ของ Maven
  • API ใช้ข้อมูลเส้นทางที่ได้รับจาก Fleet Engine ผ่าน Deliveries API ซึ่งจัดเตรียมได้ผ่าน API ใน DriverSDK (DeliveryDriverApi) หรือไปยัง Fleet Engine โดยตรงก็ได้

ขั้นตอนการผสานรวม

ส่วนนี้ครอบคลุมขั้นตอนพื้นฐานที่จำเป็นในการผสานรวมแอปไดรเวอร์ Android กับ API วิธีการเหล่านี้มีสมมติฐานดังต่อไปนี้

  • คุณมีแอป Android ที่มีอยู่ซึ่งผสานรวมกับ SDK ของไดรเวอร์แล้ว
  • คุณได้เริ่มต้น DeliveryDriverApi ในแอปด้วยออบเจ็กต์บริบทที่คุณจะพบ

โปรดดูรายละเอียดที่ เริ่มต้นใช้งาน Driver SDK สำหรับ Android

ขั้นตอนที่ 0 - การตั้งค่าเส้นทาง

คุณข้ามขั้นตอนนี้ได้หากตั้งค่า Fleet Engine แล้วและสร้างจุดจอดและงานนำส่งยานพาหนะได้

หากต้องการโหลดข้อมูลจุดแวะพักและงานไปยัง Fleet Engine คุณต้องมีรถส่งของตามเส้นทางที่ถูกต้อง เนื่องจาก RouteOverview API ต้องใช้เส้นทางที่ถูกต้องเพื่อดึงข้อมูล เส้นทางที่ถูกต้องจะประกอบไปด้วยจุดระหว่างทางและป้ายหยุดหลายจุด และจะมีจุดแวะได้ก็ต่อเมื่อมีงานที่เกี่ยวข้องอย่างน้อย 1 งานเท่านั้น ดูข้อมูลเพิ่มเติมในคู่มือการผสานรวม Fleet Engine API

ขั้นตอนที่ 1 - เริ่มต้น API

เมื่อคุณกำหนดเส้นทางที่ถูกต้องพร้อมกับจุดแวะพักและงานที่เกี่ยวข้อง คุณก็จะเริ่มใช้ RouteOverview API ได้ การเริ่มต้นมอบเฟรมเวิร์กที่จำเป็นสำหรับการเชื่อมต่อระหว่าง Fleet Engine กับ API Route Overview API ควรเริ่มต้นด้วยออบเจ็กต์บริบทเดียวกันกับที่คุณใช้ในการเริ่มต้น DeliveryDriverApi ใน DriverSDK เนื่องจากออบเจ็กต์ดังกล่าวอ้างอิง รหัสยานพาหนะเดียวกันที่กำหนดไว้ก่อนหน้านี้ในออบเจ็กต์ DriverContext ของคุณ ตัวอย่างต่อไปนี้จะแสดงวิธีสร้างอินสแตนซ์ของ RouteOverviewApi


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

ขั้นตอนที่ 2 - ลงทะเบียนรถสำหรับกิจกรรมการเปลี่ยนเส้นทาง

เมื่อเริ่มต้น API แล้ว คุณสามารถใช้ออบเจ็กต์ VehicleRouteOverview เพื่อโต้ตอบกับความสามารถในภาพรวมเส้นทาง ซึ่งจะทำให้แอปพลิเคชันของคุณใช้ข้อมูลเส้นทางที่คุณระบุไว้ระหว่างการตั้งค่าเส้นทาง ใช้ Listener เหตุการณ์ API เพื่ออำนวยความสะดวกในการอัปเดตเหตุการณ์และการดึงข้อมูลเส้นทาง

เหตุการณ์เปลี่ยนเส้นทางจะเกิดขึ้นเมื่อมีการอัปเดตเส้นทางไปยังจุดแวะพักที่กำหนดให้รถ มีการจัดเรียงจุดแวะพักใหม่ หรือเมื่อ Fleet Engine อัปเดตข้อมูลเวลาถึงโดยประมาณ


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

ขั้นตอนที่ 3 - เปิดใช้ API

ตอนนี้คุณพร้อมที่จะใช้ข้อมูลเส้นทางแล้ว คุณต้องเปิดใช้ API เพื่ออนุญาตให้สามารถตอบสนองต่อเหตุการณ์ของยานพาหนะ โปรดทราบว่า API จะเริ่มต้นในสถานะปิดใช้เพื่อหลีกเลี่ยงการใช้แบนด์วิดท์ของเครือข่ายโดยไม่จำเป็น

vehicleRouteOverview.setRouteOverviewEnabled(true);

คุณหยุดการอัปเดตเหล่านี้ชั่วคราวได้ทุกเมื่อโดยเรียกใช้เมธอดเดียวกันด้วยค่า false

ขั้นตอนที่ 4 - วาดเส้นทางบน Google Maps

เมื่อได้รับรายการ RouteToVehicleStop แล้ว คุณจะใช้รายการดังกล่าวในแอปพลิเคชันได้ เช่น คุณสามารถวาดเส้นทางเส้นประกอบของเส้นทางในอินสแตนซ์ของ Google Maps ข้อมูลโค้ดต่อไปนี้แสดงตัวอย่างที่วาดเส้นประกอบเส้นทางในมุมมองแผนที่ และเพิ่มเครื่องหมายที่ด้านบนของจุดแวะพักแต่ละแห่ง

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

ซึ่งทำได้แทนการสมัครรับข้อมูลการอัปเดตเส้นทางผ่าน Listener เหตุการณ์

ขั้นตอนที่ 6 - ล้างข้อมูล

หากแอปของคุณไม่ต้องใช้ฟังก์ชันภาพรวมเส้นทางอีกต่อไป คุณควรตรวจดูว่าได้ทำความสะอาดแล้ว การล้างข้อมูลจะหลีกเลี่ยงหน่วยความจำ การประมวลผล และการใช้งานเครือข่ายที่ไม่จำเป็นในแอปพลิเคชัน

นํา Listener เหตุการณ์ที่เฉพาะเจาะจงออก

คุณควรนำ Listener เหตุการณ์ออกเมื่อ Listener ที่เฉพาะเจาะจงนั้นไม่จำเป็นอีกต่อไป

vehicleRouteOverview.removeOnRouteChangedEventListener(listener);

ล้าง Listener เหตุการณ์ทั้งหมด

เมื่อใช้กิจวัตรการล้างข้อมูล คุณสามารถนำ Listener เหตุการณ์ทั้งหมดที่ลงทะเบียนพร้อมกันออก

vehicleRouteOverview.clearEventListeners();

ล้างอินสแตนซ์ API ภาพรวมเส้นทาง

เมื่อใดก็ตามที่ไม่จำเป็นต้องใช้ภาพรวมของเส้นทางอีกต่อไปหรือรหัสของรถที่ติดตามมีการเปลี่ยนแปลง คุณสามารถเรียกใช้ API นี้เพื่อล้างการอ้างอิงภายในได้

vehicleRouteOverview.clearInstance();