隨選行程

本文說明 Fleet Engine 中的隨選行程服務。這篇文章假設您已閱讀「什麼是 Fleet Engine？」，並瞭解所需的特定 Fleet Engine 服務功能。

閱讀本說明文件時，請注意下列事項：

• 您可以將行程指派給車輛，藉此模擬行程與完成該行程的駕駛之間的實際關聯。請參閱車輛簡介，進一步瞭解車輛在車隊引擎中的運作方式。
• 本文件也說明瞭部分僅適用於隨叫行程的車輛元素。
• Fleet Engine 的隨選行程會使用兩個資源：Trip 和 Vehicle。Fleet Engine 提供 gRPC 服務和 REST 介面：
  • TripService：gRPC 和 REST
  • VehicleService：gRPC 和 REST
  • 為簡化操作，本手冊會使用 gRPC 範例。

什麼是隨選行程？

在 Fleet Engine 中，行程代表可達成各種運輸目標的隨選行程，例如：

• People：將一或多位乘客從上車地點載往下車地點。
• 食品和商品：從特定商家地點取到一或多筆餐點訂單，並將這些訂單送到一或多位收件者所在地點。

行程元素

下圖顯示行程的基本元素：指派的車輛 ID、行程狀態和行程路線點。路線點類型會因行程階段而異，包括上車、中途和下車。在任何行程中，中途目的地或路線點都是選用的。在圖片範例中，車輛已抵達上車地點

行程資料模型

當後端將行程指派給車輛時，也必須知道車輛的其他行程。因此，下圖會同時顯示 Trip 資源和相關聯 Vehicle 資源的資料模型。您可以查看這兩張圖表，瞭解這兩項資源之間的關係，但請注意下列事項：

• 行程會根據 ID 指派給車輛。
• 行程與車輛的關聯為多對一。也就是說，特定行程可能是車輛的唯一預約行程，也可能是車輛的多個行程之一。
• 行程物件包含兩個行程路線控點清單，一個用於行程本身，另一個用於指派的車輛。本文件會進一步說明這項功能。
• 隨選車輛也會有行程路線控點清單，請參閱本文瞭解詳情。

行程類型

服務建立行程時，可以將 tripType 欄位設為下列任一值：EXCLUSIVE 或 SHARED。

獨家行程

專屬行程是指行程不會與其他行程重疊，且車輛是在其行程表上的其他行程前或後完成的行程。也就是說，當系統指派專屬行程時，只能將行程指派給一輛車，以便依序完成，而非同時完成。舉例來說，您可以使用下列任一特徵建立專屬行程：

• 行程包含單一上車地點和單一下車地點，且車輛在其行程中沒有其他行程。
• 行程包含上車、中途路線點和下車地點，且車輛沒有其他行程。
• 在已排定的車輛行程結束後，新增上車和下車地點的行程。在這種情況下，每趟行程都會排除其他行程，但行程會以背靠背的方式排序。此外，這類行程也可視需要加入中途目的地。

共乘行程

共乘行程是指行程可能與其他行程預訂重疊的行程。對於這類行程類型，系統可以將行程與交錯目的地同時指派。舉例來說，某趟行程的下車地點可能會發生在另一趟行程的上車地點之後。此外，共乘行程可能不會使用中途路線點。

一般來說，您會在「行程情境」一節所述的共用共乘情境中使用共用行程。

行程路線控點

在 Google 地圖中，路標是沿著路線的某個地點，通常由經緯度座標定義。如為隨選行程，路標會以 TripWaypoint 物件表示，其中包含其他資訊，例如：

• 行程 ID
• WaypointType：上車、中途或下車地點
• 上一個行程路標與目前路標之間的路徑和距離資訊
• 前往行程途經點的路線上的路況
• 行程路線中途點的預估到達時間和預計到達時間

請參閱以下參考資料：

• TripWaypoint：gRPC 或 REST
• WaypointType：gRPC 或 REST

行程路標類型

行程路線點的定義與車輛行程的一般生命週期相關：

• 接送地點路線點：用於行程的起點或開始位置，例如駕駛員接送食物訂單後續送達目的地，或駕駛員接送乘客後續下車的地點。
• 中途點：可用於各種用途的中途目的地，例如司機將同行程組合的乘客其中一位下車後，仍有其他乘客未下車，因此行程並未完成。這個路線點是選用的，且只能用於專屬行程。
• 下車路線控點：用於行程的最終位置，例如乘客下車時。

行程路線控點清單

Trip 實體包含兩個路線控點清單，每個清單都是 TripWaypoint 類型的重複欄位。其中一個清單會說明行程本身所需的欄位，另一個則會說明與行程相關聯的車輛剩餘的所有路線點。這樣一來，您就能全面掌握旅程的所有元素：行程和整個車輛行程。

• 車輛的剩餘路線點：名為 vehicle_waypoints 的欄位。其中包含指派給車輛的所有行程的所有剩餘路線點。
• 行程的剩餘路線點：名為 remaining_waypoints 的欄位。其中包含車輛必須依序前往的路線點，才能抵達行程的最終下車點。請參閱「行程情境」中的情境。
  • 對於指派給車輛的單一目的地行程，且該車輛在其行程表中沒有其他行程，則只會包含上車和下車地點，假設車輛未離開上車路徑點。
  • 在車輛也預約其他行程的任何行程情境中，其行程中任何行程的剩餘路線點會包含其他行程中的所有路線點，這些路線點是車輛必須經過的路線點，才能抵達該行程的下車路線點。舉例來說，在接連行程中，如果車輛正在前往行程 A 下車地點的途中，行程 B 的剩餘路線點就會包含行程 A 的下車路線點。Fleet Engine 會使用 vehicle_waypoints 欄位計算這項資訊。

請參閱 Trip 實體的參考資料：gRPC 或 REST。

行程情境

下圖說明各種支援的旅程情境。在這些情況下，只有共用共乘行程的類型為 SHARED；其他行程的類型為 EXCLUSIVE。圖表也會顯示行程狀態，以及執行行程的車輛剩餘路線點，這些概念會在本指南後續章節中說明。

行程狀態及其生命週期

本節說明行程狀態及其對車輛的影響，以及在指派及管理隨選行程時可能遇到的各種情況。

行程通常會經歷從建立到完成的各種狀態。一般來說，行程可能處於有效或無效狀態。行程狀態會影響 Fleet Engine 的各種用途情境，以及您在行程中識別車輛進度的能力。本文件的其餘部分將討論這些情境。

下表依活動和非活動類型列出行程狀態。

有效行程狀態	行程狀態無效
NEW UNKNOWN_TRIP_STATUS ENROUTE_TO_PICKUP ARRIVED_AT_PICKUP ENROUTE_TO_INTERMEDIATE_DESTINATION ARRIVED_AT_INTERMEDIATE_DESTINATION ENROUTE_TO_DROPOFF	COMPLETE CANCELED

行程狀態和剩餘的車輛路線點

為已執行行程的車輛指派其他行程時，請瞭解車輛的剩餘路線控點之間的關係，以及行程狀態對這些剩餘路線控點的影響。

舉例來說，您可以將新的共乘服務要求指派給只支援專屬行程且正在完成行程的車輛。在這種情況下，您可以將行程設為連續行程。指派這類行程時，系統應確保新行程的路線點會在進行中的行程路線點之後出現。

車輛行駛期間，只有在車輛回報正在前往下一個目的地或已完成行程時，Fleet Engine 才會從車輛的剩餘路線點清單中移除上一個行程的路線點。也就是下列任一項目：

• ENROUTE_TO_INTERMEDIATE_DESTINATION
• ENROUTE_TO_DROPOFF
• 已完成

當行程狀態變更為 COMPLETED 時，車隊引擎會從車輛的剩餘路線點清單中移除行程的最後一個路線點。

相較之下，表示抵達路線上某個點的狀態變更，通常不會影響車輛的剩餘路線上點清單：

• ARRIVED_AT_PICKUP
• ARRIVED_AT_INTERMEDIATE_DESTINATION
• ARRIVED_AT_DROPOFF

以隨選車服務為例：假設駕駛員從住家接送乘客，並將乘客送往某個地點等待乘客完成任務，然後再將乘客送回住家。初始建立時，行程有三個路線點：PICKUP、INTERMEDIATE 和 DROPOFF。下表說明在旅程的不同狀態下，查詢剩餘路線點的結果：

行程狀態	剩餘路線控點
ARRIVED_AT_PICKUP	PICKUP INTERMEDIATE DROPOFF
ENROUTE_TO_INTERMEDIATE_DESTINATION	PICKUP INTERMEDIATE DROPOFF
ARRIVED_AT_INTERMEDIATE_DESTINATION	PICKUP INTERMEDIATE DROPOFF
ENROUTE_TO_DROPOFF	PICKUP INTERMEDIATE DROPOFF
ARRIVED_AT_DROPOFF	PICKUP INTERMEDIATE DROPOFF
COMPLETE	PICKUP INTERMEDIATE DROPOFF

重新指派或取消的行程狀態規定

您必須先將行程狀態設為 NEW 或 CANCELED，才能執行下列任何操作。

• 變更行程的車輛指派。舉例來說，如果駕駛員拒絕某趟行程的車輛指派，而該行程需要重新指派給其他車輛。
• 清除行程的車輛指派。舉例來說，如果司機在行程中取消行程，而你想清除車輛指派，狀態必須為 NEW 或 CANCELED。

根據行程狀態進行搜尋

當您針對特定車輛使用 SearchTrips 服務時，系統會在 SearchTripsResponse 中傳回有效行程清單。Vehicle 實體的 active_trips 欄位也會顯示有效行程。詳情請參閱 SearchTripsResponse 參考資料：gRPC 或 REST。

因此，所有處於有效狀態的行程都會顯示在 active_trips 欄位中，但已完成或已取消的行程則不會顯示。

後續步驟

• 設定 Fleet Engine
• 建立車輛
• 建立隨選旅程