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)

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

object (LatLng)

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

string

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

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

string (Timestamp format)

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

注意：此字段仅供 Driver SDK 和 Consumer 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

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

get

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

update

 更新行程数据。