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

僅供輸出。格式為「provider/{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 世界標準時間「Zulu」的時間戳記格式，解析度為奈秒，且最多 9 個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
intermediateDestinations[]

object (TerminalLocation)

中途停靠站，以按照行程要求行程 (除了上車和下車)。目前這項功能不適用於已分享的行程。
intermediateDestinationsVersion

string (Timestamp format)

表示上次修改 intermediateDestinations 的時間。您的伺服器應快取這個值，並在更新 intermediateDestinationIndex 時傳入 UpdateTripRequest，確保 intermediateDestinations 不會遭到變更。

RFC3339 世界標準時間「Zulu」的時間戳記格式，解析度為奈秒，且最多 9 個小數位數。範例："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 世界標準時間「Zulu」的時間戳記格式，解析度為奈秒，且最多 9 個小數位數。範例："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)

僅供輸出。這趟行程前往剩餘 Waypoints 中第一個入口的路線。請注意，第一個路線控點可能屬於不同的行程。
currentRouteSegment

string

僅供輸出。前往下一個路線控點的編碼路徑。

注意：這個欄位僅供驅動程式 SDK 和 Consumer SDK 使用。目前不支援解碼。
currentRouteSegmentVersion

string (Timestamp format)

僅供輸出。指出上次修改路線的時間。

注意：這個欄位僅供驅動程式 SDK 和 Consumer SDK 使用。

RFC3339 世界標準時間「Zulu」的時間戳記格式，解析度為奈秒，且最多 9 個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
currentRouteSegmentTraffic

object (ConsumableTrafficPolyline)

僅供輸出。指出 currentRouteSegment 沿途的路況 (如有)。

注意：這個欄位僅供驅動程式 SDK 和 Consumer SDK 使用。
currentRouteSegmentTrafficVersion

string (Timestamp format)

僅供輸出。表示上次修改 currentRouteSegmentTraffic 的時間。

注意：這個欄位僅供驅動程式 SDK 和 Consumer SDK 使用。

RFC3339 世界標準時間「Zulu」的時間戳記格式，解析度為奈秒，且最多 9 個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
currentRouteSegmentEndPoint

object (TripWaypoint)

僅供輸出。currentRouteSegment 結束的路線點。
remainingDistanceMeters

integer

僅供輸出。currentRouteSegment 欄位剩餘的行車距離。如果行程未指派給車輛，或是行程完成或取消，則未指定這個值。
etaToFirstWaypoint

string (Timestamp format)

僅供輸出。到下一個路線控點的預計到達時間 (remainingWaypoints 欄位中的第一個項目)。如果行程未指派給車輛，或是行程無效 (已完成或取消)，則未指定這個值。

RFC3339 世界標準時間「Zulu」的時間戳記格式，解析度為奈秒，且最多 9 個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
remainingTimeToFirstWaypoint

string (Duration format)

僅供輸出。從行程資料傳回 Trip.eta_to_first_waypoint 時間的期間。如果行程未指派給車輛，或是行程無效 (已完成或取消)，則未指定這個值。

持續時間以秒為單位，最多 9 個小數位數，結尾為「s」。範例："3.5s"。
remainingWaypointsVersion

string (Timestamp format)

僅供輸出。表示上次變更 remainingWaypoints 的時間 (新增、移除或變更路線控點)。

RFC3339 世界標準時間「Zulu」的時間戳記格式，解析度為奈秒，且最多 9 個小數位數。範例："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 世界標準時間「Zulu」的時間戳記格式，解析度為奈秒，且最多 9 個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
numberOfPassengers

integer

不可變動。用於表示這趟行程的乘客人數，不包括司機。車輛必須有可用容量，才能在 vehicles.search 回應中傳回。
lastLocation

object (VehicleLocation)

僅供輸出。用於指出沿途車輛上次回報的位置。
lastLocationSnappable

boolean

僅供輸出。用於指出車輛的 lastLocation 是否可媒合至目前 RouteSegment。如果 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 世界標準時間「Zulu」的時間戳記格式，解析度為奈秒，且最多 9 個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
stopTime
(deprecated)

string (Timestamp format)

僅限輸入。已淘汰，使用時間戳記欄位。

RFC3339 世界標準時間「Zulu」的時間戳記格式，解析度為奈秒，且最多 9 個小數位數。範例："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

 更新行程資料。