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

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

注意：此字段仅供 Driver SDK 和 Consumer 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 沿途的交通状况（如果有）。

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

 更新行程数据。