המבנה הבסיסי (ShipmentModel,‏ Shipment ו-Vehicle)

ל-ShipmentModel יש אובייקט אחד של shipments עם סוג הודעה Shipment ואובייקט אחד של vehicles עם סוג הודעה Vehicle.

המטרה של Route Optimization API היא לתכנן מסלולים לצי של כלי רכב כדי לבקר בקבוצה של מיקומים. האובייקט OptimizeToursRequest מתאר את המאפיינים של כלי הרכב והמיקומים האלה, והוא המבנה הראשי של גוף הבקשה של כל נקודת קצה (endpoint).

המבנה הבסיסי של האובייקט OptimizeToursRequest הוא:

במסמך הזה מתוארים סוגי ההודעות הבאים:

  • ‫ShipmentModel: מכיל את רשימת המשלוחים, כלי הרכב הזמינים ואובייקטים אחרים שמתארים את הקשרים ביניהם.
  • ‫Shipment: מתאר את המיקומים שבהם הרכב צריך לבקר. הן יכולות לייצג חבילות אמיתיות שצריך לאסוף ולמסור, או מקומות שבהם הנהג ברכב מספק שירות.
  • ‫Vehicle: מתאר את אמצעי התחבורה בין מיקומי המשלוח. כל רכב תואם לרכב בפועל או לאדם שנע ברגל.

ShipmentModel

‫ShipmentModel מכיל את הרכיבים של בעיית אופטימיזציית המסלולים. הוא מכיל קבוצה של משלוחים שאפשר לבצע באמצעות קבוצה של כלי רכב, תוך התחשבות באילוצים וצמצום העלות הכוללת.

בטבלה הבאה מתוארים כמה מאפיינים רלוונטיים של ShipmentModel:

מאפיינים תיאור
shipments וגם vehicles אובייקטים נדרשים שמכילים את הפרטים של משלוח אחד או יותר ושל כלי רכב אחד או יותר.
globalStartTime וגם globalEndTime מציין את ההתחלה והסיום של חלון הזמן שבו כל הרכבים חייבים להשלים את כל המשלוחים. המאפיינים האלה לא נדרשים, אבל מומלץ לכלול אותם כי הכלי לאופטימיזציה פועל בצורה הטובה ביותר כשהוא פועל לפי מגבלות זמן.

הרשימה המלאה של המאפיינים ב-ShipmentModel מופיעה במאמרי העזרה.

ShipmentModel דוגמה

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

בדוגמה הזו, ערכי המאפיין ShipmentModel בבקשה הם:

נכס ערך תיאור
globalStartTime 2024-02-13T00:00:00.000Z התאריך ושעת ההתחלה של שעות הפעילות.
globalEndTime 2024-02-14T06:00:00.000Z התאריך והשעה של סיום שעות הפעילות.

הדוגמה הבאה היא דוגמת קוד של הודעת ShipmentModel שמשלבת את הערכים של תרחיש לדוגמה.

{
  "model": {
    "shipments": [
      ...
    ],
    "vehicles": [
      ...
    ],
   "globalStartTime": "2024-02-13T00:00:00.000Z",
   "globalEndTime": "2024-02-14T06:00:00.000Z"
  }
}

Shipment

סוג ההודעה Shipment מגדיר את מבנה המאפיינים של משלוח שאפשר למסור או של שירות שאפשר לבצע במסלול.

משלוח בחיים האמיתיים שווה להודעת `Shipment` אחת, שנכללת באובייקט `shipments`

כמו שמוצג בתרשים:

  • הודעת Shipment מכילה את כל המידע על משלוח או שירות אמיתיים.
  • כל ההודעות של Shipment מצוינות בשדה shipments.
  • השדה shipments מכיל הודעה אחת או יותר מסוג Shipment.

הודעת Shipment צריכה לכלול לפחות אובייקט pickups או deliveries אחד. ההגדרות של האובייקטים האלה הן:

  • pickups מגדיר את מיקום האיסוף של המשלוח.
  • deliveries מגדיר את מיקום המסירה של המשלוח.
  • גם pickups וגם deliveries מכילים סוג הודעה VisitRequest שמגדיר מיקומים ופרטים אחרים.

בטבלה הבאה מתוארים התרחישים השונים בהתאם להגדרות של pickups ו-deliveries בהודעת Shipment.

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

הרשימה המלאה של המאפיינים ב-Shipment מופיעה במאמרי העזרה.

Shipment דוגמה

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

  • הכלב הראשון נמצא במגדל קויט בסן פרנסיסקו. הקואורדינטות של המיקום הזה הן קו רוחב 37.8024 וקו אורך ‎-122.4058.
  • הכלב השני נמצא בפארק South Sunset Playground בסן פרנסיסקו. הקואורדינטות של המיקום הזה הן קו רוחב 37.7359 וקו אורך ‎-122.5011.
  • הפנסיון לכלבים שלכם נמצא בפארק מיסיון דולורס בסן פרנסיסקו. הקואורדינטות של המיקום הזה הן קו רוחב 37.759773 וקו אורך ‎-122.427063.

הדוגמה הבאה היא קוד של הודעת Shipment, שבה האובייקט shipments מכיל שני סוגי הודעות Shipment עם הקואורדינטות לדוגמה.

{
  "model": {
    "shipments": [
      {
        "pickups": [
          {
            "arrivalLocation": {
              "latitude": 37.8024,
              "longitude": -122.4058
            }
          }
        ],
        "deliveries": [
          {
            "arrivalLocation": {
              "latitude": 37.759773,
              "longitude": -122.427063
            }
          }
        ]
      },
      {
        "pickups": [
          {
            "arrivalLocation": {
              "latitude": 37.7359,
              "longitude": -122.5011
            }
          }
        ],
        "deliveries": [
          {
            "arrivalLocation": {
              "latitude": 37.759773,
              "longitude": -122.427063
            }
          }
        ]
      }
    ],
    "vehicles": [
    ...
    ]
  }
}

Vehicle

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

רכב בעולם האמיתי שווה להודעת Vehicle אחת, שנכללת באובייקט vehicles.

כמו שמוצג בתרשים:

  • הודעת Vehicle מכילה את כל המידע על רכב אמיתי.
  • כל ההודעות של Vehicle מצוינות בשדה vehicles.
  • השדה vehicles מכיל כמה הודעות Vehicle.

בטבלה הבאה מתוארים כמה מאפיינים רלוונטיים של Vehicle.

מאפיינים תיאור
startLocation וגם endLocation מיקומי ההתחלה והסיום של הרכבים, שהם חלק מהמסלול הסופי שעבר אופטימיזציה. אם לא מגדירים אותם, ברירת המחדל היא המיקום של איסוף המשלוח הראשון והמיקום של מסירת המשלוח האחרון.
costPerHour,‏ costPerKilometer,‏ costPerTraveledHour פרמטרים של עלות ספציפיים לרכב. מומלץ לכלול לפחות פרמטר עלות אחד בבקשה ל-API כדי לקבל מסלול אופטימלי. למידע נוסף על עלויות, קראו את המושג העיקרי מודל עלות.
startTimeWindows וגם endTimeWindows מגדירים את תקופות שבהן רכב יכול לפעול במסלול. התאריכים האלה צריכים להיות בטווח של חלון הזמן שבין globalStartTime ל-globalEndTime שהוגדר ב-ShipmentModel. המאפיין הזה לא חובה, אבל מומלץ לכלול אותו כי כלי האופטימיזציה פועל בצורה הכי טובה כשהוא עומד במגבלות הזמן.

Vehicle דוגמה

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

בדוגמה הזו, ערכי המאפיין Vehicle בבקשה הם:

נכס ערך תיאור
startLocation latitude: 37.759773, longitude: -122.427063 הקואורדינטות של נקודת ההתחלה של המסלול של הרכב. המיקומים האלה תואמים למיקום של מעון היום לכלבים שנמצא בפארק מישן דולורס בסן פרנסיסקו.
endLocation latitude: 37.759773, longitude: -122.427063 הקואורדינטות של נקודת הסיום של המסלול של הרכב. המיקומים האלה תואמים למיקום של מעון היום לכלבים שנמצא בפארק מישן דולורס בסן פרנסיסקו.
costPerHour 27 כמה אתם משלמים לנהג של הרכב של מעון היום לכלבים. אתם משלמים לנהג 27 דולר לשעה.

הקוד הבא הוא דוגמה להודעת Vehicle שמשלבת את הערכים של תרחיש לדוגמה.

{
  "model": {
    "shipments": [
    ...
    ],
    "vehicles": [
      {
        "startLocation": {
          "latitude": 37.759773,
          "longitude": -122.427063
        },
        "endLocation": {
          "latitude": 37.759773,
          "longitude": -122.427063
        },
        "costPerHour": 27
      }
    ]
  }
}

הרשימה המלאה של המאפיינים ב-Vehicle מופיעה במאמרי העזרה.

דוגמה לבקשה מלאה

דוגמת הקוד הבאה משלבת את הדוגמאות של ShipmentModel,‏ Shipment ו-Vehicle שמופיעות במסמך הזה, ומציגה דוגמה לבקשה מלאה.

{
  "model": {
    "shipments": [
      {
        "pickups": [
          {
            "arrivalLocation": {
              "latitude": 37.8024,
              "longitude": -122.4058
            }
          }
        ],
        "deliveries": [
          {
            "arrivalLocation": {
              "latitude": 37.759773,
              "longitude": -122.427063
            }
          }
        ]
      },
      {
        "pickups": [
          {
            "arrivalLocation": {
              "latitude": 37.7359,
              "longitude": -122.5011
            }
          }
        ],
        "deliveries": [
          {
            "arrivalLocation": {
              "latitude": 37.759773,
              "longitude": -122.427063
            }
          }
        ]
      }
    ],
    "vehicles": [
      {
        "startLocation": {
          "latitude": 37.759773,
          "longitude": -122.427063
        },
        "endLocation": {
          "latitude": 37.759773,
          "longitude": -122.427063
        },
        "costPerHour": 27
      }
    ],
    "globalStartTime": "2024-02-13T00:00:00.000Z",
    "globalEndTime": "2024-02-14T06:00:00.000Z"
  }
}