איך לפרש את התגובה

ה-Route Optimization API מחזיר מסלולים לכלי רכב בבקשה המתאימה. המשלוחים משויכים לכלי רכב, או שאפשר לדלג עליהם בהתאם למאפיינים של הבקשה.

להודעה ב-OptimizeToursResponse (REST, ‏ gRPC) יש שתי מאפיינים עיקריים ברמה העליונה:

• routes[] המסלולים של כל רכב עם המשלוחים שהוקצו לו. כל אחד מהם Route מכיל מדדים שמשקפים את המאפיינים של המסלול הספציפי הזה.
• ‫metrics הם מדדים מצטברים של כל התגובה, בכל כלי הרכב ובכל תוכניות המסלולים. מדדים ברמה העליונה מכילים את אותם מאפיינים כמו מדדים לכל מסלול, עם ערכים מצטברים בכל המסלולים.

יכול להיות שחלק מהמאפיינים לא יאוכלסו תמיד, בהתאם לתוצאות האופטימיזציה:

1. skippedShipments[] רשימת משלוחים שלא מתבצעים על ידי כלי רכב. אפשר לדלג על משלוח אם אי אפשר לבצע אותו במסגרת המגבלות שצוינו או אם העלות של ביצוע המשלוח גבוהה יותר מעלות הקנס. לדוגמה, אם חלון הזמן לאיסוף או למסירה של משלוח מסוים הוא קצר מאוד timeWindow יכול להיות שלא יהיה אפשר לבצע את הביקור ברכב במהלך חלון הזמן הנדרש, או שזה לא יהיה משתלם.
2. הפרמטר validationErrors[] מציין שגיאות שגורמות לכך שהבקשה לא תקינה או שאי אפשר לפתור אותה כשהערך של הפרמטר solvingMode בבקשה מוגדר ל-VALIDATE_ONLY. במצב DEFAULT_SOLVE הרגיל, שגיאות האימות יופיעו בהודעת שגיאה במקום בגוף התגובה. שימו לב: במצב פתרון בעיות אפשר לדווח על כמה שגיאות בבת אחת, וזה שימושי לניפוי באגים מהיר של בקשות.VALIDATE_ONLY

מאפייני מסלול

כל רשומה routes[] היא הודעה ShipmentRoute (REST, ‏ gRPC). כל ShipmentRoute מייצג את הקצאת המסלול לרכב מסוים מהבקשה. מאפיינים חשובים של ShipmentRoute שקשורים ל-Vehicle המתאים כוללים:

• ‫vehicleIndex הוא האינדקס מבוסס-האפס של Vehicle בהודעת הבקשה המתאימה. בתגובות REST, המאפיין הזה מושמט כשהערך הוא אפס.
• ‫vehicleStartTime היא השעה שבה הרכב צריך להתחיל את המסלול.
• ‫vehicleEndTime הוא הזמן שבו הרכב צפוי לסיים את המסלול שלו.

בתגובה, routes ייראה כך:

{
  "routes": [
    {
      "vehicleStartTime": "2024-02-13T00:00:00Z",
      "vehicleEndTime": "2024-02-13T00:38:42Z",
      "visits": [
        ...
      ],
      "transitions": [
        ...
      ],
      "metrics": {
        ...
      },
      ...
    }
  ],
  ...
}

כל ShipmentRoute כולל רשימה ממוספרת של visits שהרכב ישלים. כל Visit (REST, gRPC) מייצג VisitRequest (REST, gRPC) מהבקשה המתאימה. Visit מאפיינים חשובים:

• ‫shipmentIndex הוא האינדקס מבוסס-האפס של המשלוח שאליו הביקור הזה משויך בבקשה המתאימה.
• הערך של isPickup הוא true אם הביקור הוא לאיסוף, ו-false אם הביקור הוא למשלוח. אם הערך הוא false, המאפיין הזה לא מופיע בתשובות REST.
• ‫visitRequestIndex הוא האינדקס מבוסס-האפס של VisitRequest מתוך Shipment.pickups או Shipment.deliveries בבקשה המתאימה ש-Visit מייצג. אם הערך הוא אפס, התגובות של REST לא כוללות את המאפיין הזה.
• ‫startTime היא השעה שבה הביקור צפוי להתחיל.
• ‫loadDemands maps load type to load amount demanded to complete the Visit. סכומי הטעינה הם שליליים בביקורים לצורך מסירה, ומייצגים טעינה שמוסרת מהרכב.

דוגמה ל-Visit:

{
  "routes": [
    {
      ...
      "visits": [
        {
          "isPickup": true,
          "startTime": "2024-02-13T00:00:00Z",
          "detour": "0s"
        },
        ...
      ],
    },
    ...
  ],
  ...
}

כל ShipmentRoute כולל רשימה מסודרת של transitions שמייצגים נסיעה בין visits ברכב מסוים. מאפיינים חשובים של Transitionהודעה (REST, ‏ gRPC) כוללים:

• ‫startTime היא השעה שבה הרכב יתחיל לבצע את המעבר.
• ‫travelDuration הוא משך הזמן שנדרש לרכב כדי להגיע ליעד ולהשלים את המעבר.
• ‫travelDistanceMeters הוא המרחק במטרים שהרכב צריך לעבור כדי להשלים את המעבר.
• ‫trafficInfoUnavailable מציין אם נתוני התנועה זמינים למעבר.
• ‫waitDuration מייצג את משך הזמן שהרכב ממתין לפני שהוא יכול להתחיל את Visit הבא. יכול להיות שהחיוב הזה נובע מstart_time של Visit הבאים.
• ‫totalDuration הוא משך המעבר הכולל, כולל זמני הנסיעה, ההמתנה, ההפסקה והעיכוב.
• vehicleLoads סוג טעינת המפות לטעינת הכמות שמועברת על ידי הרכב במהלך המעבר הזה.

דוגמה ל-Transition:

{
  "routes": [
    {
      ...
      "transitions": [
        ...
        {
          "travelDuration": "1171s",
          "travelDistanceMeters": 9004,
          "waitDuration": "0s",
          "totalDuration": "1171s",
          "startTime": "2024-02-13T00:00:00Z"
        },
        ...
      ],
      ...
    }
  ],
  ...
}

מידע נוסף על הקשר בין vists לבין transitions זמין במאמר Pickup and Delivery Stop Order Optimization ובמאמרי העזרה של ShipmentRoute (REST,‏ gRPC). מידע נוסף על המאפיינים routePolyline ו-routeToken של הודעת Transition זמין במאמר Transition Polylines and Route Tokens.

מאפייני המדדים

ההודעה Metrics (REST, ‏ gRPC) מסכמת את הפתרון כולו. כמה מאפיינים חשובים של Metrics:

• ‫totalCost היא העלות הכוללת שהצטברה במהלך השלמת המסלולים. מידע נוסף על עלויות זמין במאמר פרמטרים של מודל עלויות.
• ‫usedVehicleCount הוא המספר הכולל של כלי הרכב שנעשה בהם שימוש בפתרון. יכול להיות שיהיו לרכבים מסלולים ריקים אם הכלי לאופטימיזציה יקבע שהשימוש בהם לא נחוץ.
• ‫skippedMandatoryShipmentCount הוא מספר המשלוחים שדילגו עליהם והם 'חובה'. במשלוח חובה לא מצוין penaltyCost שחל אם מדלגים על המשלוח. עדיין אפשר לדלג על משלוחים חובה אם הביצועים שלהם לא אפשריים במסגרת ההגבלות שצוינו. מידע נוסף על עלויות זמין במאמר פרמטרים של מודל עלויות.

מדדים נוספים מדווחים כהודעות AggregatedMetrics (REST,‏ gRPC). סוג ההודעה AggregatedMetrics משמש לנכס Metrics.aggregatedRouteMetrics ולנכס ShipmentRoute.metrics. הנכס Metrics.aggregatedRouteMetrics מכיל מדדים שנצברים בכל הרכיבים מסוג ShipmentRoute ב-OptimizeToursResponse. כל ShipmentRoute.metricsנכס מכיל מדדים שרלוונטיים לאותו ShipmentRoute.

בין המאפיינים החשובים של AggregatedMetrics:

• ‫performedShipmentCount הוא מספר המשלוחים שבוצעו על ידי כלי רכב לאורך המסלולים שלהם.
• ‫travelDuration הוא הזמן הכולל שכלי הרכב מבלים בנסיעה במהלך השלמת המסלולים שלהם.
• ‫waitDuration הוא הזמן הכולל שכלי הרכב מבזבקים בהמתנה במהלך השלמת המסלולים שלהם.
• ‫delayDuration הוא זמן העיכוב הכולל של כלי הרכב. הערך הזה הוא בדרך כלל אפס, אלא אם נעשה שימוש ב-TransitionAttributes בבקשה.
• ‫breakDuration הוא הזמן הכולל שכלי הרכב מבלים בהפסקות במהלך השלמת המסלולים.
• ‫visitDuration הוא הזמן הכולל שכלי הרכב מבזבזים על ביצוע ביקורים במהלך השלמת המסלולים שלהם. הערך הזה הוא למעשה סכום כל הערכים של VisitRequest.duration עבור VisitRequest שמתאימים לערכים של Visit שהוקצו לרכב הרלוונטי.
• ‫totalDuration הוא משך הזמן הכולל שנדרש להשלמת המסלולים של כלי הרכב.
• ‫travelDistanceMeters הוא המרחק הכולל שכלי הרכב עברו במהלך השלמת המסלולים שלהם.
• ‫maxLoads Maps load types to the maximum load amount carried by the vehicles at any point on their routes.

דוגמה להודעה עם Metrics:

{
  "routes": [
    ...
  ],
  "metrics": {
    "aggregatedRouteMetrics": {
      "performedShipmentCount": 1,
      "travelDuration": "2322s",
      "waitDuration": "0s",
      "delayDuration": "0s",
      "breakDuration": "0s",
      "visitDuration": "0s",
      "totalDuration": "2322s",
      "travelDistanceMeters": 18603
    },
    "usedVehicleCount": 1,
    "earliestVehicleStartTime": "2024-02-13T00:00:00Z",
    "latestVehicleEndTime": "2024-02-13T00:38:42Z",
    "totalCost": 18.603,
    "costs": {
      "model.vehicles.cost_per_kilometer": 18.603
    }
  }
}

דוגמה מלאה

דוגמה מלאה לתגובה לבקשה מתוך יצירת בקשה:

{
  "routes": [
    {
      "vehicleStartTime": "2024-02-13T00:00:00Z",
      "vehicleEndTime": "2024-02-13T00:38:42Z",
      "visits": [
        {
          "isPickup": true,
          "startTime": "2024-02-13T00:00:00Z",
          "detour": "0s"
        },
        {
          "startTime": "2024-02-13T00:19:31Z",
          "detour": "0s"
        }
      ],
      "transitions": [
        {
          "travelDuration": "0s",
          "waitDuration": "0s",
          "totalDuration": "0s",
          "startTime": "2024-02-13T00:00:00Z"
        },
        {
          "travelDuration": "1171s",
          "travelDistanceMeters": 9004,
          "waitDuration": "0s",
          "totalDuration": "1171s",
          "startTime": "2024-02-13T00:00:00Z"
        },
        {
          "travelDuration": "1151s",
          "travelDistanceMeters": 9599,
          "waitDuration": "0s",
          "totalDuration": "1151s",
          "startTime": "2024-02-13T00:19:31Z"
        }
      ],
      "metrics": {
        "performedShipmentCount": 1,
        "travelDuration": "2322s",
        "waitDuration": "0s",
        "delayDuration": "0s",
        "breakDuration": "0s",
        "visitDuration": "0s",
        "totalDuration": "2322s",
        "travelDistanceMeters": 18603
      },
      "routeCosts": {
        "model.vehicles.cost_per_kilometer": 18.603
      },
      "routeTotalCost": 18.603
    }
  ],
  "metrics": {
    "aggregatedRouteMetrics": {
      "performedShipmentCount": 1,
      "travelDuration": "2322s",
      "waitDuration": "0s",
      "delayDuration": "0s",
      "breakDuration": "0s",
      "visitDuration": "0s",
      "totalDuration": "2322s",
      "travelDistanceMeters": 18603
    },
    "usedVehicleCount": 1,
    "earliestVehicleStartTime": "2024-02-13T00:00:00Z",
    "latestVehicleEndTime": "2024-02-13T00:38:42Z",
    "totalCost": 18.603,
    "costs": {
      "model.vehicles.cost_per_kilometer": 18.603
    }
  }
}