REST Resource: providers.trips

資源:Trip

行程中繼資料。

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

TripStatusENROUTE_TO_INTERMEDIATE_DESTINATION 時,[0..N-1] 之間的數字表示車輛下一個會經過哪個中途目的地。當 TripStatusARRIVED_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)

這個欄位可讓你手動排序行程的路線控點。這項資訊包含指派車輛的所有剩餘路線點,以及這趟行程的上下車路線點。如果行程尚未指派給車輛,Fleet Engine 會忽略這個欄位。基於隱私權考量,只有在 trips.updatetrips.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 中的時間長度。如果行程未指派給車輛,或是行程處於非活動狀態 (已完成或已取消),則值未指定。

時間長度以秒為單位,最多可有 9 個小數位數,並應以「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_waypointremainingWaypoints.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。如果 lastLocationcurrentRouteSegment 不存在,則為 False。由車隊引擎計算。系統會忽略來自用戶端的任何更新。

view

enum (TripView)

要填入的 Trip 欄位子集,以及如何解讀這些欄位。

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 回應中不同組別的 Trip 欄位選擇器。請參閱 AIP-157 瞭解相關背景資訊。可能會新增其他檢視畫面。

列舉
TRIP_VIEW_UNSPECIFIED 預設值。為了兼顧回溯相容性,API 預設會顯示 SDK 檢視畫面。為確保穩定性和支援服務,建議客戶選取 SDK 以外的 TripView
SDK 包括使用公開可用的程式庫時可能無法解讀或支援的欄位。
JOURNEY_SHARING_V1S 行程欄位會根據旅程分享用途填入資料。這個檢視畫面適用於伺服器對伺服器通訊。

方法

create

在車隊引擎中建立行程,並傳回新行程。

get

取得單趟行程的資訊。
取得特定車輛的所有行程。

update

更新行程資料。