ساختار پایه (مدل محموله، حمل و نقل و وسیله نقلیه)

ShipmentModel has one `shipments` object with a `Shipment` message type and one `vehicles` object with a `Vehicle` message type.

هدف API بهینه‌سازی مسیر، برنامه‌ریزی مسیرها برای ناوگانی از وسایل نقلیه برای بازدید از مجموعه‌ای از مکان‌ها است. شیء OptimizeToursRequest ویژگی‌های این وسایل نقلیه و مکان‌ها را توصیف می‌کند و ساختار اصلی بدنه درخواست هر نقطه پایانی است.

ساختار پایه شیء OptimizeToursRequest به شرح زیر است:

  • فیلد model ، حاوی یک پیام ShipmentModel است که شامل دو فیلد کلیدی است:
    • یک فیلد shipments ، که شامل یک یا چند پیام Shipment است.
    • یک فیلد مربوط به vehicles ، که شامل یک یا چند پیام Vehicle است.

این سند انواع پیام‌های زیر را شرح می‌دهد:

  • ShipmentModel : فهرست محموله‌ها، وسایل نقلیه موجود و سایر اشیاء که روابط آنها را توصیف می‌کند، در خود نگه می‌دارد.
  • Shipment : مکان‌هایی را که یک وسیله نقلیه قرار است از آنها بازدید کند، توصیف می‌کند. این مکان‌ها می‌توانند نشان‌دهنده بسته‌های واقعی برای تحویل یا مکان‌هایی باشند که راننده وسیله نقلیه خدماتی را انجام می‌دهد.
  • Vehicle : وسیله حمل و نقل بین مکان‌های حمل و نقل را توصیف می‌کند. هر وسیله نقلیه مربوط به یک وسیله نقلیه واقعی یا شخصی است که پیاده در حال حرکت است.

ShipmentModel

ShipmentModel عناصر مسئله بهینه‌سازی مسیر را در خود جای داده است. این مدل شامل مجموعه‌ای از محموله‌ها است که ممکن است توسط مجموعه‌ای از وسایل نقلیه انجام شوند، با در نظر گرفتن محدودیت‌ها و به حداقل رساندن هزینه کلی.

جدول زیر برخی از ویژگی‌های مرتبط با ShipmentModel را شرح می‌دهد:

خواص توضیحات
shipments و vehicles اشیاء مورد نیاز که حاوی جزئیات یک یا چند محموله و وسیله نقلیه هستند.
globalStartTime و globalEndTime شروع و پایان بازه زمانی را نشان می‌دهد که در آن همه وسایل نقلیه باید تمام محموله‌ها را تکمیل کنند. اگرچه این ویژگی‌ها الزامی نیستند، اما توصیه می‌شود آنها را لحاظ کنید زیرا بهینه‌ساز هنگام رعایت محدودیت‌های زمانی بهترین عملکرد را دارد.

برای لیست کامل ویژگی‌های ShipmentModel به مستندات مرجع مراجعه کنید.

مثال مدل ShipmentModel

در این مثال، شما یک سرویس مراقبت روزانه از سگ دارید و شروع به ایجاد درخواست خود می‌کنید. شما بعداً محموله‌ها و وسایل نقلیه را تعریف می‌کنید، اما می‌خواهید با تعیین ساعات کاری و هزینه عملیاتی ساعتی خود شروع کنید.

برای این مثال، مقادیر ویژگی ShipmentModel در درخواست شما به شرح زیر است:

ملک ارزش توضیحات
globalStartTime ‎۲۰۲۴-۰۲-۱۳T۰۰:۰۰:۰۰.۰۰۰Z‎ تاریخ و زمان شروع ساعات کاری.
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 ساختار ویژگی یک محموله قابل تحویل یا خدماتی که می‌تواند در یک مسیر انجام شود را تعریف می‌کند.

A real life shipment equals one `Shipment` message, which is contained within a `shipments` object

همانطور که در نمودار نشان داده شده است:

  • یک پیام 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

در این مثال، شما یک سرویس مراقبت از سگ دارید که در آن سگ‌ها را از خانه‌شان تحویل می‌گیرید و به مهدکودک خود تحویل می‌دهید. شما می‌خواهید محل تحویل گرفتن دو سگ را تنظیم کنید و محل تحویل آنها را به کسب و کار خود اختصاص دهید:

  • خانه‌ی اولین سگ در کویت تاور، سانفرانسیسکو است. مختصات این مکان عرض جغرافیایی ۳۷.۸۰۲۴ و طول جغرافیایی -۱۲۲.۴۰۵۸ است.
  • خانه دوم سگ در پارک ساوت سانست پلی‌گراند، سانفرانسیسکو است. مختصات این مکان عرض جغرافیایی ۳۷.۷۳۵۹ و طول جغرافیایی -۱۲۲.۵۰۱۱ است.
  • مهدکودک سگ شما در پارک میشن دولورس، سانفرانسیسکو واقع شده است. مختصات این مکان عرض جغرافیایی ۳۷.۷۵۹۷۷۳ و طول جغرافیایی -۱۲۲.۴۲۷۰۶۳ است.

در ادامه نمونه کدی از یک پیام Shipment message) آمده است که در آن شیء 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 ساختار ویژگی وسیله نقلیه‌ای را تعریف می‌کند که می‌تواند در یک مسیر، حمل و نقل انجام دهد.

A real life vehicle equals one `Vehicle` message, which is contained within a `vehicles` object

همانطور که در نمودار نشان داده شده است:

  • یک پیام Vehicle تمام اطلاعات یک وسیله نقلیه واقعی را دارد.
  • تمام پیام‌های Vehicle در فیلد vehicles مشخص می‌شوند.
  • فیلد vehicles شامل چندین پیام Vehicle است.

جدول زیر برخی از ویژگی‌های مربوط به یک Vehicle را شرح می‌دهد.

خواص توضیحات
startLocation و endLocation مکان شروع و پایان وسایل نقلیه، که بخشی از مسیر بهینه نهایی هستند. اگر تعریف نشده باشند، به طور پیش‌فرض به مکان‌های اولین دریافت محموله و آخرین تحویل محموله تبدیل می‌شوند.
costPerHour ، costPerKilometer ، costPerTraveledHour پارامترهای هزینه خاص وسیله نقلیه. توصیه می‌شود حداقل یک پارامتر هزینه در درخواست خود برای API داشته باشید تا یک مسیر بهینه را برگرداند. برای کسب اطلاعات بیشتر در مورد هزینه‌ها، به مفهوم کلیدی مدل هزینه مراجعه کنید.
startTimeWindows و endTimeWindows دوره‌های زمانی که یک وسیله نقلیه می‌تواند در یک مسیر فعالیت کند را تعریف کنید. این دوره‌ها باید در محدوده پنجره زمانی globalStartTime و globalEndTime تنظیم شده در ShipmentModel قرار گیرند. اگرچه این ویژگی الزامی نیست، اما توصیه می‌شود آن را لحاظ کنید زیرا بهینه‌ساز هنگام رعایت محدودیت‌های زمانی بهترین عملکرد را دارد.

مثال Vehicle

در این مثال، شما یک سرویس مراقبت روزانه از سگ‌ها دارید و می‌خواهید موقعیت مکانی وسیله نقلیه خود را در شروع و پایان روز و میزان مصرف بنزین آن را تعریف کنید. نیازی به مشخص کردن ساعات کاری وسیله نقلیه ندارید زیرا این ساعات با ساعاتی که در ویژگی‌های globalStartTime و globalEndTime در شیء ShipmentModel تعریف کرده‌اید، مطابقت دارند.

برای این مثال، مقادیر ویژگی Vehicle در درخواست شما به شرح زیر است:

ملک ارزش توضیحات
startLocation latitude : ۳۷.۷۵۹۷۷۳، longitude : -۱۲۲.۴۲۷۰۶۳ مختصات اولیه مسیر وسیله نقلیه شما. این مختصات با محل مهدکودک سگ شما که در پارک میشن دولورس، سانفرانسیسکو واقع شده است، مطابقت دارد.
endLocation latitude : ۳۷.۷۵۹۷۷۳، longitude : -۱۲۲.۴۲۷۰۶۳ مختصات انتهایی مسیر وسیله نقلیه شما. این مختصات با محل مهدکودک سگ شما که در پارک میشن دولورس، سانفرانسیسکو واقع شده است، مطابقت دارد.
costPerHour ۲۷ مبلغی که به راننده برای راندن وسیله نقلیه مهدکودک سگ خود پرداخت می‌کنید. شما به راننده ساعتی ۲۷ دلار پرداخت می‌کنید.

در ادامه نمونه کدی از یک پیام 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"
  }
}