ساختار پایه (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 مثال

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

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

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