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

ה-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). מידע נוסף על המאפיינים routePolyline ו-routeToken בהודעה Transition זמין במאמר קווים פוליגונליים של מעבר ואסימוני מסלול.

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

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