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

טיפוסים בני מנייה (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)

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

number

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

boolean

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

string (Duration format)

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

string (Duration format)

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

string (Duration format)

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

string (Duration format)

משך המעבר הכולל, לשימושכם. הוא שווה ל:

  • הביקור הבא startTime (או vehicleEndTime אם זה המעבר האחרון) – startTime של המעבר הזה;
  • אם הערך של ShipmentRoute.has_traffic_infeasibilities הוא false, מתקיים גם התנאי הבא: totalDuration = travelDuration + delayDuration
  • breakDuration + waitDuration`.
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)

משך ההפסקה.

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