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

  • הם לא חופפים.
  • ההשהיה היא ייחודית וחייבת להיות תקופה רציפה של זמן שמתחילה מיד לפני הביקור הבא (או סיום השימוש ברכב). לכן, מספיק לדעת את משך העיכוב כדי לדעת את שעת ההתחלה ושעת הסיום שלו.
  • ההפסקות הן פרקי זמן רצופים שלא חופפים. התגובה מציינת את שעת ההתחלה ואת משך כל הפסקה.
  • הפעולות 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)
  },
  "vehicleFullness": {
    object (VehicleFullness)
  },
  "routeCosts": {
    string: number,
    ...
  },
  "routeTotalCost": number
}
שדות
vehicleIndex

integer

הרכב שמבצע את המסלול, מזוהה לפי האינדקס שלו במקור ShipmentModel.
vehicleLabel

string

תווית הרכב שמבצע את המסלול הזה, ששווה ל-ShipmentModel.vehicles(vehicleIndex).label, אם צוין.
vehicleStartTime

string (Timestamp format)

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

הפלט שנוצר תמיד יהיה בפורמט RFC 3339, עם נורמליזציה של Z ושימוש ב-0, 3, 6 או 9 ספרות אחרי הנקודה. אפשר להשתמש גם בהיסטים אחרים חוץ מ-Z. דוגמאות: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".
vehicleEndTime

string (Timestamp format)

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

הפלט שנוצר תמיד יהיה בפורמט RFC 3339, עם נורמליזציה של Z ושימוש ב-0, 3, 6 או 9 ספרות אחרי הנקודה. אפשר להשתמש גם בהיסטים אחרים חוץ מ-Z. דוגמאות: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".
visits[]

object (Visit)

רצף מסודר של ביקורים שמייצג מסלול. visits[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, בהתאם להקשר.
vehicleFullness

object (VehicleFullness)

השדה VehicleFullness משמש לחישוב המרחק של המדדים המוגבלים מהמגבלות הרלוונטיות של הרכב. השדות שלו הם יחסים בין שדה מדד עם מכסה (למשל, AggregatedMetrics.travel_distance_meters) לבין המגבלה הרלוונטית על כלי הרכב (למשל, Vehicle.route_distance_limit).

ניסיוני: ההתנהגות או הקיום של השדה הזה עשויים להשתנות בעתיד.
routeCosts

map (key: string, value: number)

עלות המסלול, מחולקת לפי שדות בקשה שקשורים לעלויות. המפתחות הם נתיבי פרוטו, ביחס לקלט OptimizeToursRequest, לדוגמה, 'model.shipments.pickups.cost', והערכים הם העלות הכוללת שנוצרה על ידי שדה העלות המתאים, שנצברת לאורך המסלול כולו. במילים אחרות, costs["model.shipments.pickups.cost"] הוא סכום כל העלויות של איסוף לאורך המסלול. כל העלויות שמוגדרות במודל מדווחות כאן בפירוט, למעט עלויות שקשורות ל-TransitionAttributes, שמדווחות רק באופן מצטבר החל מ-2022/01.
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.

הפלט שנוצר תמיד יהיה בפורמט RFC 3339, עם נורמליזציה של Z ושימוש ב-0, 3, 6 או 9 ספרות אחרי הנקודה. אפשר להשתמש גם בהיסטים אחרים חוץ מ-Z. דוגמאות: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".
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.
injectedSolutionLocationToken

integer

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

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

ניסיוני: פרטים נוספים זמינים בכתובת https://developers.google.com/maps/tt/route-optimization/experimental/u-turn-avoidance/make-request.

מעבר

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

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

הפלט שנוצר תמיד יהיה בפורמט RFC 3339, עם נורמליזציה של Z ושימוש ב-0, 3, 6 או 9 ספרות אחרי הנקודה. אפשר להשתמש גם בהיסטים אחרים חוץ מ-Z. דוגמאות: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".
routePolyline

object (EncodedPolyline)

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

string

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

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

הפלט שנוצר תמיד יהיה בפורמט RFC 3339, עם נורמליזציה של Z ושימוש ב-0, 3, 6 או 9 ספרות אחרי הנקודה. אפשר להשתמש גם בהיסטים אחרים חוץ מ-Z. דוגמאות: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".
duration

string (Duration format)

משך ההפסקה.

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

VehicleFullness

‫VehicleFullness הוא מדד שמחשב את מידת התפוסה של כלי רכב. כל שדה VehicleFullness הוא בין 0 ל-1, והוא מחושב כיחס בין שדה מדד עם מכסה (למשל AggregatedMetrics.travel_distance_meters) לבין המגבלה הרלוונטית של כלי הרכב (למשל Vehicle.route_distance_limit), אם היא קיימת. אחרת, יחס המילוי לא מוגדר. אם המגבלה היא 0, הערך בשדה הוא 1. הערה: כשמסלול נתון לבעיות תנועה, יכול להיות שחלק מיחסי המילוי הגולמיים יעלו על 1.0, למשל אם הרכב חורג ממגבלת המרחק שלו. במקרים כאלה, אנחנו מגבילים את ערכי המלאות ל-1.0.

ייצוג ב-JSON 
{
  "maxFullness": number,
  "distance": number,
  "travelDuration": number,
  "activeDuration": number,
  "maxLoad": number,
  "activeSpan": number
}
שדות
maxFullness

number

הערך המקסימלי של כל שאר השדות בהודעה הזו.
distance

number

היחס בין AggregatedMetrics.travel_distance_meters לבין Vehicle.route_distance_limit. אם הערך של Vehicle.route_distance_limit לא מוגדר, גם הערך של השדה הזה לא מוגדר.
travelDuration

number

היחס בין [AggregatedMetrics.travel_duration_seconds][] לבין Vehicle.travel_duration_limit. אם הערך של Vehicle.travel_duration_limit לא מוגדר, גם הערך של השדה הזה לא מוגדר.
activeDuration

number

היחס בין [AggregatedMetrics.total_duration_seconds][] לבין Vehicle.route_duration_limit. אם הערך של Vehicle.route_duration_limit לא מוגדר, גם הערך של השדה הזה לא מוגדר.
maxLoad

number

היחס המקסימלי בין כל סוגי [AggregatedMetrics.max_load][] לבין Vehicle.load_limits המתאים. אם כל השדות Vehicle.load_limits לא מוגדרים, השדה הזה לא מוגדר.
activeSpan

number

היחס (vehicleEndTime – vehicleStartTime) / (latestVehicleEndTime – earliestVehicleStartTime) לרכב נתון. אם המכנה לא מופיע, הפונקציה משתמשת במקום זאת ב-(ShipmentModel.global_end_time - ShipmentModel.global_start_time).