ساختار پایه (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"
  }
}