规划路线

有时，您可能想要规划应用提供给驾驶员的路线。使用 Routes API（或 Routes Preferred API）中的路线令牌有助于您为规划的路线指定以下两项内容：

• 路线的多段线

• 您的路线目标

例如，下面是一些您可能有的“路线安排”目标示例：

• 最大限度地缩短送餐时间：送餐商家可能希望最大限度地缩短送餐时间。

• 最大限度地减少行程时间或燃料消耗：物流企业可能希望提高司机效率并降低燃料成本。

• 最大限度地缩短到达目的地所需的时间：服务调度操作可能希望最大限度地缩短让操作人员收到作业请求的时间。

• 降低成本并提高安全性：拼车业务可能希望寻找票价更低的路线，并出于安全考虑避开某些区域。

重要提示 ：经过的实际路线可能与令牌提供的计划路线有所不同。交通状况、路况变化或车辆偏离指定路线都可能会导致路线变更。发生变更时，Navigation SDK 会不断尝试返回到规划的路线；如果返回不切实际，则会遵循路线令牌中的路线目标。

如需详细了解如何使用路线令牌规划路线，请参阅请求路线令牌。

为什么要为路线目标使用路线令牌

借助 Routes 或 Routes Preferred API 中的路线令牌，您可以更好地控制所提供的路线：

• 提前规划路线，以便 Navigation SDK 尽可能使用。

• 选择供 Navigation SDK 使用的最佳路线。如果您在 Routes API 中生成路由时请求路由令牌，则生成的每个路线都会获得一个路由令牌。然后，您可以为想要在将路线传递给 Navigation SDK 时使用的路线选择令牌。

• 提前估算价格，包括估算预计到达时间和距离。 虽然实际费用和时间可能会有所不同，但此估算可以缩小预期路线费用与实际路线费用之间的差距。

• 指定更高级的路由目标，例如节能路由或最短路由。

提示： 路线令牌适用于一个特定出发地和目的地，且在某个特定时间。您必须发出新的 Routes API 请求，以获取新的路线令牌。

Routes API 路由令牌的工作原理

您可以使用 Routes API 或 Routes Preferred API，通过路线目标规划路线。Routes API 会返回一个路线令牌，您可以将该令牌传递给 Navigation SDK，以指导它如何为您的车辆行驶路线。

通过 Routes API 请求和使用路线令牌时，会发生以下情况：

1. Routes API 会返回包含路线多段线和路线目标的加密路线令牌。

2. 您将路线令牌传递给 Navigation SDK。

3. Navigation SDK 会检索路线，或者如果路线因条件变化而不可用，它会检索最佳匹配路线。

4. 在驾车时，如果路况或其他路况发生变化，或者车辆偏离计划的路线，则修改后的路线将根据令牌中的路线目标不断尝试匹配最佳路线。

此过程可以最大限度地增加实际路线与计划路线的距离。

为什么规划的路线没有严格执行

您可以将规划的路线和路线目标视为要遵循的准则：它们不是规范性的。由于路况、出发地点或其他参数在您创建规划路线后发生了变化，因此您可能会注意到规划的路线与引导式导航提供的路线有所不同。这种差异可能会导致距离和预计到达时间以及其他重要的行程质量方面的计划目标与实际目标不一致。

提示 ：最佳实践是，每次在 Navigation SDK 中设置目的地时都要请求新的路线令牌，并规划一些变体以避免对您的业务产生任何影响。

使用路线令牌规划路线

若要规划路线，您可以创建一个路线令牌，然后将其传递给 Navigation SDK，具体如以下步骤所述：

第 1 步：使用 Routes 或 Routes Preferred API 创建路线令牌

1. 使用以下方法之一请求路由令牌：

   • Routes API：computeRoutes。如需详细了解如何在 Routes API 中请求路线令牌，请参阅计算路线和请求路线令牌。

   • Routes Preferred API：computeCustomRoutes。如需详细了解如何在 Routes Preferred API 中请求路线令牌，请参阅规划路线。

2. 设置您的路由请求，以满足使用路由令牌的要求：

   • 将 travel_mode 设置为 DRIVING
   • 将 routing_preference 设置为 TRAFFIC_AWARE 或 TRAFFIC_AWARE_OPTIMAL
   • 请勿使用 Via 航点

第 2 步：将路线令牌传递给 Navigation SDK

1. 存储路线令牌：在 Navigation SDK 中，设置一个字符串来存储路线令牌。例如：

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

   返回路由令牌的示例：

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

2. 使用 Navigator.setDestinations 方法将路线令牌传递给 Navigation SDK，指定您在创建路线令牌时使用的相同目的地航点：

   setDestinations(List destinations, CustomRoutesOptions customRoutesOptions, DisplayOptions displayOptions);

   例如：

   CustomRoutesOptions customRoutesOptions =
         CustomRoutesOptions.builder()
         .setRouteToken(routeToken)
         .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(CustomRoutesOptions.TravelMode.TWO_WHEELER)
          .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 生成的路线与路线令牌中的计划路线之间的交互方式：

• 替换之前设置的所有目的地。

• 使用车辆的出发位置。

• 根据路况和路况调整。请参阅为什么规划的路线可能没有准确遵循。

• 忽略以下不需要的路由相关选项：

  • avoidsHighways
  • avoidsTolls
  • avoidsFerries
  • licensePlateRestriction

• 关注：

  • 与航点相关的选项，例如路边偏好设置。

  • 路线目标。如果 Navigation SDK 必须调整返回的路线，它会使用您在请求路线令牌时指定的路线目标。因此，您应使用在 Routes API 中指定的那些与航点相关的选项。