有時，您可能需要規劃應用程式提供給使用者的路線。使用 Routes API、Routes Preferred API 或 Route Optimization API 的路線權杖，可協助您為規劃路線指定兩項資訊：
路線的折線
路線目標
以下列舉幾個可能的轉送目標：
盡可能縮短運送時間：外送餐點的商家可能希望盡可能縮短外送餐點所需的時間。
盡可能縮短行程時間或減少燃料消耗：物流公司可能希望提高司機效率並降低燃料成本。
盡可能縮短抵達目的地的時間：服務派遣作業可能需要盡可能縮短操作員抵達工作地點的時間。
降低成本並提高安全性：多元計程車業者可能想找出乘客費用較低的路線，並基於安全考量避開特定區域。
如要進一步瞭解如何使用路線權杖規劃路線，請參閱 Routes API 的「取得路線權杖」和 Route Optimization API 的「轉換折線和路線權杖」。
為何要使用路徑權杖設定路徑目標
使用 Routes API、Routes Preferred API 或 Route Optimization API 的路線權杖，可進一步控管提供的路線：
預先規劃路線，供 Navigation SDK 使用。
選擇 Navigation SDK 應使用的最佳路線。在 Routes API 中產生路線時，如果要求路線權杖，系統會為每條產生的路線提供路線權杖。接著，您可以選擇要使用的路線權杖，並傳遞給 Navigation SDK。
預先估算價格，包括預計到達時間和距離。雖然實際費用和時間可能有所不同，但這項預估值可縮小預期路線費用與實際路線費用之間的差距。
指定更進階的路線目標，例如環保路線或最短路線。
路徑權杖的運作方式
您可以使用 Routes API、Routes Preferred API 或 Route Optimization API，根據路線目標規劃路線。您可以將上述任一 API 傳回的路徑權杖傳遞至 Navigation SDK，引導車輛行駛。
要求及使用路徑權杖時，會發生以下情況：
Routes API、Routes Preferred API 或 Route Optimization API 會傳回加密路徑權杖，其中包含路徑折線和路徑目標。
將路徑權杖傳遞至 Navigation SDK。
Navigation SDK 會按照規劃路線開始導航，即使有更快的路線也一樣。
在行程中，如果路況或道路狀況有變，或車輛偏離規劃路線，Navigation SDK 會根據路線權杖中設定的路線目標和路線選項，計算新路線。
這項程序可盡量縮短實際路線與規劃路線之間的距離。
未完全按照規劃路線行駛的可能原因
導航會從規劃的路線開始，但實際路線可能會與規劃路線不同，例如：
- 車輛從預定起點以外的位置出發。
- 行程期間路況或道路條件有變。
- 車輛偏離預定路線。
這些差異可能會影響您規劃的距離、預計到達時間和其他重要行程品質。
使用路線權杖規劃路線
您可以建立路徑權杖，然後傳遞至 Navigation SDK，藉此規劃路徑，步驟如下：
步驟 1：使用 Routes API、Routes Preferred API 或 Route Optimization API 建立路線權杖
使用下列任一方法要求路線權杖：
設定 Routes API 或 Routes Preferred 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.setDestinations方法傳遞路線權杖給 Navigation SDK，並指定建立路線權杖時使用的相同目的地路線控點：setDestinations(List
destinations, CustomRoutesOptions customRoutesOptions, DisplayOptions displayOptions); 例如：
CustomRoutesOptions customRoutesOptions = CustomRoutesOptions.builder() .setRouteToken(routeToken) .setTravelMode(TravelMode.DRIVING) .build();
Navigator.setDestinations 方法會傳回要求狀態。如果找到從車輛位置到指定目的地的路線，則會傳回 RouteStatus.OK。
如要進一步瞭解這個方法，請參閱 Navigator.setDestinations。
範例
以下程式碼範例示範如何使用路線權杖指定規劃路線。
ArrayList <Waypoint> destinations = Lists.newArrayList();
Waypoint waypoint1 =
Waypoint.builder()
.setLatLng(10, 20)
.setTitle("title")
.setVehicleStopover(true)
.build();
destinations.add(waypoint1);
Waypoint waypoint2 =
Waypoint.builder()
.setPlaceId("ChIJYV-J-ziuEmsRIMyoFaMedU4")
.setTitle("title")
.setVehicleStopover(true)
.build();
destinations.add(waypoint2);
String routeToken = "route token returned by Routes API";
CustomRoutesOptions customRoutesOptions =
CustomRoutesOptions.builder()
.setRouteToken(routeToken)
.setTravelMode(TravelMode.DRIVING)
.build();
// Existing flow to get a Navigator.
NavigationApi.getNavigator(...);
// Existing flow for requesting routes.
ListenableResultFuture<RouteStatus> routeStatusFuture =
navigator.setDestinations(destinations, customRoutesOptions);
// Or with display options.
DisplayOptions displayOptions = new DisplayOptions();
ListenableResultFuture<RouteStatus> routeStatusFuture =
navigator.setDestinations(destinations, customRoutesOptions, displayOptions);
路徑權杖和 Navigation SDK 的互動方式
Navigation SDK 處理規劃路線的方式如下：
覆寫先前設定的目的地。
使用車輛起始位置。
根據路況和交通狀況調整。請參閱「為什麼可能無法完全按照規劃路線行駛」。
使用路徑權杖中設定的路線選項，而非應用程式中的下列設定，包括在行程期間計算新路線時：
RoutingOptions.avoidHighways()RoutingOptions.avoidTolls()RoutingOptions.avoidFerries()Navigator.setLicensePlateRestrictionInfo()- 應用程式中設定的交通方式
計算或調整路線時，遵循下列設定：
路線權杖中的路線目標，例如節能路線或最短路線。如果 Navigation SDK 必須調整路線，會使用您在要求路線權杖時指定的路線目標。
應用程式中與路線控點相關的選項，例如偏好的道路側。請使用與要求路線權杖時指定的相同路線控點相關選項。