פירוש התשובה

מפתחים באזור הכלכלי האירופי (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 אם הביקור הוא למשלוח. תגובות REST משמיטות את המאפיין הזה כשהערך הוא false.
  • ‫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
    }
  }
}