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

ה-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 הוא משך הזמן הכולל של המעבר, כולל נסיעות, זמני המתנה, הפסקות והשהיה.
  • סוג הטעינה של מפות Google על ידי 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
    }
  }
}

דוגמה מלאה

התגובה המלאה לדוגמה לבקשה של Build 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
    }
  }
}