API Tổng quan về tuyến đường

API Tổng quan về tuyến đường là một sản phẩm Giải pháp của Last Mile Fleet được xây dựng dựa trên DriverSDK. Nhờ công cụ này, bạn có thể truy xuất thông tin tuyến đường cho một loại xe nhất định, dưới dạng tìm nạp một lần hoặc liên tục bằng cách sử dụng trình nghe để cập nhật. API Tổng quan về tuyến đường hỗ trợ các loại thông tin sau:

  • Kế hoạch tuyến đường đầy đủ, bao gồm cả vị trí trạm dừng xe, thời gian di chuyển, khoảng cách
  • Tuyến đường hình nhiều đường giữa mỗi điểm dừng.

Tài liệu này mô tả các bước tích hợp với API cho ứng dụng của bạn.

Điều kiện tiên quyết

  • Bạn phải chạy ứng dụng Android bằng cách sử dụng kênh alpha của DriverSDK phiên bản 4.1.0 hoặc cao hơn. Bạn có thể sử dụng kênh alpha bằng cách sử dụng transportation-driver-alpha cho cấu phần phần mềm Maven.
  • API này sử dụng thông tin tuyến đường do Fleet Engine cung cấp thông qua API Phân phối. Bạn có thể cung cấp thông tin này thông qua các API trên DriverSDK (DeliveryDriverApi) hoặc trực tiếp đến Fleet Engine.

Các bước tích hợp

Phần này trình bày các bước cơ bản cần thiết để tích hợp ứng dụng trình điều khiển Android với API. Những hướng dẫn này có các giả định sau đây:

  • Bạn có một ứng dụng Android hiện có đã tích hợp với SDK trình điều khiển
  • Bạn đã khởi chạy DeliveryDriverApi trong ứng dụng bằng một đối tượng ngữ cảnh mà bạn có thể tìm thấy

Hãy xem phần Bắt đầu sử dụng SDK trình điều khiển dành cho Android để biết thông tin chi tiết.

Bước 0 - Thiết lập tuyến đường

Bạn có thể bỏ qua bước này nếu đã thiết lập Fleet Engine và có thể tạo trạm xe cũng như nhiệm vụ giao hàng.

Để tải thông tin về điểm dừng và nhiệm vụ vào Fleet Engine, bạn cần có một xe giao hàng được chỉ định cho một tuyến đường hợp lệ. Điều này là do API Tổng quan về tuyến đường yêu cầu các tuyến hợp lệ để tìm nạp dữ liệu. Các tuyến đường hợp lệ bao gồm một loạt điểm tham chiếu và điểm dừng, và một điểm dừng chỉ có thể tồn tại nếu nó có ít nhất một tác vụ liên kết. Xem hướng dẫn tích hợp API Fleet Engine để biết thêm thông tin.

Bước 1 – Khởi chạy API

Sau khi thiết lập một tuyến đường hợp lệ với các điểm dừng và nhiệm vụ được liên kết, bạn có thể khởi động API Tổng quan về tuyến đường. Quá trình khởi động cung cấp khung cần thiết để kết nối giữa Fleet Engine và API. Bạn phải khởi chạy API Tổng quan về tuyến đường bằng cùng một đối tượng ngữ cảnh mà bạn đã dùng để khởi động DeliveryDriverApi trong DriverSDK, vì đối tượng này tham chiếu đến cùng một mã xe được xác định trước đó trong đối tượng DriverContext. Ví dụ sau minh hoạ cách tạo một thực thể của RouteOverviewApi.


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

Bước 2 – Đăng ký xe để tham gia sự kiện thay đổi tuyến đường

Giờ đây, khi đã khởi động API, bạn có thể sử dụng đối tượng VehicleRouteOverview để tương tác với các chức năng tổng quan về tuyến đường. Điều này cho phép ứng dụng của bạn sử dụng thông tin về tuyến đường mà bạn đã cung cấp trong quá trình thiết lập tuyến đường. Sử dụng trình nghe sự kiện API để hỗ trợ việc cập nhật sự kiện và truy xuất tuyến.

Sự kiện thay đổi tuyến đường xảy ra bất cứ khi nào đường dẫn đến bất kỳ điểm dừng nào được chỉ định cho xe được cập nhật, sắp xếp lại một điểm dừng hoặc khi Fleet Engine cập nhật thông tin ETA.


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

Bước 3 – Bật API

Bây giờ, khi đã sẵn sàng sử dụng thông tin tuyến đường, bạn phải bật API để cho phép API này phản hồi các sự kiện trên xe. Hãy nhớ rằng API được khởi chạy ở trạng thái đã tắt để tránh sử dụng băng thông mạng một cách không cần thiết.

vehicleRouteOverview.setRouteOverviewEnabled(true);

Bạn có thể tạm dừng các bản cập nhật này bất cứ lúc nào bằng cách gọi cùng một phương thức với giá trị là false.

Bước 4 - Vẽ tuyến đường trên Google Maps

Sau khi nhận được danh sách RouteToVehicleStop, bạn có thể sử dụng danh sách đó trong ứng dụng của mình. Ví dụ: bạn có thể vẽ đường dẫn nhiều đường trong một phiên bản Google Maps. Đoạn mã sau đây cho thấy một ví dụ về cách vẽ hình nhiều đường trên chế độ xem bản đồ và thêm điểm đánh dấu ở đầu mỗi vị trí dừng.

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

Ảnh chụp màn hình cho thấy hình ảnh tổng quan về tuyến đường

Thao tác này sẽ dẫn đến chế độ xem tương tự như ảnh chụp màn hình ở bên phải:

Bước 5 – Lấy ảnh chụp nhanh tuyến đường

Nếu muốn ứng dụng của mình thực hiện lệnh gọi một lần để truy xuất ảnh chụp nhanh về thông tin tuyến đường hiện tại, bạn có thể sử dụng phương thức sau để truy xuất dữ liệu đó:

ListenableFuture<ImmutableList<RouteToVehicleStop> future = vehicleRouteOverview.getRouteToVehicleStops();
ImmutableList<RouteToVehicleStop> stops = future.get();

Bạn có thể thực hiện việc này thay vì đăng ký nhận thông tin cập nhật về tuyến đường thông qua trình nghe sự kiện.

Bước 6 – Dọn dẹp

Nếu ứng dụng của bạn không cần chức năng tổng quan về tuyến đường nữa, hãy đảm bảo bạn đã dọn dẹp. Việc dọn dẹp sẽ giúp tránh mức tiêu thụ bộ nhớ, quá trình xử lý và mạng không cần thiết trong ứng dụng của bạn.

Xoá một trình nghe sự kiện cụ thể

Bạn nên xoá một trình nghe sự kiện khi không cần một trình nghe cụ thể nữa.

vehicleRouteOverview.removeOnRouteChangedEventListener(listener);

Xoá tất cả trình nghe sự kiện

Trong quy trình dọn dẹp, bạn có thể xoá tất cả những trình nghe sự kiện đã đăng ký cùng một lúc.

vehicleRouteOverview.clearEventListeners();

Xoá phiên bản API Tổng quan về tuyến đường

Bất cứ khi nào không cần thông tin Tổng quan về tuyến đường hoặc mã của chiếc xe đang được theo dõi đã thay đổi, bạn có thể gọi API này để xoá thông tin tham chiếu nội bộ.

vehicleRouteOverview.clearInstance();