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)

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

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
intermediateDestinations[]

object (TerminalLocation)

按照行程请求的中间经停点（除上车点和下车点外）。最初，共享行程将不支持此功能。
intermediateDestinationsVersion

string (Timestamp format)

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

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
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)

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

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
remainingWaypoints[]

object (TripWaypoint)

仅限输出。从当前位置到下车点的完整路径（含边界值）。此路径可包含其他行程的航点。
vehicleWaypoints[]

object (TripWaypoint)

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

object (LatLng)

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

string

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

注意：此字段仅供驱动程序 SDK 和消费者 SDK 使用。尚不支持解码。
currentRouteSegmentVersion

string (Timestamp format)

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

注意：此字段仅供驱动程序 SDK 和消费者 SDK 使用。

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
currentRouteSegmentTraffic

object (ConsumableTrafficPolyline)

仅限输出。表示 currentRouteSegment 沿途的路况信息（如果可用）。

注意：此字段仅供驱动程序 SDK 和消费者 SDK 使用。
currentRouteSegmentTrafficVersion

string (Timestamp format)

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

注意：此字段仅供驱动程序 SDK 和消费者 SDK 使用。

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
currentRouteSegmentEndPoint

object (TripWaypoint)

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

integer

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

string (Timestamp format)

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

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
remainingTimeToFirstWaypoint

string (Duration format)

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

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

string (Timestamp format)

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

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
remainingWaypointsRouteVersion

string (Timestamp format)

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

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
numberOfPassengers

integer

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

object (VehicleLocation)

仅限输出。表示沿途车辆最后报告的位置。
lastLocationSnappable

boolean

仅限输出。指示能否将车辆的 lastLocation 贴靠到 currentRouteSegment。如果 lastLocation 或 currentRouteSegment 不存在，则返回 false。它由 Fleet Engine 计算。来自客户端的任何更新都将被忽略。
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)

指示停止的时间。

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
stopTime
(deprecated)

string (Timestamp format)

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

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。

TripView

trips.get 响应中不同“行程”字段集的选择器。如需了解背景信息，请参阅 AIP-157。并且还可能会添加其他数据视图。

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

方法

create

 在 Fleet Engine 中创建行程并返回新行程。

get

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

update

 更新行程数据。