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

לתשומת ליבכם: אנחנו עושים הבדל בין:

  • 'אירועים מדויקים', כמו תחילת הנסיעה וסיום הנסיעה ותחילת הביקור וסיום הביקור (כלומר הגעה ויציאה). הם מתרחשים בשנייה נתונה.
  • 'מרווחי זמן', כמו הביקורים עצמם והמעבר בין הביקורים. על אף שלפעמים מרווחי זמן יכולים להיות באורך אפס, כלומר תאריך התחלה וסיום באותה שנייה, משך הזמן שלהם בדרך כלל חיובי.

Invariants:

  • אם יש 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)

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

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

string (Timestamp format)

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

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

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

number

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

כניסה

ביקור שבוצע במהלך מסלול. הביקור הזה תואם לאיסוף או למשלוח של Shipment.

ייצוג JSON 
{
  "shipmentIndex": integer,
  "isPickup": boolean,
  "visitRequestIndex": integer,
  "startTime": string,
  "loadDemands": {
    string: {
      object (Load)
    },
    ...
  },
  "detour": string,
  "shipmentLabel": string,
  "visitLabel": string
}
שדות
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 (ראו את השדה הזה).
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.

מעבר

מעבר בין שני אירועים במסלול. הצגת התיאור של ShipmentRoute.

אם אין ברכב startLocation או endLocation, מדדי הנסיעה התואמים הם 0.

ייצוג ב-JSON 
{
  "travelDuration": string,
  "travelDistanceMeters": number,
  "trafficInfoUnavailable": boolean,
  "delayDuration": string,
  "breakDuration": string,
  "waitDuration": string,
  "totalDuration": string,
  "startTime": string,
  "routePolyline": {
    object (EncodedPolyline)
  },
  "routeToken": string,
  "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)

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

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

object (EncodedPolyline)

ייצוג הקוד של הקו הפוליגוני של המסלול שבו נעשה שימוש במהלך המעבר. השדה הזה מאוכלס רק אם השדה populateTransitionPolylines מוגדר כ-true.
routeToken

string

פלט בלבד. אסימון אטום שניתן להעביר ל-Navigation SDK כדי לשחזר את המסלול במהלך הניווט, ובמקרה של שינוי מסלול, הוא פועל בהתאם לכוונה המקורית בזמן יצירת המסלול. יש להתייחס לאסימון הזה כאל blob אטום. אל תשוו את הערך שלה בבקשות, כי הערך שלה עשוי להשתנות גם אם השירות מחזיר בדיוק את אותו מסלול. השדה הזה מאוכלס רק אם השדה populateTransitionPolylines מוגדר כ-true.
vehicleLoads

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

טעינת רכבים במהלך המעבר הזה, מכל סוג שמופיע בVehicle.load_limits של הרכב הזה, או שיש בהם Shipment.load_demands שאינם אפס במשלוחים מסוימים במסלול הזה.

העומסים במהלך המעבר הראשון הם העומסים ההתחלתיים של מסלול הרכב. לאחר מכן, אחרי כל ביקור, הערכים של loadDemands של הביקור מתווספים או מוחרגים כדי לקבל את העומסים של המעבר הבא, בהתאם לכך אם הביקור היה איסוף או משלוח.

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".