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

מפתחים באזור הכלכלי האירופי (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.metricsMetrics.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
    }
  }
}