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

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

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

• השדה model מכיל הודעה מסוג ShipmentModel עם שני שדות מפתח:
  • שדה shipments אחד, שמכיל הודעה אחת או יותר מסוג Shipment.
  • שדה vehicles אחד, שמכיל הודעה אחת או יותר מסוג Vehicle.

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

• ‫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 מכילה את כל המידע על משלוח או שירות אמיתי.
• כל ההודעות של 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.
• הבית השני של הכלב נמצא בפארק סאות' סנסט פלייגראונד בסן פרנסיסקו. הקואורדינטות של המיקום הזה הן קו רוחב 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 כוללת את כל המידע על כלי רכב אמיתי.
• כל ההודעות של Vehicle מצוינות בשדה vehicles.
• השדה vehicles מכיל כמה הודעות Vehicle.

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

מאפיינים	תיאור
startLocation וגם endLocation	נקודות ההתחלה והסיום של כלי הרכב, שהן חלק מהמסלול הסופי שעבר אופטימיזציה. אם לא מוגדרות נקודות איסוף, ברירת המחדל היא נקודת האיסוף של המשלוח הראשון ונקודת המסירה של המשלוח האחרון.
costPerHour,‏ costPerKilometer,‏ costPerTraveledHour	פרמטרים של עלויות שספציפיים לרכב. מומלץ לכלול לפחות פרמטר עלות אחד בבקשה ל-API כדי שה-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"
  }
}