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

ה-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 כשביקור הוא משלוח. תשובות REST משמיטות את המאפיין הזה כאשר הערך הוא False.
  • visitRequestIndex הוא האינדקס מבוסס-אפס של VisitRequest מ-Shipment.pickups או מ-Shipment.deliveries בבקשה התואמת שמייצגת Visit. תגובות REST משמיטות את המאפיין הזה כאשר הערך הוא אפס.
  • startTime הוא הזמן שבו הביקור צפוי להתחיל.
  • loadDemands ממפה את סוג הטעינה כדי לחשב את סכום הטעינה שנדרש להשלמת 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 מתואר בקטע אופטימיזציה של הזמנות עם הפסקת איסוף ומסירה, וגם במסמכי העזר של ShipmentRoute (REST, gRPC).

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

ההודעה של 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 ממפה את סוגי העומסים לכמות העומס המקסימלית שכלי הרכב מעבירים בכל נקודה במסלולים.

הודעת 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
    }
  }
}

דוגמה מלאה

דוגמה מלאה לתגובה מלאה לבקשה מ-Construct a Request נראית כך:

{
  "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
    }
  }
}