איך מפרשים את התגובה של Route Optimization API… בעזרת כלבים

אחרי ששולחים את הבקשה בשליחת הבקשה הראשונה, הכלי להצעת אופטימיזציה מחזיר OptimizeToursResponse. התשובה הזו היא תוכנית המסלול שהנהג צריך לפעול לפיה. במדריך הזה מוסבר איך לקרוא אותו.

סיכום תוכנית המסלול

בתרחיש של מעון היום לכלבים, כלי האופטימיזציה מקצה את כלב ההרים השוויצרי ואת הצ'יוואווה לרכב המסחרי, ומדלג על הרועה הגרמני. תוכנית המסלול של הנהג:

• התחלת משמרת בשעה 7:55 במעון היום.
• אוספים את כלב ההרים הברנזי ליד מגדל קויט בשעה 08:20.
• אוספים את הצ'יוואווה בפארק South Sunset Playground בשעה 08:58.
• חוזרים למעון בשעה 9:24 ומחכים עד שחלון ההורדה נפתח בשעה 9:30.
• להוריד את כלב ההרים השוויצרי בשעה 9:30.
• להוריד את הצ'יוואווה ב-09:35.
• סיום המשמרת ב-09:40.

המסלול עולה 147.22$, כולל קנס של 100 $על דילוג על הרועה הגרמני.

כדי לבדוק את התוצאות, משווים את התשובה שקיבלתם לתשובה המלאה לדוגמה. יכול להיות שהתוצאות יהיו שונות במקצת, כי זמני הנסיעה והמרחקים תלויים בנתוני הכבישים הנוכחיים.

{
  "routes": [
    {
      "vehicleStartTime": "2024-02-13T15:55:04Z",
      "vehicleEndTime": "2024-02-13T17:40:00Z",
      "visits": [
        {
          "isPickup": true,
          "startTime": "2024-02-13T16:20:00Z",
          "detour": "0s",
          "shipmentLabel": "Bernese mountain dog",
          "visitType": "PICKUP_SHIPMENT"
        },
        {
          "shipmentIndex": 1,
          "isPickup": true,
          "startTime": "2024-02-13T16:58:12Z",
          "detour": "2600s",
          "shipmentLabel": "Chihuahua",
          "visitType": "PICKUP_SHIPMENT"
        },
        {
          "startTime": "2024-02-13T17:30:00Z",
          "detour": "2297s",
          "shipmentLabel": "Bernese mountain dog",
          "visitType": "DELIVER_SHIPMENT"
        },
        {
          "shipmentIndex": 1,
          "startTime": "2024-02-13T17:35:00Z",
          "detour": "656s",
          "shipmentLabel": "Chihuahua",
          "visitType": "DELIVER_SHIPMENT"
        }
      ],
      "transitions": [
        {
          "travelDuration": "1496s",
          "travelDistanceMeters": 7082,
          "waitDuration": "0s",
          "totalDuration": "1496s",
          "startTime": "2024-02-13T15:55:04Z"
        },
        {
          "travelDuration": "1992s",
          "travelDistanceMeters": 16589,
          "waitDuration": "0s",
          "totalDuration": "1992s",
          "startTime": "2024-02-13T16:25:00Z"
        },
        {
          "travelDuration": "1252s",
          "travelDistanceMeters": 7860,
          "waitDuration": "356s",
          "totalDuration": "1608s",
          "startTime": "2024-02-13T17:03:12Z"
        },
        {
          "travelDuration": "0s",
          "waitDuration": "0s",
          "totalDuration": "0s",
          "startTime": "2024-02-13T17:35:00Z"
        },
        {
          "travelDuration": "0s",
          "waitDuration": "0s",
          "totalDuration": "0s",
          "startTime": "2024-02-13T17:40:00Z"
        }
      ],
      "metrics": {
        "performedShipmentCount": 2,
        "travelDuration": "4740s",
        "waitDuration": "356s",
        "delayDuration": "0s",
        "breakDuration": "0s",
        "visitDuration": "1200s",
        "totalDuration": "6296s",
        "travelDistanceMeters": 31531,
        "performedShipmentPenaltyCostSum": 2000
      },
      "routeCosts": {
        "model.vehicles.cost_per_hour": 47.22
      },
      "routeTotalCost": 47.22,
      "vehicleFullness": {
        "maxFullness": 0.3497777777777778,
        "activeSpan": 0.3497777777777778
      }
    }
  ],
  "skippedShipments": [
    {
      "index": 2,
      "label": "German shepherd",
      "penaltyCost": 100
    }
  ],
  "metrics": {
    "aggregatedRouteMetrics": {
      "performedShipmentCount": 2,
      "travelDuration": "4740s",
      "waitDuration": "356s",
      "delayDuration": "0s",
      "breakDuration": "0s",
      "visitDuration": "1200s",
      "totalDuration": "6296s",
      "travelDistanceMeters": 31531,
      "performedShipmentPenaltyCostSum": 2000
    },
    "usedVehicleCount": 1,
    "earliestVehicleStartTime": "2024-02-13T15:55:04Z",
    "latestVehicleEndTime": "2024-02-13T17:40:00Z",
    "totalCost": 147.22,
    "costs": {
      "model.vehicles.cost_per_hour": 47.22,
      "model.shipments.penalty_cost": 100
    }
  }
}
    

מבנה התשובה

OptimizeToursResponse כולל שני רכיבים עיקריים:

• ‫routes: תוכנית המסלול לכל רכב בצי, כולל הסדר והזמנים של כל איסוף ומשלוח. יש לכם מסחרית אחת, אז יש תוכנית מסלול אחת.
• ‫metrics: סיכום של כל תוכנית המסלול, כולל העלות הכוללת, משך הזמן והמרחק.

מכיוון שהאופטימיזציה מדלגת על הרועה הגרמני, התשובה כוללת גם את skippedShipments.

בקטעים הבאים מוסבר איפה אפשר למצוא כל פרט בסיכום של תוכנית המסלול בתשובה.

איזה רכב נוסע באיזה מסלול?

האופטימיזציה יוצרת תוכנית מסלול (המערך routes) שתואמת לסדר של vehicles בבקשה.

השדה vehicleIndex מזהה כל רכב על סמך המיקום שלו, שמתחיל מ-0. במקרה של המסחרית, המיקום הוא 0. השדות vehicleStartTime ו-vehicleEndTime מורים לנהג מתי להתחיל ומתי לסיים את המשמרת.

‫Route Optimization API מחזיר חותמות זמן ב-UTC, שמסומנות בסיומת Z, בלי קשר להפרש בבקשה. כדי לקבל את השעה בסן פרנסיסקו, צריך להפחית 8 שעות. לרכב המסחרי, המשמרת נמשכת מ-7:55 עד 9:40, כמו שמוצג בדוגמת הקוד הבאה.

{
"routes": [
    {
    // "vehicleIndex": 0, // Omitted in actual JSON response because it's 0
    "vehicleStartTime": "2024-02-13T15:55:04Z",
    "vehicleEndTime": "2024-02-13T17:40:00Z",
    ...
    }
  ]
  ...
}

מה סדר האיסוף וההורדה?

בכל מסלול, המערך visits מכיל את כל האיסופים והמשלוחים של הרכב שהוקצה בסדר כרונולוגי.

הערך של shipmentIndex בכל ביקור הוא המיקום של המשלוח בבקשה, החל מ-0: 0 הוא כלב ההרים השוויצרי ו-1 הוא הצ'יוואווה. בשדה shipmentLabel מוצגת התווית שהגדרתם לכל משלוח.

כדי להבחין בין איסוף לבין הורדה (או מסירה), אפשר לבדוק את השדות visitType או isPickup:

• ‫visitType: מגדיר במפורש את פעולת הביקור.
  • איסוף: visitType = "PICKUP_SHIPMENT"
  • משלוח: visitType = "DELIVER_SHIPMENT"
• ‫isPickup: שדה עזר בוליאני.
  • איסוף: isPickup = true
  • משלוח: isPickup = false (לא נכלל ב-JSON)

כדי לקבוע את רצף האירועים המדויק ואת זמן ההגעה הצפוי לכל מיקום, קוראים את המערך visits לפי הסדר. בטבלה הבאה מוצגת הפעולה של תוכנית הניתוב על סמך הסדר והערכים של השדות shipmentIndex, isPickup או visitType ו-startTime.

בדוגמת הקוד הבאה אפשר לראות איך התשובה מספקת את הרצף הזה:

{
  "routes": [
    {
      "visits": [
        {
          // "shipmentIndex": 0, // Omitted in actual JSON response because it's 0
          "isPickup": true,
          "startTime": "2024-02-13T16:20:00Z",
          "shipmentLabel": "Bernese mountain dog",
          "visitType": "PICKUP_SHIPMENT"
        },
        {
          "shipmentIndex": 1,
          "isPickup": true,
          "startTime": "2024-02-13T16:58:12Z",
          "shipmentLabel": "Chihuahua",
          "visitType": "PICKUP_SHIPMENT"
        },
        {
          // "shipmentIndex": 0, // Omitted in actual JSON response because it's 0
          // "isPickup": false, // Omitted in actual JSON response because it's false
          "startTime": "2024-02-13T17:30:00Z",
          "shipmentLabel": "Bernese mountain dog",
          "visitType": "DELIVER_SHIPMENT"
        },
        {
          "shipmentIndex": 1,
          // "isPickup": false, // Omitted in actual JSON response because it's false
          "startTime": "2024-02-13T17:35:00Z",
          "shipmentLabel": "Chihuahua",
          "visitType": "DELIVER_SHIPMENT"
        }
      ]
    }
  ]
}

לכל ביקור יש גם visitRequestIndex, שהוא המיקום (החל מ-0) של אפשרות האיסוף או המסירה שהכלי לאופטימיזציה בחר למשלוח. לכל כלב בתרחיש הזה יש רק אפשרות אחת לאיסוף ואפשרות אחת להורדה, כך שהערך של visitRequestIndex הוא תמיד 0, והתגובה משמיטה אותו.

מה קורה בין הביקורים?

בכל מסלול, המערך transitions מפרט את פרטי הנסיעה בין הביקורים. למרות ש-visits ו-transitions הן רשימות נפרדות, הן משתלבות זו בזו לאורך זמן, באופן הבא:

1. transitions[0] (נסיעה מההתחלה עד לביקור הראשון)
2. visits[0] (ביקור ראשון)
3. transitions[1] (נסיעה מהביקור הראשון לביקור השני)
4. visits[1] (ביקור שני)
5. ...
6. visits[N-1] (הביקור האחרון, כאשר N הוא המספר הכולל של הביקורים)
7. transitions[N] (נסיעה מהביקור האחרון עד לסיום)

כדי לעקוב אחרי ציר הזמן של המסלול, אפשר להסתכל על השדה startTime בשני המערכים. השדה startTime של מעבר הוא הזמן שבו הנהג מתחיל לנסוע, והשדה startTime של ביקור הוא הזמן שבו הנהג מתחיל את האיסוף או ההורדה.

בכל מעבר מוצגים זמן הנסיעה והמרחק הצפויים בין המיקומים. בטבלה הבאה ממופים השדות transitions ו-visits לפעולות של המסלול הכרונולוגי בתרחיש של מעון היום לכלבים.

בדוגמת הקוד הבאה אפשר לראות איך התגובה מספקת את הרצף הזה ל-transitions[0] ול-transitions[1]:

{
  "routes": [
    {
      "transitions": [
        {
          "travelDuration": "1496s",
          "travelDistanceMeters": 7082,
          "waitDuration": "0s",
          "totalDuration": "1496s",
          "startTime": "2024-02-13T15:55:04Z"
        },
        {
          "travelDuration": "1992s",
          "travelDistanceMeters": 16589,
          "waitDuration": "0s",
          "totalDuration": "1992s",
          "startTime": "2024-02-13T16:25:00Z"
        },
        ...
      ]
    }
  ]
}

כמה עולה המסלול?

אתם יכולים לבדוק כמה שדות בתגובה, בהתאם לצורך שלכם בעלות של רכב ספציפי או בעלות הכוללת של כל צי הרכבים.

בטבלה הבאה מפורטות כל הדרכים שבהן אפשר למצוא את פרטי העלות בתשובה:

העלויות שמופיעות ב-routeCosts וב-costs משקפות את מגבלות העלות שציינתם בבקשה. למידע נוסף, קראו את המאמר מושג מפתח: מודל עלות.

בתרחיש הזה של מעון הכלבים, בגלל שדילגתם על משלוח, העלות לכל מסלול והעלות הכוללת המצטברת שונות. עלות המסלול כוללת רק את העלויות שמשויכות למסלול הספציפי הזה (שכר הנהג), ועלות הצבירה הכוללת כוללת גם את הקנס על המשלוח שדילגו עליו. בדוגמת הקוד הבאה אפשר לראות איפה הערכים האלה נמצאים בתגובה:

{
  "routes": [
    {
      "vehicleStartTime": "2024-02-13T15:55:04Z",
      "vehicleEndTime": "2024-02-13T17:40:00Z",
      ...
      "routeCosts": {
        "model.vehicles.cost_per_hour": 47.22
      },
      "routeTotalCost": 47.22
    }
  ],
  "metrics": {
    "totalCost": 147.22,
    "costs": {
      "model.shipments.penalty_cost": 100,
      "model.vehicles.cost_per_hour": 47.22
    },
    ...
  }
}

לפי תוכנית המסלול, הנהג מפעיל את הרכב מ-7:55 עד 9:40, כלומר כשעה ו-45 דקות (6,296 שניות). לפי התעריף שהגדרתם, 27 $לשעה, עלות המסלול היא 47.22$. מכיוון שהאופטימיזציה דילגה על המשלוח של הרועה הגרמני, היא מוסיפה עלות קנס של 100$, כך שהעלות הכוללת המצטברת היא 147.22$.

למה המערכת דילגה על משלוח?

האופטימייזר מפרט את כל המשלוחים שהוא לא מבצע במערך skippedShipments. הסיבה לדילוג על משלוח תלויה בהגדרה של penaltyCost:

• משלוחים חובה (ללא penaltyCost): כלי האופטימיזציה אף פעם לא מדלג עליהם רק כי הם יקרים לביצוע. הוא מדלג על משלוח רק אם אי אפשר להתאים אותו לאף מסלול, למשל כי חלון הזמן שלו מתנגש עם משלוחים אחרים.
• משלוחים אופציונליים (עם penaltyCost): כלי האופטימיזציה יכול לדלג גם על המשלוחים האלה אם עלות הביצוע שלהם גבוהה מהקנס. אפשר להגדיר עלויות קנס שונות כדי לתעדף משלוחים מסוימים על פני אחרים.

בתרחיש הזה, חלון האיסוף של הרועה הגרמני מתנגש עם החלון של כלב ההרים השוויצרי. המרחק בין מגדל קויט לבין לנדס אנד הוא 25 דקות, ולכן הנהג לא יכול לבצע את שני האיסופים בטווח של 20 דקות. האופטימיזציה חייבת לדלג על אחד מהם. מכיוון שעלות הקנס של הרועה הגרמני נמוכה יותר (100$ לעומת 1,000 $ללקוח הרגיל), הכלי לאופטימיזציה מדלג עליו וצובר את הקנס בסך 100$.

בדוגמת הקוד הבאה מוצג האובייקט skippedShipments בתגובה:

{
  ...
  "skippedShipments": [
    {
      "index": 2,
      "label": "German shepherd",
      "penaltyCost": 100
    }
  ],
  ...
}

האובייקט skippedShipments בתשובה מכיל את השדות הבאים:

• ‫index: האינדקס מבוסס האפס של המשלוח בבקשה (2 למשלוח השלישי).
• ‫label: התווית שציינתם בבקשה ("רועה גרמני").
• ‫penaltyCost: עלות הקנס שציינתם בבקשה, שה-API מוסיף לעלות הכוללת.

כדי למנוע מהכלי לאופטימיזציה לדלג על משלוח, צריך להקל על האילוץ שגורם להתנגשות. לדוגמה, אפשר לבקש מהבעלים של הרועה הגרמני חלון זמנים גמיש יותר לאיסוף, ואז לעדכן את timeWindows של האיסוף הזה בבקשה.

שדות התשובה בדוגמה

בטבלה הבאה מתוארים כל שדות התגובה שמוחזרים ב-OptimizeToursResponse של התרחיש לדוגמה. לא צריך להשתמש בכל שדה כדי להבין את תוכנית המסלול, אבל אפשר לנתח את השדות האלה כדי להחליט איך להתאים את OptimizeToursRequest לצרכים העסקיים. מידע נוסף זמין במאמר מחזור החיים של תוכנית המסלול.

אתם יכולים לסנן את התוכן לפי הורה או לפי חיפוש טקסט.