隨選行程

本文件說明 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。

注意： 您定義的行程類型只能指派給支援該行程類型的車輛。舉例來說，您只能將 SHARED 行程指派給車輛，並將 supported_trip_types 設為 SHARED。請參閱車輛服務 gRPC 或 Rest 的參考資料。

專屬行程

專屬行程是指旅程不會與其他行程重疊，且車輛在行程其他行程之前或之後完成的行程。這表示當系統指派專屬行程時，只能將其指派給連續完成的車輛，而無法並行完成。舉例來說，您可以使用下列任一特性建立專屬行程：

• 如果行程只有單一上車地點和單次下車地點，且時間表內沒有其他行程，
• 包含上車、中繼路線控點和下車地點的車輛，且時間表上沒有其他行程。
• 在已預定行程的行程結束時，新增上車和下車地點的行程。在這種情況下，每趟行程都不會視為另一個行程，但行程的排序方式是反向排序。此外，這類行程也可以視需要包含中繼目的地。

注意： 只有專屬行程可能會有中途目的地或路線控點。 詳情請參閱「行程路線控點類型」。

已分享的行程

所分享的行程是指能與其他行程重疊的行程。針對這些行程類型，您的系統可與交互目的地並行指派。例如，某個行程的下車可能會發生在另一趟行程的上車地點之後。此外，共用的行程不得使用中繼路線控點。

一般而言，您會對其中一個共用集區情境使用共用行程，如「行程情境」一節所示。

行程路線控點

在 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。這些圖表也會顯示行程狀態，以及車輛行駛的其餘路線點，本指南稍後說明的概念。

單程行程

單一目的地行程為 EXCLUSIVE 行程，只有一個上車和一個下車地點。例如駕駛人從某個地點領取乘客，再轉至另一個地點；或駕駛人從餐廳擷取餐點外送訂單再送到客戶手中。

多目的地行程

多目的地行程是一種 EXCLUSIVE 行程，包含上車和下車地點之間的一或多個中繼目的地。舉例來說，有三位代僱駕駛服務客戶透過一位使用者的手機一起預訂行程，但各自的目的地各不相同。

返回行程

返回行程屬於 EXCLUSIVE 趟行程，包含一連串的一系列獨立行程。鏈結中的每趟行程都可以是單個或多個目的地。在這個情境中，駕駛人承諾在完成目前的行程之前接手第一位客戶。

這些行程只能指派給支援反向排程的車輛。請參閱 Vehicle REST 和 gRPC 參考資料。

共用游泳池行程

共用泳池行程與其他行程類型不同。首先，這必須是 SHARED 行程，而不是 EXCLUSIVE 行程。在這裡，車輛會以並行方式執行行程，而不是像專屬行程依序執行。共用的泳池行程會與其他行程分享行程，但不會在行程之間分享上車和下車地點資訊。每個行程都是專屬預訂，因此預訂任一行程的使用者無法看到任何其他行程的上車或目的地資訊。例如：

• 機場接駁服務會接待每一位客戶居住地，並將他們帶往沿途不同的機場航廈。第 2 人可能會使用您的消費者應用程式追蹤行程進度，但應用程式只會顯示行程的一部分，不會顯示第 1 人的上車地點，或是第 1 人的下車地點，即使部分旅程有所重疊。
  
• 某家餐點外送司機從同一家餐廳收取三筆餐點訂單，分別運送至不同的客戶居住地。使用消費者應用程式，個人 3 可以查看車輛的上車地點和時間，並查看司機的路線，但無法查看 1 和 2 人的下車地點。
  

行程狀態及其生命週期

本節說明行程狀態及其對車輛和您在指派及管理隨選行程時遇到的各種情境有何影響。

行程通常會經歷多個狀態，從建立到完成。廣義來說，視狀態而定，行程可能是有效或無效。 行程狀態會影響 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

注意： 如需狀態定義，請參閱 gRPC 或 REST 參考資料。

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

將其他行程指派給已經在進行行程的車輛時，您應瞭解車輛其餘路線控點之間的關係，以及行程狀態對剩餘路線控點的影響。

舉例來說，您可以將新的共乘要求指派給只有支援專屬行程的車輛，且正在行程中。在此情況下，您可以將行程建模為返回的行程。指派這類行程時，系統應確保新行程的路線控點是在持續行程的路線控點之後發生。

在車輛旅程中，只有在車輛回報路線前往下一個目的地或完成時，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
• 建立車輛
• 建立隨選歷程