隨選行程

本文件說明 Fleet Engine 中的隨選行程服務。本文假設您已閱讀什麼是 Fleet Engine？一文，且瞭解您需要的特定 Fleet Engine 服務功能。

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

• 您可以為車輛指派行程，模擬行程與完成該行程的駕駛之間的實際關聯。請參閱「車輛簡介」，進一步瞭解車輛在 Fleet Engine 中的運作方式。
• 本文件也說明部分僅適用於隨選行程的車輛元素。
• 隨選行程適用的 Fleet Engine 使用兩項資源：Trip 和 Vehicle。Fleet Engine 同時提供 gRPC 服務和 REST 介面：
  • TripService：gRPC 和 REST
  • VehicleService：gRPC 和 REST
  • 為求簡單起見，本手冊使用 gRPC 範例。

什麼是隨選行程？

在 Fleet Engine 中，行程代表隨需規劃的行程，可完成各種交通運輸目標。例如：

• 乘客：將一或多人從上車地點運送至下車地點。
• 食物與商品：取材自特定商家所在地點的一或多筆餐點訂單，將訂購商品分送給一或多位收件者前往該地。

行程元素

下圖顯示行程的基本元素：指派的車輛 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 時，Fleet Engine 會從車輛其餘的路線控點清單中，移除行程的最終路線控點。

相反地，指示抵達路線控點的狀態變更通常不會影響車輛的其餘路線控點清單：

• 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
• 建立車輛
• 建立隨選歷程