ShipmentRoute

車輛路線可沿著時間軸分解，如下所示 (假設有 n 次造訪)：

  |            |            |          |       |  T[2], |        |      |
  | Transition |  Visit #0  |          |       |  V[2], |        |      |
  |     #0     |    aka     |   T[1]   |  V[1] |  ...   | V[n-1] | T[n] |
  |  aka T[0]  |    V[0]    |          |       | V[n-2],|        |      |
  |            |            |          |       | T[n-1] |        |      |
  ^            ^            ^          ^       ^        ^        ^      ^
vehicle    V[0].start   V[0].end     V[1].   V[1].    V[n].    V[n]. vehicle
 start     (arrival)   (departure)   start   end      start    end     end

請注意，我們會變更以下兩個選項：

  • 「偶發事件」，例如車輛的起點和終點，以及每次造訪的開始和結束 (又稱抵達和離開)。這些事件會在特定秒數發生。
  • 「時間間隔」，例如造訪本身和造訪之間的轉換。雖然時段的持續時間有時為零 (例如從一秒開始和結束)，但效期通常為正值。

不變：

  • 如果有 n 次造訪，就會有 n+1 次轉換。
  • 造訪一律會在轉換之前 (相同索引) 和之後的轉場 (索引 + 1) 周圍環繞。
  • 車輛啟動一律會接著轉換 #0。
  • 車輛端點一律會前面加上轉場效果 #n。

放大，以下是 Transition 和 Visit 期間會發生的情況：

---+-------------------------------------+-----------------------------+-->
   |           TRANSITION[i]             |           VISIT[i]          |
   |                                     |                             |
   |  * TRAVEL: the vehicle moves from   |      PERFORM the visit:     |
   |    VISIT[i-1].departure_location to |                             |
   |    VISIT[i].arrival_location, which |  * Spend some time:         |
   |    takes a given travel duration    |    the "visit duration".    |
   |    and distance                     |                             |
   |                                     |  * Load or unload           |
   |  * BREAKS: the driver may have      |    some quantities from the |
   |    breaks (e.g. lunch break).       |    vehicle: the "demand".   |
   |                                     |                             |
   |  * WAIT: the driver/vehicle does    |                             |
   |    nothing. This can happen for     |                             |
   |    many reasons, for example when   |                             |
   |    the vehicle reaches the next     |                             |
   |    event's destination before the   |                             |
   |    start of its time window         |                             |
   |                                     |                             |
   |  * DELAY: *right before* the next   |                             |
   |    arrival. E.g. the vehicle and/or |                             |
   |    driver spends time unloading.    |                             |
   |                                     |                             |
---+-------------------------------------+-----------------------------+-->
   ^                                     ^                             ^
V[i-1].end                           V[i].start                    V[i].end

最後，我們來看看如何在轉場期間安排 TRAVEL、BREAKS、DELAY 和 WAIT。

  • 不會重疊。
  • 延遲時間是唯一值，且必須在下次造訪 (或車輛結束) 之前，連續一段時間。因此，您可以從中瞭解延遲時間的開始和結束時間。
  • 中斷期間是連續、不重疊的時間。回應會指定每個廣告插播的開始時間和持續時間。
  • 「旅遊」和「等待時間」都是「可先佔」的內容：在轉換期間，可能會多次中斷。用戶端可以假設行程會「盡快」發生，且「等待」會填滿剩餘時間。

以下示例：

                               TRANSITION[i]
--++-----+-----------------------------------------------------------++-->
  ||     |       |           |       |           |         |         ||
  ||  T  |   B   |     T     |       |     B     |         |    D    ||
  ||  r  |   r   |     r     |   W   |     r     |    W    |    e    ||
  ||  a  |   e   |     a     |   a   |     e     |    a    |    l    ||
  ||  v  |   a   |     v     |   i   |     a     |    i    |    a    ||
  ||  e  |   k   |     e     |   t   |     k     |    t    |    y    ||
  ||  l  |       |     l     |       |           |         |         ||
  ||     |       |           |       |           |         |         ||
--++-----------------------------------------------------------------++-->
JSON 表示法 
{
  "vehicleIndex": integer,
  "vehicleLabel": string,
  "vehicleStartTime": string,
  "vehicleEndTime": string,
  "visits": [
    {
      object (Visit)
    }
  ],
  "transitions": [
    {
      object (Transition)
    }
  ],
  "hasTrafficInfeasibilities": boolean,
  "routePolyline": {
    object (EncodedPolyline)
  },
  "breaks": [
    {
      object (Break)
    }
  ],
  "metrics": {
    object (AggregatedMetrics)
  },
  "routeCosts": {
    string: number,
    ...
  },
  "routeTotalCost": number
}
欄位
vehicleIndex

integer

執行路線的車輛，由來源 ShipmentModel 中的索引識別。
vehicleLabel

string

執行此路線的車輛標籤，等同於 ShipmentModel.vehicles(vehicleIndex).label (如有指定)。
vehicleStartTime

string (Timestamp format)

車輛開始行駛的時間。

RFC3339 世界標準時間「Zulu」格式的時間戳記，解析度以奈秒為單位，小數點後最多 9 位。例如 "2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
vehicleEndTime

string (Timestamp format)

車輛完成路線的時間。

RFC3339 世界標準時間「Zulu」格式的時間戳記，精確度達奈秒單位，最多九個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
visits[]

object (Visit)

代表路線的一系列造訪順序。造訪次數 [i] 是路線中的第 i 次造訪。如果這個欄位空白，系統會將車輛視為未使用。
transitions[]

object (Transition)

路線的轉換已排序清單。
hasTrafficInfeasibilities

boolean

如果將 OptimizeToursRequest.consider_road_traffic 設為 true，這個欄位表示路線時間不一致，是根據路況估算的交通時間來預測。在第一個訪客到達前或最後一個訪客離開後，可能沒有足夠的時間完成經過交通調整的移動、延誤和兩次造訪之間的休息時間，同時還要滿足訪客和車輛的時間限制。例如：

  startTime(previous_visit) + duration(previous_visit) +
  travelDuration(previous_visit, next_visit) > startTime(next_visit)

因為路況的關係，預估的交通時間增加 travelDuration(previous_visit, next_visit)，因此抵達 next_visit 的機率可能會晚於目前的時間範圍。此外，由於預估行程時間增加，且訪問或休息時間窗口受到限制，因此休息時間可能會與訪問時間重疊。
routePolyline

object (EncodedPolyline)

路線的編碼折線表示法。只有在 OptimizeToursRequest.populate_polylines 設為 True 時，系統才會填入這個欄位。
breaks[]

object (Break)

為行駛這條路線的車輛安排了休息時間。breaks 序列代表時間間隔，每個時間間隔從對應的 startTime 開始，持續 duration 秒。
metrics

object (AggregatedMetrics)

這個路線的時間長度、距離和載客量指標。系統會根據結構定義，為所有 ShipmentRoute.transitions 或 ShipmentRoute.visits 欄位加總 AggregatedMetrics 的欄位。
routeCosts

map (key: string, value: number)

路線費用，按照費用相關要求欄位細分。鍵是相對於輸入 OptimizeToursRequest 的 proto 路徑，例如「model.shipments.pickups.cost」，而值則是相應費用欄位產生的總費用，並在整個路線上進行匯總。換句話說，成本 ["model.shipments.pickups.cost"] 是路線上所有取貨費用的總和。這裡詳細列出模型中定義的所有費用，但 TransitionAttributes 的相關費用除外。這些費用只以 2022 年 1 月的匯總方式呈現。

這個物件中包含 "key": value 組合的清單，範例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
routeTotalCost

number

路線的總費用。費用對應中所有費用的總和。

前往

在航線中進行造訪。這項拜訪對應至 Shipment 的取貨或送貨。

JSON 表示法 
{
  "shipmentIndex": integer,
  "isPickup": boolean,
  "visitRequestIndex": integer,
  "startTime": string,
  "loadDemands": {
    string: {
      object (Load)
    },
    ...
  },
  "detour": string,
  "shipmentLabel": string,
  "visitLabel": string
}
欄位
shipmentIndex

integer

來源 ShipmentModel 中的 shipments 欄位索引。
isPickup

boolean

如果造訪為 true，則造訪對應至 Shipment 的取貨。否則對應項目會對應提交內容。
visitRequestIndex

integer

Shipment 中「pick up」或「delivery」欄位的 VisitRequest 索引 (請參閱 isPickup)。
startTime

string (Timestamp format)

造訪開始的時間。請注意，車輛可能會在造訪地點之前抵達。時間與 ShipmentModel 一致。

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

map (key: string, value: object (Load))

總訪客負載需求是出貨和訪客要求 loadDemands 的總和。如果造訪是運送，這個值會是負值。系統會針對與 Transition.loads 相同的類型回報要求 (請參見這個欄位)。

這個物件中包含 "key": value 組合的清單，範例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
detour

string (Duration format)

由於在到達目的地前，路線上會經過其他貨件，因此會產生額外的繞路時間，以及因時間窗口而產生的潛在等待時間。如果是送貨行程，系統會從對應的接送行程計算繞路距離，計算方式如下：

startTime(delivery) - startTime(pickup)
- (duration(pickup) + travel duration from the pickup location
to the delivery location).

否則，系統會根據車輛 startLocation 計算該值，並等於：

startTime - vehicleStartTime - travel duration from
the vehicle's `startLocation` to the visit.

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

string

對應的 Shipment.label 副本 (如果在 Shipment 中指定)。
visitLabel

string

對應的 VisitRequest.label 副本 (如果在 VisitRequest 中指定)。

轉移

在路徑上，兩個事件之間的轉換。請參閱 ShipmentRoute 的說明。

如果車輛沒有 startLocation 和/或 endLocation，則相應的旅遊指標為 0。

JSON 表示法 
{
  "travelDuration": string,
  "travelDistanceMeters": number,
  "trafficInfoUnavailable": boolean,
  "delayDuration": string,
  "breakDuration": string,
  "waitDuration": string,
  "totalDuration": string,
  "startTime": string,
  "routePolyline": {
    object (EncodedPolyline)
  },
  "vehicleLoads": {
    string: {
      object (VehicleLoad)
    },
    ...
  }
}
欄位
travelDuration

string (Duration format)

轉換期間的交通時間。

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

number

轉換期間移動的距離。
trafficInfoUnavailable

boolean

當透過 OptimizeToursRequest.consider_road_traffic 要求路況資訊，但無法為 Transition 擷取路況資訊時，這個布林值會設為 true。這可能是暫時性的 (在即時流量伺服器中短暫出現)，或永久 (沒有這個地點的資料)。
delayDuration

string (Duration format)

套用至這個轉換作業的延遲時間長度總和。如有這種情況，延遲時間剛好是發生下一個事件 (造訪或車輛結束) 的 delayDuration 秒前。查看《TransitionAttributes.delay》。

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

string (Duration format)

在這個轉換期間內發生的片段持續時間總和 (如有)。每個廣告插播的開始時間和持續時間詳細資料會儲存在 ShipmentRoute.breaks 中。

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

string (Duration format)

轉換期間的等待時間。等待時間長度對應於閒置時間，不包含休息時間。另請注意，這個等待時間可能會分成幾個不連續的間隔。

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

string (Duration format)

轉場效果的總時間長度 (方便查看)。等於：

  • 下次造訪 startTime (如果是最後一次轉換，則為 vehicleEndTime) - 這個轉換是 startTime
  • 如果 ShipmentRoute.has_traffic_infeasibilities 為 false，則以下會額外保留：`totalDuration = travelDuration +DelayDuration
  • breakDuration + waitDuration`

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

string (Timestamp format)

此轉場效果的開始時間。

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

object (EncodedPolyline)

轉換期間所遵循路線的編碼折線表示法。只有在 populateTransitionPolylines 設為 True 時，系統才會填入這個欄位。
vehicleLoads

map (key: string, value: object (VehicleLoad))

在這個轉換期間載入的車輛，每個類型都會顯示在該車輛的 Vehicle.load_limits 中，或是在這個路線上執行的某些出貨作業中，有非零值的 Shipment.load_demands。

在第一次轉換期間的負載，是車輛路線的起始負載。接著，系統會在每次造訪後，根據造訪是取貨或送貨，增加或減少造訪的 loadDemands，以便載入下一個轉換。

這個物件中包含 "key": value 組合的清單，範例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。

EncodedPolyline

折線的編碼表示法。如要進一步瞭解多邊形編碼，請參閱以下網頁：https://developers.google.com/maps/documentation/utilities/polylinealgorithm https://developers.google.com/maps/documentation/javascript/reference/geometry#encoding。

JSON 表示法 
{
  "points": string
}
欄位
points

string

代表折線已編碼點的字串。

休息時間

代表執行中斷的資料。

JSON 表示法 
{
  "startTime": string,
  "duration": string
}
欄位
startTime

string (Timestamp format)

休息的開始時間。

RFC3339 世界標準時間「Zulu」格式的時間戳記，解析度以奈秒為單位，小數點後最多 9 位。例如 "2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
duration

string (Duration format)

休息時間長度。

時間長度以秒為單位，最多可有 9 個小數位數，並應以「s」結尾，例如："3.5s"。