Method: projects.optimizeTours

یک OptimizeToursRequest حاوی یک ShipmentModel ارسال می‌کند و یک OptimizeToursResponse حاوی ShipmentRoute ها برمی‌گرداند، که مجموعه‌ای از مسیرها هستند که باید توسط وسایل نقلیه انجام شوند و هزینه کلی را به حداقل برسانند.

یک مدل ShipmentModel عمدتاً شامل Shipment هایی است که باید انجام شوند و Vehicle هایی که می‌توانند برای حمل Shipment ها استفاده شوند. ShipmentRoute ها، Shipment ها را به Vehicle ها اختصاص می‌دهند. به طور خاص‌تر، آنها مجموعه‌ای از Visit ها را به هر وسیله نقلیه اختصاص می‌دهند، که در آن Visit معادل VisitRequest است که به معنای دریافت یا تحویل Shipment است.

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

درخواست HTTP

POST https://routeoptimization.googleapis.com/v1/{parent=projects/*}:optimizeTours

این URL از سینتکس Transcoding در gRPC استفاده می‌کند.

پارامترهای مسیر

پارامترها
parent

string

الزامی. پروژه یا مکان مورد نظر برای برقراری تماس.

قالب:

  • projects/{project-id}
  • projects/{project-id}/locations/{location-id}

اگر هیچ مکانی مشخص نشده باشد، یک منطقه به طور خودکار انتخاب می‌شود.

درخواست بدنه

بدنه درخواست شامل داده‌هایی با ساختار زیر است:

نمایش JSON 
{
  "timeout": string,
  "model": {
    object (ShipmentModel)
  },
  "solvingMode": enum (SolvingMode),
  "searchMode": enum (SearchMode),
  "injectedFirstSolutionRoutes": [
    {
      object (ShipmentRoute)
    }
  ],
  "injectedSolutionConstraint": {
    object (InjectedSolutionConstraint)
  },
  "refreshDetailsRoutes": [
    {
      object (ShipmentRoute)
    }
  ],
  "interpretInjectedSolutionsUsingLabels": boolean,
  "considerRoadTraffic": boolean,
  "populatePolylines": boolean,
  "populateTransitionPolylines": boolean,
  "allowLargeDeadlineDespiteInterruptionRisk": boolean,
  "useGeodesicDistances": boolean,
  "label": string,
  "geodesicMetersPerSecond": number,
  "maxValidationErrors": integer
}
فیلدها
timeout

string ( Duration format)

اگر این مهلت زمانی تنظیم شود، سرور قبل از اتمام دوره مهلت زمانی یا رسیدن به مهلت سرور برای درخواست‌های همزمان، هر کدام که زودتر باشد، پاسخی را برمی‌گرداند.

برای درخواست‌های ناهمزمان، سرور (در صورت امکان) قبل از اتمام مهلت زمانی، یک راه‌حل ایجاد می‌کند.

مدت زمانی بر حسب ثانیه با حداکثر نه رقم کسری که به ' s ' ختم می‌شود. مثال: "3.5s" .

model

object ( ShipmentModel )

مدل حمل و نقل برای حل.

solvingMode

enum ( SolvingMode )

به طور پیش‌فرض، حالت حل DEFAULT_SOLVE (0) است.

searchMode

enum ( SearchMode )

حالت جستجو برای حل درخواست استفاده می‌شود.

injectedFirstSolutionRoutes[]

object ( ShipmentRoute )

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

این مدل هنگام ساخت اولین راه‌حل، محدود می‌شود. هر محموله‌ای که در یک مسیر انجام نشود، به طور ضمنی در راه‌حل اول نادیده گرفته می‌شود، اما ممکن است در راه‌حل‌های متوالی انجام شود.

راه حل باید برخی از فرضیات اعتبار اساسی را برآورده کند:

  • برای همه مسیرها، vehicleIndex باید در محدوده باشد و تکراری نباشد.
  • برای همه بازدیدها، shipmentIndex و visitRequestIndex باید در محدوده باشند.
  • یک محموله فقط می‌تواند در یک مسیر ارجاع داده شود.
  • دریافت محموله‌ی تحویلی-تحویلی باید قبل از تحویل انجام شود.
  • بیش از یک گزینه برای تحویل یا دریافت محموله نمی‌توان انجام داد.
  • برای همه مسیرها، زمان‌ها در حال افزایش هستند (یعنی، vehicleStartTime <= visits[0].start_time <= visits[1].start_time ... <= vehicleEndTime ).
  • یک حمل و نقل فقط می‌تواند روی وسیله نقلیه‌ای که مجاز است انجام شود. یک وسیله نقلیه در صورتی مجاز است که Shipment.allowed_vehicle_indices خالی باشد یا vehicleIndex آن در Shipment.allowed_vehicle_indices گنجانده شده باشد.

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

injectedSolutionConstraint

object ( InjectedSolutionConstraint )

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

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

refreshDetailsRoutes[]

object ( ShipmentRoute )

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

از تاریخ ۲۰۲۰/۱۱، این فقط خطوط چندخطی مسیرهای غیرخالی را پر می‌کند و مستلزم آن است که populatePolylines برابر با true باشد.

فیلدهای routePolyline مسیرهای ارسالی ممکن است با transitions ناسازگار باشند.

این فیلد نباید همراه با injectedFirstSolutionRoutes یا injectedSolutionConstraint استفاده شود.

Shipment.ignore و Vehicle.ignore هیچ تاثیری بر رفتار ندارند. خطوط چندخطی همچنان بین تمام بازدیدها در تمام مسیرهای غیر خالی، صرف نظر از اینکه محموله‌ها یا وسایل نقلیه مرتبط نادیده گرفته شوند یا خیر، پر می‌شوند.

interpretInjectedSolutionsUsingLabels

boolean

اگر درست باشد:

  • از ShipmentRoute.vehicle_label به جای vehicleIndex برای تطبیق مسیرها در یک راه‌حل تزریق‌شده با وسایل نقلیه در درخواست استفاده می‌کند؛ از نگاشت ShipmentRoute.vehicle_index اصلی به ShipmentRoute.vehicle_index جدید برای به‌روزرسانی ConstraintRelaxation.vehicle_indices در صورت خالی نبودن، استفاده مجدد می‌کند، اما نگاشت باید بدون ابهام باشد (یعنی چندین ShipmentRoute نباید vehicleIndex اصلی یکسانی را به اشتراک بگذارند).
  • از ShipmentRoute.Visit.shipment_label به جای shipmentIndex برای تطبیق بازدیدها در یک راه‌حل تزریق‌شده با محموله‌های موجود در درخواست استفاده می‌کند؛
  • از SkippedShipment.label به جای SkippedShipment.index برای تطبیق محموله‌های نادیده گرفته شده در محلول تزریق شده با محموله‌های درخواستی استفاده می‌کند.

این تفسیر در مورد فیلدهای injectedFirstSolutionRoutes ، injectedSolutionConstraint و refreshDetailsRoutes اعمال می‌شود. این تفسیر می‌تواند زمانی استفاده شود که شاخص‌های حمل و نقل یا وسیله نقلیه در درخواست از زمان ایجاد راه‌حل تغییر کرده باشند، شاید به این دلیل که محموله‌ها یا وسایل نقلیه از درخواست حذف یا به آن اضافه شده‌اند.

اگر درست باشد، برچسب‌های موجود در دسته‌های زیر باید حداکثر یک بار در دسته خود ظاهر شوند:

اگر یک vehicleLabel در راه‌حل تزریق‌شده با یک وسیله نقلیه درخواست مطابقت نداشته باشد، مسیر مربوطه به همراه بازدیدهای آن از راه‌حل حذف می‌شود. اگر یک shipmentLabel در راه‌حل تزریق‌شده با یک محموله درخواست مطابقت نداشته باشد، بازدید مربوطه از راه‌حل حذف می‌شود. اگر یک SkippedShipment.label در راه‌حل تزریق‌شده با یک محموله درخواست مطابقت نداشته باشد، SkippedShipment از راه‌حل حذف می‌شود.

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

نکته: فراخواننده باید اطمینان حاصل کند که هر Vehicle.label (به نام Shipment.label ) به طور منحصر به فرد یک موجودیت vehicle (به نام shipping) را که در دو درخواست مربوطه استفاده می‌شود، شناسایی می‌کند: درخواست قبلی که OptimizeToursResponse مورد استفاده در راه‌حل تزریق شده را تولید کرده است و درخواست فعلی که شامل راه‌حل تزریق شده است. بررسی‌های منحصر به فرد بودن که در بالا توضیح داده شد، برای تضمین این الزام کافی نیستند.

considerRoadTraffic

boolean

تخمین ترافیک را در محاسبه فیلدهای Transition.travel_duration ، Visit.start_time و vehicleEndTime در ShipmentRoute در تنظیم فیلد ShipmentRoute.has_traffic_infeasibilities و در محاسبه فیلد OptimizeToursResponse.total_cost در نظر بگیرید.

populatePolylines

boolean

اگر درست باشد، چندخطی‌ها در ShipmentRoute های پاسخ قرار می‌گیرند.

populateTransitionPolylines

boolean

اگر درست باشد، چندخطی‌ها و توکن‌های مسیر در پاسخ ShipmentRoute.transitions قرار داده می‌شوند.

allowLargeDeadlineDespiteInterruptionRisk

boolean

اگر این تنظیم شده باشد، درخواست می‌تواند مهلتی (به https://grpc.io/blog/deadlines مراجعه کنید) تا ۶۰ دقیقه داشته باشد. در غیر این صورت، حداکثر مهلت فقط ۳۰ دقیقه است. توجه داشته باشید که درخواست‌های طولانی مدت، خطر وقفه بسیار بیشتری (اما همچنان کم) دارند.

useGeodesicDistances

boolean

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

label

string

برچسبی که ممکن است برای شناسایی این درخواست استفاده شود، در OptimizeToursResponse.request_label گزارش شده است.

geodesicMetersPerSecond

number

وقتی useGeodesicDistances برابر با true باشد، این فیلد باید تنظیم شود و سرعت اعمال شده برای محاسبه زمان سفر را تعریف کند. مقدار آن باید حداقل ۱.۰ متر بر ثانیه باشد.

maxValidationErrors

integer

تعداد خطاهای اعتبارسنجی برگشتی را کوتاه می‌کند. این خطاها معمولاً به عنوان جزئیات خطای BadRequest ( https://cloud.google.com/apis/design/errors#error_details ) به یک payload خطای INVALID_ARGUMENT پیوست می‌شوند، مگر اینکه solvingMode=VALIDATE_ONLY باشد: به فیلد OptimizeToursResponse.validation_errors مراجعه کنید. این مقدار به طور پیش‌فرض ۱۰۰ است و حداکثر ۱۰۰۰۰ است.

بدنه پاسخ

در صورت موفقیت، بدنه پاسخ شامل نمونه‌ای از OptimizeToursResponse است.

دامنه‌های مجوز

به محدوده OAuth زیر نیاز دارد:

  • https://www.googleapis.com/auth/cloud-platform

مجوزهای IAM

به مجوز IAM زیر در منبع parent نیاز دارد:

  • routeoptimization.locations.use

برای اطلاعات بیشتر، به مستندات IAM مراجعه کنید.