ساختار پایه (ShipmentModel،‏ Shipment، و Vehicle)

ShipmentModel یک شیء `shipments` با نوع پیام `Shipment` و یک شیء `vehicles` با نوع پیام `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` که در شیء `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 مثال

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

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

در زیر نمونه کدی از پیام 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 مبلغی که به راننده برای رانندگی خودرو مهد سگ‌ها پرداخت می‌کنید. به راننده ساعتی ۲۷ دلار پرداخت می‌کنید.

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