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

Route Overview API (API Tổng quan về tuyến đường) là một sản phẩm Giải pháp Last Mile Fleet được xây dựng dựa trên DriverSDK. Nhờ vậ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 vị trí dừng xe, thời gian di chuyển, khoảng cách
  • Tuyến đường 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 alpha kênh 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 mã 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 giao hàng. 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 cho 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:

  • 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 với một đối tượng ngữ cảnh mà bạn có thể tìm thấy

Hãy xem bài viết 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 dừng xe cũng như nhiệm vụ giao hàng.

Để tải thông tin về điểm dừng và nhiệm vụ cho 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ệ. Lý do là 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. Ngoài ra, một điểm dừng chỉ có thể tồn tại nếu có ít nhất một tác vụ liên quan. 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 chạy cung cấp khung cần thiết để kết nối giữa Fleet Engine và API. Bạn nên khởi chạy API Tổng quan về tuyến đường bằng chính đố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 cho các sự kiện thay đổi tuyến đường

Bây giờ, bạn đã khởi chạy API, bạn có thể sử dụng đối tượng VehicleRouteOverview để tương tác với các tính năng tổng quan về tuyến đường. Điều này cho phép ứng dụng của bạn 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. 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 đường.

Sự kiện thay đổi tuyến đường xảy ra bất cứ khi nào đường đi đến một điểm dừng bất kỳ được chỉ định cho xe được cập nhật, mộ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ề 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 về 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 bị tắt để tránh tiêu thụ 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ị của 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 kẻ trong một phiên bản Google Map. Đoạn mã sau đây cho thấy một ví dụ vẽ hình nhiều đường trên tuyến đườ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

Kết quả là một khung hiển thị sẽ tương tự như ảnh chụp màn hình ở bên phải:

Bước 5 – Xem ả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 thông tin tổng quan 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 tuyến đườ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, thì bạn nên đảm bảo rằng mình đã dọn dẹp. Việc dọn dẹp sẽ giúp bạn tránh sử dụng bộ nhớ, xử lý và tiêu thụ mạng không cần thiết trong ứng dụng.

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ả trình nghe sự kiện khác nhau đã đăng ký cùng một lúc.

vehicleRouteOverview.clearEventListeners();

Xoá thực thể API Tổng quan về tuyến đường

Bất cứ khi nào không còn cần đến thẻ Tổng quan về tuyến đường hoặc mã nhận dạng của 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();