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

最後，以下是轉換期間的旅遊、BREAK、延遲和 WAIT 方法。

  • 不會重疊。
  • 延遲是唯一的，而且必須是下次造訪 (或車輛結束) 前的連續時段。如此一來，您就能得知延遲時間的延遲時間和結束時間。
  • BREAKS 是連續且不重疊的時段。回應會指定每個廣告插播的開始時間和持續時間。
  • 旅遊和 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」格式的時間戳記，採用奈秒解析度和最多九個小數位數。範例："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] 是指路線中的第 1 次造訪。如果這個欄位空白，系統會將車輛視為未使用。
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)

這條路線的行車時間、距離和負載指標。視情境而定，AggregatedMetrics 的欄位會在所有 ShipmentRoute.transitions 或 ShipmentRoute.visits 上進行加總。
routeCosts

map (key: string, value: number)

路線費用，按照費用相關要求欄位細分。索引鍵是相對於輸入最佳化工具 ToursRequest 的 proto 路徑 (例如「model.shipments.pickups.cost」)，值則是對應費用欄位產生的總費用，並經過整條路線匯總。換句話說，cost["model.shipments.pickups.cost"] 是航線的所有上車費用總和。這裡會列出模型定義的所有費用，但截至 2022 年 1 月為止，僅以匯總方式回報 TransitionAttributes 相關費用的情況除外。

這個物件中包含 "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 上車或送貨欄位中的 VisitRequest 索引 (請參閱 isPickup)。
startTime

string (Timestamp format)

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

採用 RFC3339 世界標準時間「Zulu」格式的時間戳記，採用奈秒解析度和最多九個小數位數。範例："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 中已指定相應 Shipment.label 的副本。
visitLabel

string

VisitRequest 中已指定相應 VisitRequest.label 的副本。

轉場

路線上兩個事件之間的轉換。請參閱 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」格式的時間戳記，採用奈秒解析度和最多九個小數位數。範例："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」格式的時間戳記，採用奈秒解析度和最多九個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
duration

string (Duration format)

休息的時間長度。

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