規劃路線

有時，您可能需要規劃應用程式提供給使用者的路線。使用 Routes API、Routes Preferred API 或 Route Optimization API 的路線權杖，可協助您為規劃路線指定兩項資訊：

• 路線的折線

• 路線目標

以下列舉幾個可能的轉送目標：

• 盡可能縮短送達時間：外送餐點的商家可能希望盡可能縮短送達時間。

• 盡可能縮短行程時間或減少燃料消耗：物流公司可能想提高司機效率，並降低燃料成本。

• 盡可能縮短抵達目的地的時間：服務調度作業可能需要盡可能縮短操作員抵達工作地點的時間。

• 降低成本並提高安全性：多元計程車業務可能需要尋找乘客費用較低的路線，並基於安全考量避開特定區域。

重要事項： 司機行駛的路線可能與你規劃的路線不同。 路況或道路狀況變化、車輛偏離規劃路線，或切換至更快的路線，都可能導致行程中路線變更。每當 Navigation SDK 計算新路線時，都會使用路線權杖中設定的路線選項，例如避開收費路段。

如要進一步瞭解如何使用路線權杖規劃路線，請參閱 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 要求，才能取得新的路線權杖。

路徑權杖的運作方式

您可以使用 Routes API、Routes Preferred API 或 Route Optimization API，根據路線目標規劃路線。您可以將上述任一 API 傳回的路徑權杖傳遞至 Navigation SDK，引導車輛行駛。

要求及使用路徑權杖時，會發生以下情況：

1. Routes API、Routes Preferred API 或 Route Optimization API 會傳回加密路徑權杖，其中包含路徑折線和路徑目標。

2. 將路線權杖傳遞至 Navigation SDK。

3. 即使有更快的路線，Navigation SDK 仍會按照規劃的路線開始導航。

4. 行程期間，如果路況或道路狀況有變，或車輛偏離預定路線，Navigation SDK 會根據路線權杖中設定的路線目標和路線選項，計算新路線。

這個程序可盡量縮短實際路線與規劃路線之間的距離。

為何可能無法完全按照規劃路線行駛

導航會從規劃的路線開始，但實際路線可能會與規劃路線不同，例如：

• 車輛從預定起點以外的位置出發。
• 行程期間路況或道路狀況有變。
• 車輛偏離預定路線。

這些差異可能會影響您規劃的距離、預計到達時間和其他重要行程品質。

提示： 最佳做法是每次在 Navigation SDK 中設定目的地時，一律要求新的路徑權杖，並預留一些變動空間，以免對業務造成任何影響。

使用路線權杖規劃路線

您可以建立路徑權杖，然後傳遞至 Navigation SDK，藉此規劃路徑，步驟如下：

步驟 1：使用 Routes API、Routes Preferred API 或 Route Optimization API 建立路線權杖

1. 使用下列任一方法要求路線權杖：

   • Routes API：computeRoutes。如要進一步瞭解如何在 Routes API 中要求路線權杖，請參閱「計算路線」和「取得路線權杖」。

   • Routes Preferred API：computeCustomRoutes。如要進一步瞭解如何在 Routes Preferred API 中要求路線權杖，請參閱「規劃路線」。

   • Route Optimization API：optimizeTours 或 batchOptimizeTours。如要進一步瞭解如何在 Route Optimization API 中要求路線權杖，請參閱「轉場折線和路線權杖」。

2. 設定 Routes API 或 Routes Preferred API 要求，以符合使用路徑權杖的規定：

   • 將 travelMode 設為 DRIVE 或 TWO_WHEELER。
   • 將 routingPreference 設為 TRAFFIC_AWARE 或 TRAFFIC_AWARE_OPTIMAL。
   • 請勿使用 Via 路線控點。

注意：您可以使用導航點權杖，在路線權杖中指定精確的起點和目的地值，例如入口、裝卸區或指定上車區。

步驟 2：將路線權杖傳遞至 Navigation SDK

1. 儲存路徑權杖：在 Navigation SDK 中，設定用於儲存路徑權杖的字串。例如：

   let routeToken = "route token returned by Routes API"
   

   傳回的路線權杖範例：

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

2. 使用 mapView.navigator 的 setDestinationsWithToken:completionHandler: 方法，將路線權杖傳遞至 Navigation SDK。Navigation SDK 會從路徑權杖取得目的地和路線選項，因此您不需要傳遞路線控點。

   在應用程式中設定的交通方式 (例如 mapView.travelMode) 必須是下列其中一個值：

   • .driving (GMSNavigationTravelModeDriving)：開車。這是預設值，因此大多數應用程式都不需要變更。
   • .twoWheeler (GMSNavigationTravelModeTwoWheeler)：兩輪車。

   如果使用其他交通工具，要求會失敗並傳回 .travelModeUnsupported (GMSRouteStatusTravelModeUnsupported)。無論使用哪一個支援的值，路線都會採用路線權杖中的交通工具。舉例來說，如果應用程式使用開車模式，而路線權杖適用於兩輪車路線，Navigation SDK 就會提供兩輪車路線。如要確認路線使用的交通工具，請查看 resolvedParameters.travelMode。詳情請參閱「已解析的轉送選項」。

   注意：如果應用程式使用的 Navigation SDK 版本低於 11.3，請改用已淘汰的 setDestinations:routeToken:callback: 方法，並傳遞與建立路線權杖時相同的目的地路線控點。

3. 在完成處理常式中檢查路線狀態。Navigation SDK 完成路線計算後，會將 GMSNavigationRouteDescription 傳遞至完成處理常式。如果系統找到從車輛位置到路線權杖中目的地的路線，路線說明的 routeStatus 會是 .OK (GMSRouteStatusOK)，您就可以開始導航。否則，完成處理常式也會收到說明失敗原因的 NSError。例如：

   mapView.navigator?.setDestinationsWithToken(routeToken) { [weak self] routeDescription, error in
     if routeDescription?.routeStatus == .OK {
       self?.mapView.navigator?.isGuidanceActive = true
     }
   }
   

注意：如需再次行經相同路線，請要求新的路線權杖。

檢查 Navigation SDK 是否已套用路徑權杖

如果路徑狀態為 .OK，表示 Navigation SDK 找到路徑，但不一定是您規劃的路徑。如要確認路線是否與規劃路線相符，請在完成處理常式中按照下列步驟操作：

1. 確認路徑說明的 routeStatus 為 .OK。Navigation SDK 只有在找到路線時，才會提供路線權杖詳細資料。詳情請參閱步驟 2。

2. 取得路線說明的 routeTokenExecutionDetails，這是符合 GMSNavigationRouteTokenExecutionDetails 通訊協定的物件。如果伺服器未提供路線權杖詳細資料，這個屬性會是 nil。

3. 查看執行作業詳細資料的 tokenExecutionStatus 屬性。如果為 .tokenSuccessfullyApplied，表示路線與規劃路線相符。如果顯示其他狀態，表示路線可能與規劃路線不同。如要進一步瞭解各項狀態，請參閱「權杖執行狀態值」。

4. 選用：如果狀態為 .tokenSuccessfullyApplied，請查看相同執行詳細資料的 resolvedParameters 屬性，瞭解路線使用的路線選項，例如是否避開收費路段。詳情請參閱「已解析的轉送選項」。

權杖執行狀態值

如果 routeStatus 為 .OK，您可以在任何權杖執行狀態下開始引導。狀態會指出路線是否符合預計路線。

狀態	按照規劃路線行駛	說明
.tokenSuccessfullyApplied	是	Navigation SDK 已套用路線權杖。
.tokenAppliedWithLocationMismatch	不一定	Navigation SDK 無法重建規劃路線，且裝置與路線權杖中的起點距離超過 25 公尺。路線仍會使用路線權杖中的目的地和路線選項。
.tokenIgnoredOther	不一定	Navigation SDK 因其他原因無法重建規劃路線，例如規劃路線上的道路封閉。路線仍會使用路線權杖中的目的地和路線選項。
.noTokenProvided	不適用	路線要求不含路線權杖。
.unknown	不明	狀態不明。

如果路線不一定會遵循規劃路線，且確切路線很重要 (例如用於計算價格)，請記錄狀態，或從車輛目前位置要求新的路線權杖。

已解析的轉送選項

resolvedParameters 是符合 GMSNavigationRouteTokenResolvedParameters 通訊協定的物件，如果沒有可用的路徑選項，則為 nil。這個屬性包含下列選項：

• travelMode：路線使用的交通工具，例如 .driving (GMSNavigationTravelModeDriving)。如果路線使用的交通工具沒有相符的值，或交通工具無法使用，Navigation SDK 也會回報 .driving。
• avoidTolls：路線是否避開收費路段。
• avoidHighways：路線是否避開高速公路。
• avoidFerries：路線是否避開渡輪。
• avoidTunnels：計算路線時，是否盡可能避開隧道。
• avoidVignettes：計算路線時，盡可能避開過路費貼紙的國家/地區，以 Unicode CLDR 雙字母區域代碼表示，例如瑞士為 CH。
• rerouteStrategy：轉送後端在行程期間計算 新路線時採用的策略。策略包括 .bestBasedOnTokenParameters (GMSNavigationRerouteStrategyBestBasedOnTokenParameters)，會使用路線權杖中的路線參數計算新路線。

如果權杖執行狀態不是 .tokenSuccessfullyApplied，Navigation SDK 只會回報 travelMode、avoidTolls、avoidHighways 和 avoidFerries。其他屬性則採用預設值，即使您在要求路線權杖時，要求避開隧道或收費路段：avoidTunnels 為 false (NO)、avoidVignettes 為空白，rerouteStrategy 則為 .unknown (GMSNavigationRerouteStrategyUnknown)。

範例

下列程式碼範例示範如何使用路徑權杖規劃路徑、檢查 Navigation SDK 是否已套用權杖，以及開始導航。

Swift

let routeToken = "route token returned by Routes API"

mapView.navigator?.setDestinationsWithToken(routeToken) { [weak self] routeDescription, error in
  // Check whether the Navigation SDK found a route.
  guard routeDescription?.routeStatus == .OK else {
    print("Route error: \(error?.localizedDescription ?? "unknown")")
    return
  }

  // Check whether the Navigation SDK applied the route token.
  if let executionDetails = routeDescription?.routeTokenExecutionDetails {
    if executionDetails.tokenExecutionStatus != .tokenSuccessfullyApplied {
      print("The route might differ from your planned route.")
    }
  } else {
    print("Route token details aren't available.")
  }

  self?.mapView.navigator?.isGuidanceActive = true
}

Objective-C

NSString *routeToken = @"route token returned by Routes API";

[mapView.navigator setDestinationsWithToken:routeToken
                          completionHandler:^(id<GMSNavigationRouteDescription> _Nullable routeDescription,
                                              NSError *_Nullable error) {
  // Check whether the Navigation SDK found a route.
  if (routeDescription.routeStatus != GMSRouteStatusOK) {
    NSLog(@"Route error: %@", error.localizedDescription);
    return;
  }

  // Check whether the Navigation SDK applied the route token.
  id<GMSNavigationRouteTokenExecutionDetails> executionDetails =
      routeDescription.routeTokenExecutionDetails;
  if (executionDetails == nil) {
    NSLog(@"Route token details aren't available.");
  } else if (executionDetails.tokenExecutionStatus !=
             GMSNavigationRouteTokenExecutionStatusTokenSuccessfullyApplied) {
    NSLog(@"The route might differ from your planned route.");
  }

  mapView.navigator.guidanceActive = YES;
}];

多停靠點情境

最多可設定 25 個路線控點。

Navigation SDK 不會自動前往下一個目的地。車輛抵達路線控點時，請呼叫 continueToNextDestinationWithCompletion:，開始下一段行程。這也適用於具有中繼路線控點的路徑權杖。前往下一個目的地時，Navigation SDK 會繼續沿用路線權杖中的路線，而不是規劃新路線。

注意：呼叫 continueToNextDestinationWithCompletion: 方法有時會導致抵達事件不正確，也就是剛完成的目的地似乎重新選取。

路徑權杖和 Navigation SDK 的互動方式

Navigation SDK 處理規劃路線的方式如下：

• 覆寫先前設定的所有目的地。

• 使用車輛起始位置。

• 根據路況和交通狀況調整。請參閱「為什麼可能無法完全按照規劃路線行駛」。

• 使用路徑權杖中設定的路線選項，而非應用程式中的下列設定，包括在行程中計算新路線時：

  • avoidsHighways
  • avoidsTolls
  • avoidsFerries
  • licensePlateRestriction
  • 應用程式中設定的交通方式

• 計算或調整路線時，遵循下列設定：

  • 路線權杖中的路線目標，例如節能路線或最短路線。如果 Navigation SDK 必須調整路線，會使用您在要求路線權杖時指定的路線目標。
  • 路線權杖中與路線控點相關的選項，例如道路偏好設定。

注意：使用 setDestinationsWithToken:completionHandler: 時，您不必傳遞路線控點，Navigation SDK 會使用路線權杖中的目的地和路線控點選項。如要設定路線控點選項 (例如道路偏好或車輛停靠點)，請在 Routes API 要求的路線控點中使用 sideOfRoad 和 vehicleStopover 欄位。起點一律是裝置的位置，因此您在 Routes API 要求中為起點設定的選項不適用。