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

ผลิตภัณฑ์หรือฟีเจอร์นี้เป็นการทดสอบ (ก่อนเวอร์ชันสำหรับผู้ใช้ทั่วไป) ผลิตภัณฑ์และฟีเจอร์ก่อนเวอร์ชันสำหรับผู้ใช้ทั่วไปอาจมีการรองรับอย่างจำกัด และการเปลี่ยนแปลงในผลิตภัณฑ์และฟีเจอร์ก่อนเวอร์ชันสำหรับผู้ใช้ทั่วไปอาจใช้ไม่ได้กับเวอร์ชันก่อนเวอร์ชันสำหรับผู้ใช้ทั่วไปอื่นๆ ข้อเสนอก่อนเวอร์ชันสำหรับผู้ใช้ทั่วไปจะอยู่ภายใต้ข้อกำหนดเฉพาะของบริการ Google Maps Platform ดูข้อมูลเพิ่มเติมได้ในคำอธิบายขั้นตอนการเปิดตัว

สำคัญ: ขณะนี้ RouteOverview API มีให้บริการเฉพาะใน Android

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

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

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

สิ่งที่ต้องดำเนินการก่อน

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

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

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

• คุณมีแอป Android ที่ผสานรวมกับ Driver 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);
}

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

ขั้นตอนที่ 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();