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

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

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

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

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

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

ShipmentModel

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

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

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

ShipmentModel דוגמה

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

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

בדוגמה הבאה מוצג קוד של הודעת 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.

רשימה מלאה של המאפיינים ב-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.

Vehicle דוגמה

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

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

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