按需行程

本文档介绍了车队引擎中的按需行程服务。本文假定您已阅读什么是车队引擎？，并了解您需要的特定车队引擎服务功能。

阅读本文档时，请注意以下事项：

  • 您可以将行程分配给车辆，以模拟行程与完成该行程的驾驶员之间的真实关联。请参阅车辆简介，更好地了解车辆在车队引擎中的运作方式。
  • 本文档还介绍了仅适用于随叫车行的部分车辆元素。
  • 适用于按需行程的 Fleet Engine 使用两个资源：Trip 和 Vehicle。Fleet Engine 同时提供 gRPC 服务和 REST 接口：
    • TripService：gRPC 和 REST
    • VehicleService：gRPC 和 REST
    • 为简单起见，本手册使用 gRPC 示例。

什么是随叫随到行程？

在 Fleet Engine 中，行程代表可实现各种交通目标的按需行程。例如：

  • 乘客：将一人或多人从上车点运送到下车点。
  • 食品和商品：从指定商家营业地点自提一个或多个食品订单，并将这些订单送到一个或多个收货人所在的地点。

行程元素

下图显示了行程的基本元素：分配的车辆 ID、行程状态和行程航点。路点类型因行程阶段而异：上车点、中途点和下车点。在任何行程中，中途目的地或路点都是可选的。在图片示例中，车辆已到达上车地点

行程的数据模型

当后端向车辆分配行程时，还必须知道为车辆安排的其他行程。因此，以下两个图展示了 Trip 资源的数据模型及其关联的 Vehicle 资源的图表。您可以查看这两个图表，探索这两种资源之间的关系，同时注意以下事项：

  • 行程会按 ID 分配给车辆。
  • 行程与车辆之间的关联是一对多关系。也就是说，给定行程可能是为车辆安排的唯一行程，也可能是车辆的众多行程中之一。
  • 行程对象包含两个行程航点列表，一个用于行程本身，另一个用于分配的车辆。本文档中对此进行了详细说明。
  • 点按式车辆还具有行程路点列表，本文档中对此进行了详细介绍。

行程数据模型

车辆数据模型

行程类型

当您的服务创建行程时，可以将 tripType 字段设置为以下任一值：EXCLUSIVE 或 SHARED。

专属行程

专属行程是指行程不会与其他行程重叠，并且车辆会在其行程安排中的其他行程之前或之后完成的行程。这意味着，当您的系统分配专属行程时，只能将其分配给一辆车依序完成，而不能同时完成。举例来说，您可以创建具有以下任一特征的专属行程：

  • 车辆只有一个上车点和一个下车点，且行程安排中没有其他行程。
  • 包含上车点、中间航点和下车点的行程，且车辆的安排中没有其他行程。
  • 在车辆已安排的行程结束后添加上车点和下车点的行程。在这种情况下，每趟行程都互不相干，但行程的排序是接连的。此外，如果需要，此类行程还可以包含中途目的地。

共享行程

共享行程是指其行程可能会与其他行程预订重叠的行程。对于这些行程类型，系统可以将其分配为与交错目的地同时发生。例如，一项行程的下车点可能会在另一项行程的上车点之后。此外，共享行程不得使用中间航点。

通常，您会将共享行程用于行程场景部分中所述的共享池化场景之一。

行程航点

对于 Google 地图，航点是路线上的地点，通常由纬度/经度坐标定义。对于随叫随到行程，航点由 TripWaypoint 对象表示，该对象包含以下等其他信息：

  • 行程 ID
  • WaypointType，即上车点、中途点或下车点
  • 上一个行程航点与当前航点之间的路径和距离信息
  • 前往行程航点路线上的路况
  • 到行程航点的行程时间和预计到达时间

请参阅以下参考文档：

行程航点类型

行程航点是根据车辆行程的一般生命周期定义的：

  • 上车点路点 - 用于行程的起点或开始部分，例如司机上车接收食品订单以供后续配送，或司机上车接人以供后续下车。
  • 中继航点 - 中继目的地可用于各种用途，例如当司机将同一预订方的一名乘客送下车时，由于仍有其他乘客，因此行程本身尚未结束。此航点为可选项，只能用于专属行程。
  • 下车路点 - 用于行程的最终位置，例如剩余乘客下车时的位置。

行程航点列表

Trip 实体包含两个航点列表，每个列表都是类型为 TripWaypoint 的重复字段。其中一个列表用于描述行程本身所需的字段，另一个列表用于描述与行程关联的车辆剩余的所有路点。这样，您就可以全面了解行程的所有元素：行程和整个车辆行程。

  • 车辆的剩余航点 - 一个名为 vehicle_waypoints 的字段。它包含分配给车辆的所有行程的所有剩余航点。
  • 行程剩余的航点 - 一个名为 remaining_waypoints 的字段。它包含车辆在行程的最终下车点之前必须按顺序经过的路点。请参阅行程场景中的场景。
    • 对于分配给车辆且其行程中没有其他行程的单目的地行程，此属性仅包含上车点和下车点（假设车辆未离开上车点）。
    • 对于车辆还安排了其他行程的任何其他行程场景，其行程中任何行程的剩余路点将包括车辆在到达该行程的下车路点之前必须经过的其他行程的所有路点。例如，在接连的两次行程中，如果车辆正在前往行程 A 的下车点，那么行程 B 的其余路点将包含行程 A 的下车点路点。Fleet Engine 使用 vehicle_waypoints 字段计算此信息。

请参阅 Trip 实体的参考文档：gRPC 或 REST。

行程场景

下图展示了各种受支持的行程场景。在这些情况下，只有共享的拼车行程的类型为 SHARED；所有其他行程的类型均为 EXCLUSIVE。这些图表还会显示执行行程的车辆的行程状态和剩余的路点（本指南稍后会介绍这些概念）。

单目的地行程

单目的地行程是指包含一个上车点和一个下车点的 EXCLUSIVE 行程。例如，司机从一个地点接上乘客并将其送往另一个地点；或者司机从餐厅取回外卖订单并将其送给客户。

多目的地行程

多目的地行程是指在上车点和下车点之间包含一个或多个中途目的地的 EXCLUSIVE 行程。例如，三位乘客通过一人的手机一起预订了行程，但每个人的目的地各不相同。

背靠背行程

背靠背行程是指包含一系列紧接发生的独立行程的EXCLUSIVE行程。该链中的每项行程可以是单目的地或多目的地行程。在这种情况下，驾驶员承诺在完成当前行程之前接载另一位乘客。

这些行程只能分配给允许接连安排行程的车辆。请参阅 Vehicle REST、gRPC 参考文档。

共享拼车行程

共享拼车行程不同于其他行程类型。首先，它必须是 SHARED 行程，而不是 EXCLUSIVE 行程。在这里，车辆会并行执行行程，而不是像专属行程那样按顺序执行。虽然拼车行程会与其他行程分享其行程，但不会在行程之间分享上车点和下车点信息。而是将每趟行程视为单独的预订，这样，预订了某趟行程的最终用户便无法看到除自己行程以外的任何其他行程的接人点或目的地信息。例如：

  • 机场班车服务会在客户的住处接上各种客户，并将他们送到沿途不同的机场航站楼。乘客 2 可以使用您的消费者应用跟踪行程进度，但其应用只会显示其行程的相关部分，而不会显示乘客 1 上车地点或下车地点，即使他们的行程部分重叠也是如此。
  • 一名外卖送餐员从同一家餐厅接收了三份外卖订单，需要将其送往不同的客户住址。使用您的消费者应用，第三人可以查看其食品的取餐地点和时间，以及司机的路线，但无法查看第一人和第二人的食品送达地点。

行程状态及其生命周期

本部分介绍了行程状态及其对车辆的影响，以及您在分配和管理随叫行程时可能会遇到的各种场景。

行程通常会经历从创建到完成的各种状态。一般来说，行程可以是有效或无效的，具体取决于其状态。行程状态会影响 Fleet Engine 的各种使用情形，以及您能够确定车辆在行程中的进度。本文档的其余部分将讨论这些场景。

下表按有效和无效类型列出了行程状态。

有效的行程状态 非活跃行程状态
NEW
UNKNOWN_TRIP_STATUS
ENROUTE_TO_PICKUP
ARRIVED_AT_PICKUP
ENROUTE_TO_INTERMEDIATE_DESTINATION
ARRIVED_AT_INTERMEDIATE_DESTINATION
ENROUTE_TO_DROPOFF 		COMPLETE
CANCELED

行程状态和剩余车辆航点

向正在执行行程的车辆分配其他行程时，您应了解车辆剩余航点之间的关系，以及行程状态对这些剩余航点的影响。

例如，您可以将新的拼车请求分配给一辆仅支持专享行程且正在完成行程的车辆。在这种情况下，您将行程建模为连续行程。分配此类行程时，您的系统应确保新行程的航点出现在正在进行的行程的航点之后。

在车辆行程中，只有在车辆报告正在前往下一个目的地或已完成行程时，车队引擎才会从车辆的剩余航点列表中移除上一行程航点。即以下任一项：

  • ENROUTE_TO_INTERMEDIATE_DESTINATION
  • ENROUTE_TO_DROPOFF
  • 已完成

当行程状态更改为 COMPLETED 时，车队引擎会从车辆的剩余航点列表中移除行程的最后一个航点。

相比之下，表示到达某个航点的状态更改通常不会对车辆的剩余航点列表产生影响：

  • ARRIVED_AT_PICKUP
  • ARRIVED_AT_INTERMEDIATE_DESTINATION
  • ARRIVED_AT_DROPOFF

下面以按需车辆服务为例进行说明：假设司机从客户的住所接上客户，将其送往某个场所，在那里等待客户完成任务，然后将客户送回住所。初始创建时，行程有三个航点：PICKUP、INTERMEDIATE 和 DROPOFF。下表展示了在行程的不同状态下查询剩余航点的结果：

行程状态 剩余航点
ARRIVED_AT_PICKUP PICKUP
INTERMEDIATE
DROPOFF
ENROUTE_TO_INTERMEDIATE_DESTINATION PICKUP
INTERMEDIATE
DROPOFF
ARRIVED_AT_INTERMEDIATE_DESTINATION PICKUP
INTERMEDIATE
DROPOFF
ENROUTE_TO_DROPOFF PICKUP
INTERMEDIATE
DROPOFF
ARRIVED_AT_DROPOFF PICKUP
INTERMEDIATE
DROPOFF
COMPLETE PICKUP
INTERMEDIATE
DROPOFF

重新分配或取消的行程的状态要求

您必须先将行程状态设为 NEW 或 CANCELED，然后才能执行以下任一操作。

  • 更改行程的车辆分配时。例如，如果司机拒绝了行程的车辆分配，并且需要将其重新分配给其他车辆。
  • 清除行程的车辆分配。例如，如果司机在行程中取消了行程，而您想清除车辆分配，则状态必须为 NEW 或 CANCELED。

根据行程状态显示的搜索结果

当您针对特定车辆使用 SearchTrips 服务时，该服务会在 SearchTripsResponse 中返回有效行程的列表。有效行程也会显示在 Vehicle 实体的 active_trips 字段中。如需了解详情，请参阅 SearchTripsResponse 参考文档：gRPC 或 REST。

因此，所有处于有效状态的行程都会显示在 active_trips 字段中，但已完成或已取消的行程不会显示。

后续步骤