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. Với ứng dụng này, bạn có thể truy xuất thông tin tuyến đường cho một chiếc xe cụ thể, ở 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. Chiến lược phát hành đĩa đơn 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 phiên bản alpha của DriverSDK phiên bản 4.1.0 hoặc cao hơn. Có kênh alpha bằng cách sử dụng transportation-driver-alpha cho cấu phần phần mềm Maven.
• API sử dụng thông tin tuyến đường do Fleet Engine cung cấp thông qua API Phân phối. 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 tới Fleet Engine.

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

Phần này đề cập đến 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 của bạn với API. Những hướng dẫn này có các giả định sau đây:

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

Xem 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 điểm dừng xe và nhiệm vụ giao hàng.

Để tải thông tin về điểm dừng và nhiệm vụ lên Fleet Engine, bạn cần có một chiếc xe giao hàng được gán cho một tuyến hợp lệ. Điều này là do API Tổng quan về tuyến đường yêu cầu để tìm nạp dữ liệu. 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 liên kết với ít nhất một điểm dừng công việc. 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 trạm dừng và nhiệm vụ có liên quan, bạn có thể khởi chạy API Tổng quan về tuyến đường. Khởi tạo cung cấp khung cần thiết để kết nối giữa Fleet Engine và API. Tuyến đường API Tổng quan phải được khởi chạy với cùng một đối tượng ngữ cảnh mà bạn đã dùng khởi tạo DeliveryDriverApi trong DriverSDK vì đối tượng tham chiếu đến cùng một mã xe được xác định trước đó trong đối tượng DriverContext. Nội dung sau đây ví dụ 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 chạy API, bạn có thể sử dụ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 để sử dụng thông tin 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 chiếc xe được cập nhật, điểm dừng được sắp xếp lại hoặc khi Fleet Engine cập nhật Thông tin về giờ đến dự kiến.

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 ứng dụng phản hồi các sự kiện trên xe. Hãy nhớ rằng API được khởi chạy trong disabled (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 nội dung 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 bằng hàm giá trị của false.

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

Sau khi nhận được danh sách các RouteToVehicleStop, bạn có thể sử dụng nó trong . Ví dụ: bạn có thể vẽ con đường hình nhiều đường trong Google Maps thực thể. Đoạn mã sau đây cho thấy một ví dụ vẽ tuyến đường hình nhiều đường trên chế độ xem bản đồ và thêm các điểm đánh dấu ở đầu mỗi vị trí điểm 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);
}

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 bạn 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 thông tin về 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 cần chức năng tổng quan về tuyến đường, bạn nên đảm bảo bạn đã dọn dẹp. Việc dọn dẹp sẽ tránh được tình trạng bộ nhớ, quá trình xử lý và mức tiêu thụ mạng 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 một trình nghe cụ thể không còn hoạt động nữa nếu cần.

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