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

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

למשל, 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
    }
  }
}

דוגמה מלאה

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