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 הן פעולות שניתן להפריע להן: אפשר להפריע להן כמה פעמים במהלך המעבר הזה. הלקוחות יכולים להניח שהפעולה 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,
  "visitType": enum (VisitType),
  "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.
visitType

enum (VisitType)

אופציונלי. מציין את סוג הביקור. ההגדרה הזו מחליפה את השדה Visit.is_pickup.
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.

VisitType

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

טיפוסים בני מנייה (enum)
VISIT_TYPE_UNSPECIFIED סוג הביקור לא צוין.
PICKUP_SHIPMENT ביקור תואם לאיסוף משלוח.
DELIVER_SHIPMENT ביקור מתאים למשלוח.

מעבר

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

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

הפלט שנוצר תמיד יהיה בפורמט 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).