Route Overview API

이 제품 또는 기능은 실험용(GA 이전) 버전입니다. GA 이전 제품과 기능에 대한 지원이 제한될 수 있으며 GA 이전 제품과 기능의 변경사항이 다른 GA 이전 버전과 호환되지 않을 수 있습니다. GA 이전 버전 제품 또는 서비스에는 Google Maps Platform 서비스별 약관이 적용됩니다. 자세한 내용은 출시 단계 설명을 참고하세요.

중요: Route Overview API는 현재 Android에서만 사용할 수 있습니다.

Route Overview API는 DriverSDK를 기반으로 빌드된 라스트 마일 Fleet 솔루션 제품입니다. 이를 통해 특정 차량의 경로 정보를 일회성 가져오기로 가져오거나 업데이트 리스너를 사용하여 지속적으로 검색할 수 있습니다. Route Overview API는 다음과 같은 종류의 정보를 지원합니다.

• 차량 정차 위치, 이동 시간, 거리를 포함한 전체 경로 계획
• 각 정류장 사이의 경로 다중선 경로입니다.

이 문서에서는 애플리케이션용 API와의 통합 단계를 설명합니다.

기본 요건

• DriverSDK v4.1.0 이상의 알파 채널을 사용하여 Android 애플리케이션을 실행해야 합니다. 알파 채널은 Maven artifactId에 transportation-driver-alpha를 사용하여 사용할 수 있습니다.
• API는 Deliveries API를 통해 Fleet Engine이 제공하는 경로 정보를 사용합니다. DriverSDK의 API(DeliveryDriverApi)를 통해 제공하거나 Fleet Engine에 직접 제공할 수 있습니다.

통합 단계

이 섹션에서는 Android 드라이버 앱을 API와 통합하는 데 필요한 기본 단계를 설명합니다. 이 안내에서는 다음과 같이 가정합니다.

• 드라이버 SDK와 이미 통합된 기존 Android 앱이 있는 경우
• 찾을 수 있는 컨텍스트 객체를 사용하여 앱의 DeliveryDriverApi를 초기화했습니다.

자세한 내용은 Android용 드라이버 SDK 시작하기를 참고하세요.

0단계 - 경로 설정

이미 Fleet Engine을 설정했고 차량 정류장 및 배송 태스크를 만들 수 있는 경우 이 단계를 건너뛰어도 됩니다.

정류장 및 작업 정보를 Fleet Engine에 로드하려면 유효한 경로에 할당된 배송 차량이 필요합니다. Route Overview API가 데이터를 가져오려면 유효한 경로가 필요하기 때문입니다. 유효한 경로는 일련의 경유지와 정류장으로 구성되며 정류장은 관련 작업이 하나 이상 있는 경우에만 존재할 수 있습니다. 자세한 내용은 Fleet Engine API 통합 가이드를 참고하세요.

1단계 - API 초기화

관련 정류장 및 태스크와 함께 유효한 경로를 설정하면 Route Overview API를 초기화할 수 있습니다. 초기화는 Fleet Engine과 API 간의 연결에 필요한 프레임워크를 제공합니다. Route Overview API는 DriverSDK에서 DeliveryDriverApi를 초기화하는 데 사용한 것과 동일한 컨텍스트 객체로 초기화해야 합니다. 객체가 이전에 DriverContext 객체에 정의된 것과 동일한 차량 ID를 참조하기 때문입니다. 다음 예는 RouteOverviewApi 인스턴스를 만드는 방법을 보여줍니다.

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

참고: Route Overview API를 초기화하면 설정을 완료하는 동안 불필요한 대역폭이 소모되지 않도록 자동으로 사용 중지 상태로 설정됩니다.

2단계 - 경로 변경 이벤트에 차량 등록

이제 API를 초기화했으므로 VehicleRouteOverview 객체를 사용하여 경로 개요 기능과 상호작용할 수 있습니다. 이렇게 하면 애플리케이션에서 경로 설정 중에 제공한 경로 정보를 사용할 수 있습니다. API 이벤트 리스너를 사용하여 이벤트 업데이트 및 경로 검색을 용이하게 합니다.

경로 변경 이벤트는 차량에 할당된 정류장 경로가 업데이트되거나, 정류장이 다시 정렬되거나, Fleet Engine이 도착예정시간 정보를 업데이트할 때마다 발생합니다.

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

3단계 - API 사용 설정

이제 경로 정보를 사용할 준비가 되었으므로 API를 사용 설정하여 차량 이벤트에 응답하도록 해야 합니다. API는 불필요한 네트워크 대역폭 소비를 방지하기 위해 사용 중지 상태로 초기화됩니다.

vehicleRouteOverview.setRouteOverviewEnabled(true);

false 값으로 동일한 메서드를 호출하여 언제든지 이러한 업데이트를 일시중지할 수 있습니다.

4단계 - Google 지도에 경로 그리기

RouteToVehicleStop 목록을 가져오면 애플리케이션에서 사용할 수 있습니다. 예를 들어 Google 지도 인스턴스에서 경로 다중선 경로를 그릴 수 있습니다. 다음 코드 스니펫은 지도뷰에 경로 다중선을 그리고 각 정류장 위치 위에 마커를 추가하는 예를 보여줍니다.

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

이벤트 리스너를 통해 경로 업데이트를 구독하는 대신 이렇게 할 수 있습니다.

6단계 - 정리

앱에 경로 개요 기능이 더 이상 필요하지 않으면 경로를 삭제했는지 확인해야 합니다. 정리를 수행하면 애플리케이션에서 불필요한 메모리, 처리, 네트워크 소비를 방지할 수 있습니다.

특정 이벤트 리스너 삭제

특정 리스너가 더 이상 필요하지 않으면 이벤트 리스너를 삭제해야 합니다.

vehicleRouteOverview.removeOnRouteChangedEventListener(listener);

모든 이벤트 리스너 지우기

정리 루틴의 일부로 한 번에 등록된 모든 다른 이벤트 리스너를 삭제할 수 있습니다.

vehicleRouteOverview.clearEventListeners();

Route Overview API 인스턴스 삭제

경로 개요가 더 이상 필요하지 않거나 추적 중인 차량의 ID가 변경될 때마다 이 API를 호출하여 내부 참조를 지울 수 있습니다.

vehicleRouteOverview.clearInstance();