Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

경로 계획하기

앱에서 사용자에게 제공하는 경로를 계획해야 하는 경우가 있습니다. Routes API 또는 Route Optimization API의 경로 토큰을 사용하면 계획된 경로에 대해 다음 두 가지를 지정할 수 있습니다.

경로의 다중선
경로 목표

예를 들어 다음과 같은 라우팅 목표가 있을 수 있습니다.

배송 시간 최소화: 음식을 배달하는 비즈니스는 음식을 배달하는 데 걸리는 시간을 최소화하려고 할 수 있습니다.
이동 시간 또는 연료 소비 최소화: 물류 비즈니스는 운전자의 효율성을 개선하고 연료 비용을 줄이기를 원할 수 있습니다.
목적지까지의 시간 최소화: 서비스 파견 작업에서 작업자가 작업 요청을 처리하는 데 걸리는 시간을 최소화할 수 있습니다.
비용 절감 및 안전 개선: 차량 공유 비즈니스에서는 탑승자에게 더 저렴한 비용이 들고 안전상의 이유로 특정 지역을 피하는 경로를 찾을 수 있습니다.

경로 토큰을 사용하여 경로를 계획하는 방법에 관한 자세한 내용은 Routes API의 경로 토큰 가져오기 및 Route Optimization API의 전환 다중선 및 경로 토큰을 참고하세요.

경로 목표에 경로 토큰을 사용하는 이유

Routes API 또는 Route Optimization API의 경로 토큰을 사용하면 제공되는 경로를 더 세부적으로 제어할 수 있습니다.

Navigation SDK에서 사용할 경로를 미리 계획합니다.
Navigation SDK에서 사용할 최적의 경로를 선택합니다. Routes API에서 경로를 생성할 때 경로 토큰을 요청하면 생성된 각 경로에 대한 경로 토큰을 받게 됩니다. 그런 다음 Navigation SDK에 전달할 때 사용할 경로의 토큰을 선택할 수 있습니다.
ETA 및 거리 추정치를 포함하여 사전에 가격을 추정합니다. 실제 비용과 시간은 다를 수 있지만 이 추정치를 사용하면 예상 경로 비용과 실제 경로 비용 간의 차이가 줄어듭니다.
친환경 경로 또는 최단 경로와 같은 고급 경로 목표를 지정합니다.

경로 토큰의 작동 방식

Routes API 또는 Route Optimization API를 사용하여 경로 목표를 사용해 경로를 계획할 수 있습니다. 이러한 API 중 하나에서 반환된 경로 토큰을 Navigation SDK에 전달하여 차량의 경로를 안내할 수 있습니다.

경로 토큰을 요청하고 사용하면 다음과 같은 상황이 발생합니다.

Routes API 또는 Route Optimization API는 경로 다중선과 경로 목표가 포함된 암호화된 경로 토큰을 반환합니다.
경로 토큰을 Navigation SDK에 전달합니다.
Navigation SDK는 더 빠른 경로가 있더라도 계획된 경로에서 내비게이션을 시작합니다.
이동 중에 교통 상황이나 도로 상황이 변경되거나 차량이 계획된 경로를 벗어나면 Navigation SDK는 경로 토큰에 설정된 경로 목표 및 경로 옵션을 따르는 새 경로를 계산합니다.

이 프로세스는 실제 경로가 계획된 경로에 최대한 가깝도록 합니다.

계획된 경로를 정확하게 따르지 않을 수 있는 이유

내비게이션은 계획된 경로에서 시작되지만 실제 경로는 다음과 같은 상황에서 다를 수 있습니다.

차량이 계획된 출발지에서 멀리 떨어진 곳에서 출발합니다.
이동 중에 교통 상황이나 도로 상황이 변경되는 경우
차량이 계획된 경로를 벗어납니다.

이러한 차이는 계획한 거리, 도착 예정 시간, 기타 중요한 이동 품질에 영향을 미칠 수 있습니다.

경로 토큰을 사용하여 경로 계획

다음 단계에 설명된 대로 경로 토큰을 만든 후 Navigation SDK에 전달하여 경로를 계획할 수 있습니다.

1단계: Routes API 또는 Route Optimization API를 사용하여 경로 토큰 만들기

다음 방법 중 하나를 사용하여 경로 토큰을 요청합니다.
- Routes API: computeRoutes. Routes API에서 경로 토큰을 요청하는 방법에 관한 자세한 내용은 경로 계산 및 경로 토큰 가져오기를 참고하세요.
- Route Optimization API: optimizeTours 또는 batchOptimizeTours Route Optimization API에서 경로 토큰을 요청하는 방법에 대한 자세한 내용은 전환 다중선 및 경로 토큰을 참고하세요.
경로 토큰 사용 요구사항을 충족하도록 Routes API 요청을 설정합니다.
- travelMode를 DRIVE 또는 TWO_WHEELER으로 설정합니다.
- routingPreference를 TRAFFIC_AWARE 또는 TRAFFIC_AWARE_OPTIMAL으로 설정합니다.
- Via 경유지를 사용하지 마세요.

2단계: Navigation SDK에 경로 토큰 전달

경로 토큰 저장: Navigation SDK에서 경로 토큰을 저장할 문자열을 설정합니다. 예를 들면 다음과 같습니다.

String routeToken = "route token returned by Routes API";

반환된 경로 토큰의 예는 다음과 같습니다.

{
// Other fields
"routeToken": "CqMBCjoKCJQOor5DHcwiEhBon3XpHXFnVvDeWMwd9PpAGgz6wtnFDKIBrAHTARpCApUDSggAAAAACjcrP3gBEAQaTApKChgKDQoCCAERAAAAAACAZkAR3SQGgZUXdUASEggAEAMQBhATEBIYAkIEGgIIBSIYChZ2VEJiWlBPSkk1aU5wUVRzNTV5d0FRKAEiFQBcJuds-Efh-2QZhOMTtUCCxEVL_g",
}

Navigator.setDestinationsWithToken 메서드를 사용하여 Navigation SDK에 경로 토큰을 전달합니다. Navigation SDK는 경로 토큰에서 목적지와 경로 옵션을 가져오므로 경유지나 이동 수단을 전달할 필요가 없습니다.
```
setDestinationsWithToken(String routeToken, RouteDescriptionLoadCallback callback);
setDestinationsWithToken(String routeToken, DisplayOptions displayOptions, RouteDescriptionLoadCallback callback);
```
참고: 앱에서 8.1 이전 버전의 Navigation SDK를 사용하는 경우 대신 CustomRoutesOptions 를 사용하는 지원 중단된 setDestinations 메서드를 사용하고 경로 토큰을 만드는 데 사용한 것과 동일한 목적지 경유지를 전달합니다.

콜백에서 경로 상태를 확인합니다. Navigation SDK가 경로 계산을 완료하면 RouteDescription를 콜백에 전달합니다. 차량 위치에서 경로 토큰의 목적지까지의 경로를 찾으면 RouteDescription.getRouteStatus가 Navigator.RouteStatus.OK를 반환하고 안내를 시작할 수 있습니다. 예를 들면 다음과 같습니다.

navigator.setDestinationsWithToken(
    routeToken,
    routeDescription -> {
      if (routeDescription.getRouteStatus() == Navigator.RouteStatus.OK) {
        navigator.startGuidance();
      }
    });

Navigation SDK에서 경로 토큰을 적용했는지 확인하기

경로 상태가 OK이면 Navigation SDK가 경로를 찾았지만 계획된 경로가 아닐 수도 있습니다. 경로가 계획된 경로와 일치하는지 확인하려면 콜백에서 다음 단계를 따르세요.

RouteDescription.getRouteStatus가 Navigator.RouteStatus.OK를 반환하는지 확인합니다. Navigation SDK는 경로를 찾은 경우에만 경로 토큰 세부정보를 제공합니다. 자세한 내용은 2단계를 참조하세요.
RouteDescription.getRouteTokenExecutionDetails를 호출하여 RouteTokenExecutionDetails 객체를 가져옵니다. 서버에서 경로 토큰 세부정보를 제공하지 않으면 이 메서드는 null를 반환합니다.
RouteTokenExecutionDetails 객체에서 getTokenExecutionStatus를 호출합니다. TOKEN_SUCCESSFULLY_APPLIED를 반환하면 경로가 계획된 경로와 일치하는 것입니다. 다른 상태는 경로가 계획된 경로와 다를 수 있음을 의미합니다. 각 상태에 대한 자세한 내용은 토큰 실행 상태 값을 참조하세요.
선택사항: 상태가 TOKEN_SUCCESSFULLY_APPLIED인 경우 동일한 RouteTokenExecutionDetails 객체에서 getResolvedParameters를 호출하여 경로에서 사용하는 경로 옵션(예: 유료 도로를 피하는지 여부)을 확인합니다. 자세한 내용은 확정된 라우팅 옵션을 참조하세요.

토큰 실행 상태 값

경로 상태가 OK인 경우 토큰 실행 상태와 관계없이 안내를 시작할 수 있습니다. 상태는 경로가 계획된 경로를 따르는지 여부를 알려줍니다.

상태	계획된 경로를 따릅니다.	설명
`TOKEN_SUCCESSFULLY_APPLIED`	예	Navigation SDK가 경로 토큰을 적용했습니다.
`TOKEN_APPLIED_WITH_LOCATION_MISMATCH`	꼭 그렇지는 않습니다.	경로 요청의 위치가 경로 토큰의 일치하는 위치에서 25미터 이상 떨어져 있으므로 Navigation SDK에서 계획된 경로를 다시 빌드할 수 없습니다. `setDestinationsWithToken`의 경우 기기가 경로 토큰의 출발지에서 25미터 이상 떨어져 있음을 의미합니다. 경로는 여전히 목적지로 이동하지만 Navigation SDK는 경로 토큰의 경로 옵션(예: 통행료 회피)을 사용하는지 확인할 수 없습니다.
`TOKEN_IGNORED_OTHER`	꼭 그렇지는 않습니다.	Navigation SDK가 다른 이유로 계획된 경로를 다시 만들 수 없습니다(예: 계획된 경로의 도로가 폐쇄됨). 경로는 여전히 목적지로 이동하지만 Navigation SDK는 경로 토큰의 경로 옵션(예: 통행료 회피)을 사용하는지 확인할 수 없습니다.
`NO_TOKEN_PROVIDED`	해당 없음	경로 요청에 경로 토큰이 포함되지 않았습니다.
`UNKNOWN`	알 수 없음	상태를 알 수 없습니다.

경로가 계획된 경로를 따르지 않고 정확한 경로가 중요한 경우(예: 가격을 계산하는 데 사용한 경우) 상태를 기록하거나 차량의 현재 위치에서 새 경로 토큰을 요청합니다.

해결된 라우팅 옵션

getResolvedParameters는 RouteTokenResolvedParameters 객체를 반환하거나, 경로 옵션을 사용할 수 없는 경우 null를 반환합니다. RouteTokenResolvedParameters에는 다음 메서드가 있습니다.

getTravelMode: 경로에서 사용하는 이동 수단입니다(예: RoutingOptions.TravelMode.DRIVING). 또한 Navigation SDK는 경로에서 일치하는 값이 없는 이동 수단을 사용하거나 이동 수단을 사용할 수 없는 경우 RoutingOptions.TravelMode.DRIVING를 보고합니다.
getAvoidTolls: 경로가 유료 도로를 피하는지 여부입니다.
getAvoidHighways: 경로가 고속도로를 제외하는지 여부입니다.
getAvoidFerries: 경로가 페리를 피하는지 여부입니다.

예

다음 코드 예는 경로 토큰을 사용하여 경로를 계획하고, Navigation SDK가 토큰을 적용했는지 확인하고, 안내를 시작하는 방법을 보여줍니다.

String routeToken = "route token returned by Routes API";

// Existing flow to get a Navigator.
NavigationApi.getNavigator(...);

// Handle the result of the route calculation.
RouteDescriptionLoadCallback callback =
    routeDescription -> {
      // Check whether the Navigation SDK found a route.
      if (routeDescription.getRouteStatus() != Navigator.RouteStatus.OK) {
        Log.w(TAG, "Route status: " + routeDescription.getRouteStatus());
        return;
      }

      // Check whether the Navigation SDK applied the route token.
      RouteTokenExecutionDetails executionDetails =
          routeDescription.getRouteTokenExecutionDetails();
      if (executionDetails == null) {
        Log.i(TAG, "Route token details aren't available.");
      } else if (executionDetails.getTokenExecutionStatus()
          != RouteTokenExecutionDetails.TokenExecutionStatus.TOKEN_SUCCESSFULLY_APPLIED) {
        Log.w(TAG, "The route might differ from your planned route.");
      }

      navigator.startGuidance();
    };

// Set destinations using the route token.
navigator.setDestinationsWithToken(routeToken, callback);

// Or with display options.
DisplayOptions displayOptions = new DisplayOptions();
navigator.setDestinationsWithToken(routeToken, displayOptions, callback);

경로 토큰과 Navigation SDK의 상호작용 방식

Navigation SDK는 계획된 경로를 다음과 같이 처리합니다.

이전에 설정된 모든 도착 페이지를 재정의합니다.
차량 시작 위치를 사용합니다.
도로 및 교통 상황에 따라 조정됩니다. 계획된 경로를 정확하게 따르지 않는 이유를 참고하세요.

이동 중에 새 경로를 계산할 때를 포함하여 앱의 다음 설정 대신 경로 토큰에 설정된 경로 옵션을 사용합니다.
- RoutingOptions.avoidHighways
- RoutingOptions.avoidTolls
- RoutingOptions.avoidFerries
- Navigator.setLicensePlateRestrictionInfo
- 앱에 설정된 이동 모드

경로를 계산하거나 조정할 때 다음 설정을 따릅니다.
- 경로 토큰의 경로 목표(예: 친환경 경로 또는 최단 경로) Navigation SDK에서 경로를 조정해야 하는 경우 경로 토큰을 요청할 때 지정한 경로 목표를 사용합니다.
- 경로 토큰의 경유지 관련 옵션(예: 도로변 환경설정)