有時，您可能需要規劃應用程式提供給使用者的路線。使用 Routes API 或 Route Optimization API 的路線權杖，可協助您為規劃路線指定兩項資訊：
路線的折線
路線目標
以下列舉幾個可能的轉送目標：
盡可能縮短送達時間：外送餐點的商家可能希望盡可能縮短送達時間。
盡可能縮短行程時間或減少燃料消耗：物流公司可能想提高司機效率，並降低燃料成本。
盡可能縮短抵達目的地的時間：服務調度作業可能需要盡可能縮短操作員抵達工作地點的時間。
降低成本並提高安全性：多元計程車業務可能需要尋找乘客費用較低的路線，並基於安全考量避開特定區域。
如要進一步瞭解如何使用路線權杖規劃路線，請參閱 Routes API 的「取得路線權杖」和 Route Optimization API 的「轉換折線和路線權杖」。
為何要使用路線權杖設定路線目標
使用 Routes API 或 Route Optimization API 的路線權杖，可進一步控管提供的路線：
預先規劃路線，供 Navigation SDK 使用。
選擇 Navigation SDK 要使用的最佳路線。在 Routes API 中產生路線時，如果要求路線權杖，系統會為每條產生的路線提供路線權杖。接著，您可以選擇要使用的路線權杖，並傳遞至 Navigation SDK。
預先估算價格，包括預估預計到達時間和距離。雖然實際費用和時間可能有所不同，但這項預估值可縮小預期路線費用與實際路線費用之間的差距。
指定更進階的路線目標，例如環保路線或最短路線。
路徑權杖的運作方式
您可以使用 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 要求，以符合使用路線權杖的規定：
- 將
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);在回呼中檢查路徑狀態。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.avoidHighwaysRoutingOptions.avoidTollsRoutingOptions.avoidFerriesNavigator.setLicensePlateRestrictionInfo- 應用程式中設定的交通方式
計算或調整路線時，遵循下列設定：
- 路線權杖中的路線目標，例如節能路線或最短路線。如果 Navigation SDK 必須調整路線，會使用您在要求路線權杖時指定的路線目標。
- 路線權杖中與路線控點相關的選項，例如道路偏好設定。