פירוש התשובה

מפתחים באזור הכלכלי האירופי (EEA)

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

דוגמה להודעה 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
    }
  }
}