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 במהלך מעבר.

  • הן לא חופפות.
  • הערך של DELAY הוא ייחודי וחייב להיות תקופה רציפה של זמן ממש לפני הביקור הבא (או סיום הנסיעה ברכב). לכן, מספיק לדעת מהו משך ההשהיה כדי לדעת את שעת ההתחלה ושעת הסיום.
  • קטעי ה-breakS הם רציפים ולא חופפים. התגובה מציינת את שעת ההתחלה ואת משך הזמן של כל הפסקה.
  • TRAVEL ו-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)

השעה שבה הרכב מתחיל את המסלול.

חותמת זמן בפורמט UTC 'Zulu' של RFC3339, עם רזולוציה של ננו-שנייה ועד תשע ספרות עשרוניות. דוגמאות: "2014-10-02T15:01:23Z" ו-"2014-10-02T15:01:23.045123456Z".
vehicleEndTime

string (Timestamp format)

השעה שבה הרכב מסיים את המסלול.

חותמת זמן בפורמט UTC 'Zulu' של RFC3339, עם רזולוציה של ננו-שנייה ועד תשע ספרות עשרוניות. דוגמאות: "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)

סביר להניח שהגעה אל next_visit תתרחש מאוחר יותר מחלון הזמן הנוכחי שלה בגלל האומדן המוגדל של זמן הנסיעה travelDuration(previous_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)

העלות של המסלול, לפי פירוט בשדות הבקשה שקשורים לעלויות. המפתחות הם נתיבים של פרוטו, ביחס לקלט OptimizeToursRequest, למשל 'model.shipments.pickups.cost', והערכים הם העלות הכוללת שנוצרה על ידי שדה העלות התואם, שנצברה לאורך המסלול כולו. במילים אחרות, costs["model.shipments.pickups.cost"] הוא הסכום של כל עלויות האיסוף במסלול. כל העלויות שמוגדרות במודל מדווחות כאן בפירוט, למעט עלויות שקשורות למאפייני מעבר, שמדווחות רק באופן מצטבר נכון ל-2022.

אובייקט שמכיל רשימה של "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,
  "injectedSolutionLocationToken": integer
}
שדות
shipmentIndex

integer

אינדקס של השדה shipments במקור ShipmentModel.
isPickup

boolean

אם הערך הוא True, הביקור תואם לאיסוף של Shipment. אחרת, הוא תואם למשלוח.
visitRequestIndex

integer

אינדקס של VisitRequest בשדה האיסוף או בשדה המשלוח של Shipment (מידע נוסף זמין בכתובת isPickup).
startTime

string (Timestamp format)

השעה שבה מתחיל הביקור. חשוב לדעת שהרכב עשוי להגיע למיקום הביקור לפני המועד הזה. הזמנים תואמים ל-ShipmentModel.

חותמת זמן בפורמט UTC 'Zulu' של RFC3339, עם רזולוציה של ננו-שנייה ועד תשע ספרות עשרוניות. דוגמאות: "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.

משך זמן בשניות עם עד תשע ספרות עשרוניות, שמסתיים ב-'s'. דוגמה: "3.5s".
shipmentLabel

string

עותק של Shipment.label התואם, אם הוא צוין ב-Shipment.
visitLabel

string

עותק של VisitRequest.label התואם, אם הוא צוין ב-VisitRequest.
injectedSolutionLocationToken

integer

אסימון אטום שמייצג מידע על מיקום הביקור.

יכול להיות ששדה זה יאוכלס בביקורים של נתיבי התוצאות כאשר VisitRequest.avoid_u_turns הוגדר כ-True עבור הביקור הזה או אם ShipmentModel.avoid_u_turns הוגדר כ-True בבקשה OptimizeToursRequest.

מעבר

מעבר בין שני אירועים במסלול. הצגת התיאור של 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)

משך הנסיעה במהלך המעבר.

משך זמן בשניות עם עד תשע ספרות עשרוניות, שמסתיים ב-'s'. דוגמה: "3.5s".
travelDistanceMeters

number

המרחק שעברתם במהלך המעבר.
trafficInfoUnavailable

boolean

כשמבקשים מידע על תנועה דרך OptimizeToursRequest.consider_road_traffic ולא ניתן לאחזר את פרטי התנועה של Transition, הערך של המשתנה הבוליאני הזה מוגדר כ-true. ייתכן שמדובר בבעיה זמנית (תקלה נדירה בשרתי התנועה בזמן אמת) או קבועה (אין נתונים לגבי המיקום הזה).
delayDuration

string (Duration format)

סכום משך הזמן של העיכובים שהוחלו על המעבר הזה. אם בכלל, העיכוב יתחיל בדיוק delayDuration שניות לפני האירוע הבא (ביקור או סיום הרכב). TransitionAttributes.delay.

משך זמן בשניות עם עד תשע ספרות עשרוניות, שמסתיים ב-'s'. דוגמה: "3.5s".
breakDuration

string (Duration format)

משך הזמן של ההפסקות במהלך המעבר, אם יש כאלה. פרטים על שעת ההתחלה והמשך של כל הפסקה נשמרים ב-ShipmentRoute.breaks.

משך זמן בשניות עם עד תשע ספרות עשרוניות, שמסתיים ב-'s'. דוגמה: "3.5s".
waitDuration

string (Duration format)

משך הזמן של ההמתנה במהלך המעבר. משך ההמתנה תואם לזמן ההמתנה ללא פעילות ולא כולל את זמן ההפסקה. חשוב גם לזכור שזמן ההמתנה הזה עשוי להתחלק למספר מקטעים לא רציפים.

משך זמן בשניות עם עד תשע ספרות עשרוניות, שמסתיים ב-'s'. דוגמה: "3.5s".
totalDuration

string (Duration format)

משך המעבר הכולל, לצורך נוחות. הוא שווה ל-:

  • הביקור הבא startTime (או vehicleEndTime אם זהו המעבר האחרון) – startTime של המעבר הזה.
  • אם הערך של ShipmentRoute.has_traffic_infeasibilities הוא False, גם הפונקציה הבאה כוללת: 'totalDuration = TravelDuration + delayDuration'
  • breakDuration + waitDuration`.

משך זמן בשניות עם עד תשע ספרות עשרוניות, שמסתיים ב-'s'. דוגמה: "3.5s".
startTime

string (Timestamp format)

שעת ההתחלה של המעבר הזה.

חותמת זמן בפורמט 'Zulu' בפורמט RFC3339 UTC, עם רזולוציה של ננו-שנייה ועד תשע ספרות אחרי הנקודה. דוגמאות: "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)

שעת ההתחלה של ההפסקה.

חותמת זמן בפורמט UTC 'Zulu' של RFC3339, עם רזולוציה של ננו-שנייה ועד תשע ספרות עשרוניות. דוגמאות: "2014-10-02T15:01:23Z" ו-"2014-10-02T15:01:23.045123456Z".
duration

string (Duration format)

משך ההפסקה.

משך זמן בשניות עם עד תשע ספרות עשרוניות, שמסתיים ב-'s'. דוגמה: "3.5s".