REST Resource: providers.trips

资源：行程

行程元数据。

JSON 表示法 
{
  "name": string,
  "vehicleId": string,
  "tripStatus": enum (TripStatus),
  "tripType": enum (TripType),
  "pickupPoint": {
    object (TerminalLocation)
  },
  "actualPickupPoint": {
    object (StopLocation)
  },
  "actualPickupArrivalPoint": {
    object (StopLocation)
  },
  "pickupTime": string,
  "intermediateDestinations": [
    {
      object (TerminalLocation)
    }
  ],
  "intermediateDestinationsVersion": string,
  "intermediateDestinationIndex": integer,
  "actualIntermediateDestinationArrivalPoints": [
    {
      object (StopLocation)
    }
  ],
  "actualIntermediateDestinations": [
    {
      object (StopLocation)
    }
  ],
  "dropoffPoint": {
    object (TerminalLocation)
  },
  "actualDropoffPoint": {
    object (StopLocation)
  },
  "dropoffTime": string,
  "remainingWaypoints": [
    {
      object (TripWaypoint)
    }
  ],
  "vehicleWaypoints": [
    {
      object (TripWaypoint)
    }
  ],
  "route": [
    {
      object (LatLng)
    }
  ],
  "currentRouteSegment": string,
  "currentRouteSegmentVersion": string,
  "currentRouteSegmentTraffic": {
    object (ConsumableTrafficPolyline)
  },
  "currentRouteSegmentTrafficVersion": string,
  "currentRouteSegmentEndPoint": {
    object (TripWaypoint)
  },
  "remainingDistanceMeters": integer,
  "etaToFirstWaypoint": string,
  "remainingTimeToFirstWaypoint": string,
  "remainingWaypointsVersion": string,
  "remainingWaypointsRouteVersion": string,
  "numberOfPassengers": integer,
  "lastLocation": {
    object (VehicleLocation)
  },
  "lastLocationSnappable": boolean,
  "view": enum (TripView)
}
字段
name

string

仅限输出。格式为“providers/{provider}/trips/{trip}”
vehicleId

string

进行此行程的车辆的 ID。
tripStatus

enum (TripStatus)

行程的当前状态。
tripType

enum (TripType)

行程的类型。
pickupPoint

object (TerminalLocation)

客户指明的取件地点。
actualPickupPoint

object (StopLocation)

仅限输入。客户上车的实际位置和时间。此字段供提供商提供有关实际上门取件信息的反馈。
actualPickupArrivalPoint

object (StopLocation)

仅限输入。司机到达上车点的实际时间和位置。此字段供提供商提供有关上车点实际到达信息的反馈。
pickupTime

string (Timestamp format)

仅限输出。乘客上车的预计未来时间，或上车的实际时间。

使用 RFC 3339，其中生成的输出将始终采用 Z 归一化，并使用 0、3、6 或 9 个小数位。也接受除“Z”以外的偏移量。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
intermediateDestinations[]

object (TerminalLocation)

除了上车点和下车点之外，行程请求的中途停靠点。此功能最初不支持拼车。
intermediateDestinationsVersion

string (Timestamp format)

表示上次修改 intermediateDestinations 的时间。您的服务器应缓存此值，并在更新 intermediateDestinationIndex 时通过 UpdateTripRequest 传递该值，以确保 intermediateDestinations 不会发生更改。

使用 RFC 3339，其中生成的输出将始终采用 Z 归一化，并使用 0、3、6 或 9 个小数位。也接受除“Z”以外的偏移量。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
intermediateDestinationIndex

integer

当 TripStatus 为 ENROUTE_TO_INTERMEDIATE_DESTINATION 时，表示车辆下一个要经过的中间目的地，介于 [0..N-1] 之间的数字。当 TripStatus 为 ARRIVED_AT_INTERMEDIATE_DESTINATION 时，表示车辆位于哪个中间目的地，介于 [0..N-1] 之间的数字。提供程序会设置此值。如果没有 intermediateDestinations，则系统会忽略此字段。
actualIntermediateDestinationArrivalPoints[]

object (StopLocation)

仅限输入。司机到达中途目的地的实际时间和位置。此字段供提供商提供有关中途目的地的实际到达信息的反馈。
actualIntermediateDestinations[]

object (StopLocation)

仅限输入。从中途目的地接上客户的实际时间和地点。此字段供提供商提供有关中途目的地的实际上车信息的反馈。
dropoffPoint

object (TerminalLocation)

客户指明的下车地点。
actualDropoffPoint

object (StopLocation)

仅限输入。客户下车的实际时间和地点。此字段供提供商提供有关实际下车信息的反馈。
dropoffTime

string (Timestamp format)

仅限输出。乘客在最终目的地下车的预计未来时间，或实际下车时间。

使用 RFC 3339，其中生成的输出将始终采用 Z 归一化，并使用 0、3、6 或 9 个小数位。也接受除“Z”以外的偏移量。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
remainingWaypoints[]

object (TripWaypoint)

仅限输出。从当前位置到下车点的完整路径（包括这两个点）。此路线可能包含其他行程中的航点。
vehicleWaypoints[]

object (TripWaypoint)

此字段支持手动对行程的航点进行排序。它包含分配给指定车辆的所有剩余航点，以及此行程的上车点和下车点航点。如果行程未分配给车辆，车队引擎会忽略此字段。出于隐私保护原因，服务器仅在 trips.update 和 trips.create 调用（而非 trips.get 调用）时填充此字段。
route[]

object (LatLng)

仅限输出。此行程到 remainingWaypoints 中第一个条目的预计路线。请注意，第一个航点可能属于其他行程。
currentRouteSegment

string

仅限输出。指向下一个航点的编码路径。

注意：此字段仅供 Driver SDK 和 Consumer SDK 使用。尚不支持解码。
currentRouteSegmentVersion

string (Timestamp format)

仅限输出。表示路线的上次修改时间。

注意：此字段仅供 Driver SDK 和 Consumer SDK 使用。

使用 RFC 3339，其中生成的输出将始终采用 Z 归一化，并使用 0、3、6 或 9 个小数位。也接受除“Z”以外的偏移量。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
currentRouteSegmentTraffic

object (ConsumableTrafficPolyline)

仅限输出。指示 currentRouteSegment 沿途的交通状况（如果有）。

注意：此字段仅供 Driver SDK 和 Consumer SDK 使用。
currentRouteSegmentTrafficVersion

string (Timestamp format)

仅限输出。表示上次修改 currentRouteSegmentTraffic 的时间。

注意：此字段仅供 Driver SDK 和 Consumer SDK 使用。

使用 RFC 3339，其中生成的输出将始终采用 Z 归一化，并使用 0、3、6 或 9 个小数位。也接受除“Z”以外的偏移量。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
currentRouteSegmentEndPoint

object (TripWaypoint)

仅限输出。currentRouteSegment 结束的航点。
remainingDistanceMeters

integer

仅限输出。currentRouteSegment 字段中的剩余行驶距离。如果行程未分配给车辆，或者行程已完成或取消，则此值为未指定。
etaToFirstWaypoint

string (Timestamp format)

仅限输出。到下一个航路点的预计到达时间（remainingWaypoints 字段中的第一个条目）。如果行程未分配给车辆，或者行程处于非活动状态（已完成或已取消），则此值为未指定。

使用 RFC 3339，其中生成的输出将始终采用 Z 归一化，并使用 0、3、6 或 9 个小数位。也接受除“Z”以外的偏移量。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
remainingTimeToFirstWaypoint

string (Duration format)

仅限输出。从返回行程数据到 Trip.eta_to_first_waypoint 中的时间的间隔。如果行程未分配给车辆，或者行程处于非活动状态（已完成或已取消），则此值为未指定。

该时长以秒为单位，最多包含九个小数位，以“s”结尾。示例："3.5s"。
remainingWaypointsVersion

string (Timestamp format)

仅限输出。表示上次更改 remainingWaypoints 的时间（添加、移除或更改了航点）。

使用 RFC 3339，其中生成的输出将始终采用 Z 归一化，并使用 0、3、6 或 9 个小数位。也接受除“Z”以外的偏移量。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
remainingWaypointsRouteVersion

string (Timestamp format)

仅限输出。表示上次修改 remainingWaypoints.path_to_waypoint 和 remainingWaypoints.traffic_to_waypoint 的时间。您的客户端应用应缓存此值并在 GetTripRequest 中传递该值，以确保仅在更新时返回 remainingWaypoints 的路径和流量。

使用 RFC 3339，其中生成的输出将始终采用 Z 归一化，并使用 0、3、6 或 9 个小数位。也接受除“Z”以外的偏移量。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
numberOfPassengers

integer

不可变。表示此行程的乘客人数（不包括司机）。车辆必须有可用的载客量，才能在 vehicles.search 响应中返回。
lastLocation

object (VehicleLocation)

仅限输出。表示车辆在路线上上次报告的位置。
lastLocationSnappable

boolean

仅限输出。指示车辆的 lastLocation 是否可以贴靠到 currentRouteSegment。如果 lastLocation 或 currentRouteSegment 不存在，则为 false。该指标由车队引擎计算得出。系统会忽略来自客户端的任何更新。
view

enum (TripView)

要填充的部分行程字段及其解读方式。

TripStatus

行程状态，表示行程的进度。

枚举
UNKNOWN_TRIP_STATUS 默认，用于未指定或无法识别的行程状态。
NEW 新创建的行程。
ENROUTE_TO_PICKUP 司机正在前往上车点。
ARRIVED_AT_PICKUP 司机已到达上车点。
ARRIVED_AT_INTERMEDIATE_DESTINATION 司机已到达中途目的地，正在等待乘客。
ENROUTE_TO_INTERMEDIATE_DESTINATION 司机正在前往中途目的地（而非下车点）。
ENROUTE_TO_DROPOFF 司机已接上乘客，正在前往下一个目的地。
COMPLETE 乘客已下车，行程已结束。
CANCELED 在司机、乘客或拼车服务提供商上门接人之前，行程已被取消。

StopLocation

相应经停点（上车点/下车点）的实际位置。

JSON 表示法 
{
  "point": {
    object (LatLng)
  },
  "timestamp": string,
  "stopTime": string
}
字段
point

object (LatLng)

必需。表示实际位置。
timestamp

string (Timestamp format)

表示停止发生的时间。

使用 RFC 3339，其中生成的输出将始终采用 Z 归一化，并使用 0、3、6 或 9 个小数位。也接受除“Z”以外的偏移量。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
stopTime
(deprecated)

string (Timestamp format)

仅限输入。已弃用。使用时间戳字段。

使用 RFC 3339，其中生成的输出将始终采用 Z 归一化，并使用 0、3、6 或 9 个小数位。也接受除“Z”以外的偏移量。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

TripView

用于选择 trips.get 响应中不同组行程字段的选择器。如需了解背景信息，请参阅 AIP-157。我们可能会添加其他视图。

枚举
TRIP_VIEW_UNSPECIFIED 默认值。为了实现向后兼容性，该 API 将默认采用 SDK 视图。为确保稳定性和支持，建议客户选择 SDK 以外的 TripView。
SDK 包括可能无法使用公开可用的库解读或支持的字段。
JOURNEY_SHARING_V1S 为“行程分享”用例填充了行程字段。此视图适用于服务器到服务器通信。

方法

create

 在车队引擎中创建行程，并返回新行程。

get

 获取单次行程的相关信息。
获取特定车辆的所有行程。

update

 更新行程数据。