تفسیر پاسخ Route Optimization API… با سگ‌ها

پس‌از ارسال درخواست در اولین درخواستتان را ایجاد کنید، بهینه‌ساز OptimizeToursResponse را برمی‌گرداند. این پاسخ طرح مسیر است که راننده شما باید دنبال کند. این راهنما به شما نشان می‌دهد چگونه آن را بخوانید.

خلاصه برنامه مسیر

برای سناریو مهد سگ‌ها، بهینه‌ساز سگ کوهستانی برنی و چی‌واوا را به ون شما اختصاص می‌دهد و سگ ژرمن شپرد را رد می‌کند. برنامه مسیر راننده شما به‌صورت زیر است:

• شروع نوبت کاری در ساعت ۷:۵۵ صبح در مهدکودک.
• سگ کوهستانی برنیز را ساعت ۸:۲۰ صبح نزدیک برج کویت بردارید.
• ساعت ۸:۵۸ صبح، سگ شی‌واوا را در «پارک زمین بازی ساوت سانست» بردارید.
• ساعت ۹:۲۴ صبح به مهدکودک برگردید و تا باز شدن پنجره تحویل در ساعت ۹:۳۰ صبح منتظر بمانید.
• سگ کوهستانی برن را ساعت ۹:۳۰ صبح تحویل بده.
• ساعت ۹:۳۵ صبح، چیهواهوا را پیاده کن.
• پایان نوبت کاری در ساعت ۹:۴۰ صبح.

هزینه طرح مسیر ۱۴۷٫۲۲ دلار است، شامل ۱۰۰ دلار جریمه برای رد کردن ژرمن شپرد.

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

{
  "routes": [
    {
      "vehicleStartTime": "2024-02-13T15:55:04Z",
      "vehicleEndTime": "2024-02-13T17:40:00Z",
      "visits": [
        {
          "isPickup": true,
          "startTime": "2024-02-13T16:20:00Z",
          "detour": "0s",
          "shipmentLabel": "Bernese mountain dog",
          "visitType": "PICKUP_SHIPMENT"
        },
        {
          "shipmentIndex": 1,
          "isPickup": true,
          "startTime": "2024-02-13T16:58:12Z",
          "detour": "2600s",
          "shipmentLabel": "Chihuahua",
          "visitType": "PICKUP_SHIPMENT"
        },
        {
          "startTime": "2024-02-13T17:30:00Z",
          "detour": "2297s",
          "shipmentLabel": "Bernese mountain dog",
          "visitType": "DELIVER_SHIPMENT"
        },
        {
          "shipmentIndex": 1,
          "startTime": "2024-02-13T17:35:00Z",
          "detour": "656s",
          "shipmentLabel": "Chihuahua",
          "visitType": "DELIVER_SHIPMENT"
        }
      ],
      "transitions": [
        {
          "travelDuration": "1496s",
          "travelDistanceMeters": 7082,
          "waitDuration": "0s",
          "totalDuration": "1496s",
          "startTime": "2024-02-13T15:55:04Z"
        },
        {
          "travelDuration": "1992s",
          "travelDistanceMeters": 16589,
          "waitDuration": "0s",
          "totalDuration": "1992s",
          "startTime": "2024-02-13T16:25:00Z"
        },
        {
          "travelDuration": "1252s",
          "travelDistanceMeters": 7860,
          "waitDuration": "356s",
          "totalDuration": "1608s",
          "startTime": "2024-02-13T17:03:12Z"
        },
        {
          "travelDuration": "0s",
          "waitDuration": "0s",
          "totalDuration": "0s",
          "startTime": "2024-02-13T17:35:00Z"
        },
        {
          "travelDuration": "0s",
          "waitDuration": "0s",
          "totalDuration": "0s",
          "startTime": "2024-02-13T17:40:00Z"
        }
      ],
      "metrics": {
        "performedShipmentCount": 2,
        "travelDuration": "4740s",
        "waitDuration": "356s",
        "delayDuration": "0s",
        "breakDuration": "0s",
        "visitDuration": "1200s",
        "totalDuration": "6296s",
        "travelDistanceMeters": 31531,
        "performedShipmentPenaltyCostSum": 2000
      },
      "routeCosts": {
        "model.vehicles.cost_per_hour": 47.22
      },
      "routeTotalCost": 47.22,
      "vehicleFullness": {
        "maxFullness": 0.3497777777777778,
        "activeSpan": 0.3497777777777778
      }
    }
  ],
  "skippedShipments": [
    {
      "index": 2,
      "label": "German shepherd",
      "penaltyCost": 100
    }
  ],
  "metrics": {
    "aggregatedRouteMetrics": {
      "performedShipmentCount": 2,
      "travelDuration": "4740s",
      "waitDuration": "356s",
      "delayDuration": "0s",
      "breakDuration": "0s",
      "visitDuration": "1200s",
      "totalDuration": "6296s",
      "travelDistanceMeters": 31531,
      "performedShipmentPenaltyCostSum": 2000
    },
    "usedVehicleCount": 1,
    "earliestVehicleStartTime": "2024-02-13T15:55:04Z",
    "latestVehicleEndTime": "2024-02-13T17:40:00Z",
    "totalCost": 147.22,
    "costs": {
      "model.vehicles.cost_per_hour": 47.22,
      "model.shipments.penalty_cost": 100
    }
  }
}
    

ساختار پاسخ

OptimizeToursResponse شامل دو مؤلفه اصلی است:

• routes: طرح مسیر برای هر خودرو در ناوگان شما، ازجمله ترتیب و زمان هر تحویل گرفتن و تحویل دادن. یک ون دارید، بنابراین یک طرح مسیر وجود دارد.
• metrics: خلاصه‌ای از کل برنامه مسیر، شامل هزینه کل، مدت، و مسافت.

چون بهینه‌ساز از ژرمن شپرد صرف‌نظر می‌کند، پاسخ همچنین شامل skippedShipments است.

بخش‌های زیر نشان می‌دهند که هر جزئیات خلاصه طرح مسیر را در پاسخ کجا پیدا کنید.

کدام وسیله نقلیه در کدام مسیر حرکت می‌کند؟

بهینه‌ساز طرح مسیری (آرایه routes) تولید می‌کند که با ترتیب vehicles در درخواست شما مطابقت دارد.

فیلد vehicleIndex هر خودرو را براساس موقعیت صفرپایه آن شناسایی می‌کند که برای ون شما ۰ است. فیلدهای vehicleStartTime و vehicleEndTime به راننده دستور می‌دهند که چه زمانی نوبت کاری خود را شروع و پایان دهد.

Route Optimization API مُهرهای زمان را در قالب UTC برمی‌گرداند که با پسوند Z مشخص می‌شود، صرف‌نظر از انحراف در درخواست شما. برای دریافت زمان سانفرانسیسکو، ۸ ساعت کم کنید. برای ون شما، نوبت کاری از ساعت ۷:۵۵ صبح تا ۹:۴۰ صبح است، همان‌طور که در نمونه کد زیر نشان داده شده است.

{
"routes": [
    {
    // "vehicleIndex": 0, // Omitted in actual JSON response because it's 0
    "vehicleStartTime": "2024-02-13T15:55:04Z",
    "vehicleEndTime": "2024-02-13T17:40:00Z",
    ...
    }
  ]
  ...
}

ترتیب سوار و پیاده کردن چیست؟

در هر مسیر، آرایه visits شامل همه سوار کردن‌ها و تحویل‌ها برای خودرو واگذارشده به‌ترتیب زمانی است.

shipmentIndex هر بازدید، موقعیت صفرپایه محموله در درخواست شما است: 0 سگ کوهستانی برنی است و 1 شی‌هواهوا است. فیلد shipmentLabel برچسبی را که برای هر محموله تنظیم کرده‌اید نشان می‌دهد.

برای تشخیص بین تحویل گرفتن و تحویل دادن (یا ارسال)، می‌توانید فیلدهای visitType یا isPickup را بررسی کنید:

• visitType: کنش بازدید را به‌طور صریح تعریف می‌کند.
  • تحویل: visitType = "PICKUP_SHIPMENT"
  • ارسال: visitType = "DELIVER_SHIPMENT"
• isPickup: فیلد کمکی بولی.
  • تحویل: isPickup = true
  • ارسال: isPickup = false (در JSON حذف شده است)

برای تعیین توالی دقیق رویدادها و زمان رسیدن موردانتظار به هر مکان، آرایه visits را به‌ترتیب بخوانید. جدول زیر کنش طرح مسیر را براساس ترتیب و مقادیر فیلدهای shipmentIndex، isPickup یا visitType، و startTime نشان می‌دهد.

نمونه کد زیر نشان می‌دهد که پاسخ چگونه این توالی را ارائه می‌دهد:

{
  "routes": [
    {
      "visits": [
        {
          // "shipmentIndex": 0, // Omitted in actual JSON response because it's 0
          "isPickup": true,
          "startTime": "2024-02-13T16:20:00Z",
          "shipmentLabel": "Bernese mountain dog",
          "visitType": "PICKUP_SHIPMENT"
        },
        {
          "shipmentIndex": 1,
          "isPickup": true,
          "startTime": "2024-02-13T16:58:12Z",
          "shipmentLabel": "Chihuahua",
          "visitType": "PICKUP_SHIPMENT"
        },
        {
          // "shipmentIndex": 0, // Omitted in actual JSON response because it's 0
          // "isPickup": false, // Omitted in actual JSON response because it's false
          "startTime": "2024-02-13T17:30:00Z",
          "shipmentLabel": "Bernese mountain dog",
          "visitType": "DELIVER_SHIPMENT"
        },
        {
          "shipmentIndex": 1,
          // "isPickup": false, // Omitted in actual JSON response because it's false
          "startTime": "2024-02-13T17:35:00Z",
          "shipmentLabel": "Chihuahua",
          "visitType": "DELIVER_SHIPMENT"
        }
      ]
    }
  ]
}

هر بازدید همچنین دارای یک visitRequestIndex است که موقعیت مبتنی بر صفر گزینه تحویل یا ارسال است که بهینه‌ساز برای محموله انتخاب کرده است. هر سگ در این سناریو فقط یک گزینه سوار کردن و یک گزینه پیاده کردن دارد، بنابراین visitRequestIndex همیشه 0 است و پاسخ آن را حذف می‌کند.

بین بازدیدها چه اتفاقی می‌افتد؟

در هر مسیر، آرایه transitions جزئیات سفر بین بازدیدها را فهرست می‌کند. اگرچه visits و transitions فهرست‌های جداگانه‌ای هستند، اما به‌صورت زیر در زمان تداخل دارند:

1. transitions[0] (رانندگی از شروع تا نخستین بازدید)
2. ‫visits[0] (نخستین بازدید)
3. transitions[1] (رانندگی از بازدید اول به بازدید دوم)
4. visits[1] (بازدید دوم)
5. ...
6. visits[N-1] (آخرین بازدید، که N تعداد کل بازدیدها است)
7. transitions[N] (رانندگی از آخرین بازدید تا پایان)

می‌توانید خط زمان مسیر را با نگاه کردن به فیلد startTime در هر دو آرایه دنبال کنید. startTime انتقال زمانی است که راننده سفر را شروع می‌کند، و startTime بازدید زمانی است که راننده سوار کردن یا پیاده کردن را شروع می‌کند.

هر گذار زمان رانندگی و فاصله موردانتظار بین مکان‌ها را نشان می‌دهد. جدول زیر هر دو فیلد transitions و visits را به کنش‌های مسیر زمانی برای سناریو مهدکودک سگ‌ها نگاشت می‌کند.

نمونه کد زیر نشان می‌دهد که چگونه پاسخ این توالی را برای transitions[0] و transitions[1] ارائه می‌دهد:

{
  "routes": [
    {
      "transitions": [
        {
          "travelDuration": "1496s",
          "travelDistanceMeters": 7082,
          "waitDuration": "0s",
          "totalDuration": "1496s",
          "startTime": "2024-02-13T15:55:04Z"
        },
        {
          "travelDuration": "1992s",
          "travelDistanceMeters": 16589,
          "waitDuration": "0s",
          "totalDuration": "1992s",
          "startTime": "2024-02-13T16:25:00Z"
        },
        ...
      ]
    }
  ]
}

هزینه این مسیر چقدر است؟

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

جدول زیر همه روش‌هایی را که می‌توانید اطلاعات هزینه را در پاسخ پیدا کنید فهرست می‌کند:

هزینه‌های مشخص‌شده در routeCosts و costs نشان‌دهنده محدودیت‌های هزینه است که در درخواستتان مشخص می‌کنید. برای اطلاعات بیشتر، به سند مفهوم کلیدی مدل هزینه مراجعه کنید.

برای این سناریو مهد سگ‌ها، چون یک ارسال ردشده دارید، هزینه هر مسیر و هزینه کل تجمیع‌شده متفاوت است. هزینه مسیر فقط شامل هزینه‌های مرتبط با آن مسیر خاص (دستمزد راننده) است، درحالی‌که هزینه کل تجمیع‌شده شامل جریمه محموله نادیده‌گرفته‌شده نیز می‌شود. نمونه کد زیر نشان می‌دهد که این مقادیر را در کجا می‌توانید در پاسخ پیدا کنید:

{
  "routes": [
    {
      "vehicleStartTime": "2024-02-13T15:55:04Z",
      "vehicleEndTime": "2024-02-13T17:40:00Z",
      ...
      "routeCosts": {
        "model.vehicles.cost_per_hour": 47.22
      },
      "routeTotalCost": 47.22
    }
  ],
  "metrics": {
    "totalCost": 147.22,
    "costs": {
      "model.shipments.penalty_cost": 100,
      "model.vehicles.cost_per_hour": 47.22
    },
    ...
  }
}

طبق برنامه مسیر، راننده ون را از ساعت ۷:۵۵ صبح تا ۹:۴۰ صبح می‌راند که تقریباً ۱ ساعت و ۴۵ دقیقه (۶۲۹۶ ثانیه) است. با نرخ تعریف‌شده شما که ۲۷ دلار در ساعت است، هزینه مسیر ۴۷٫۲۲ دلار است. چون بهینه‌ساز از محموله ژرمن شپرد صرف‌نظر کرد، هزینه جریمه ۱۰۰ دلاری اضافه می‌کند و مجموع هزینه کل را به ۱۴۷٫۲۲ دلار می‌رساند.

چرا ارسال رد شده است؟

بهینه‌ساز هر محموله‌ای را که انجام نمی‌دهد در آرایه skippedShipments فهرست می‌کند. دلیل رد شدن ارسال به این بستگی دارد که آیا penaltyCost را تنظیم کرده‌اید یا نه:

• محموله‌های اجباری (بدون penaltyCost): بهینه‌ساز هرگز این محموله‌ها را فقط به‌دلیل گران بودن اجرای آن‌ها نادیده نمی‌گیرد. تنها درصورتی از یک محموله صرف‌نظر می‌کند که نتواند آن را در هیچ مسیری قرار دهد، مثلاً به‌دلیل اینکه پنجره زمانی آن با محموله‌های دیگر تداخل دارد.
• محموله‌های اختیاری (با penaltyCost): بهینه‌ساز همچنین می‌تواند از این موارد صرف‌نظر کند اگر هزینه انجام آن‌ها بیشتر از جریمه باشد. می‌توانید هزینه‌های جریمه متفاوتی را برای اولویت‌بندی برخی محموله‌ها نسبت‌به سایرین تنظیم کنید.

در این سناریو، پنجره تحویل سگ ژرمن شپرد با پنجره سگ کوهستانی برن تداخل دارد. برج کویت و لندز اند ۲۵ دقیقه باهم فاصله دارند، بنابراین راننده نمی‌تواند هر دو سوار کردن را در بازه ۲۰ دقیقه‌ای انجام دهد. بهینه‌ساز باید یکی از آن‌ها را رد کند. چون ژرمن شپرد هزینه جریمه کمتری دارد (۱۰۰ دلار درمقابل ۱۰۰۰ دلار برای مشتری معمولی)، بهینه‌ساز از آن صرف‌نظر می‌کند و جریمه ۱۰۰ دلاری را متحمل می‌شود.

نمونه کد زیر شیء skippedShipments را در پاسخ نشان می‌دهد:

{
  ...
  "skippedShipments": [
    {
      "index": 2,
      "label": "German shepherd",
      "penaltyCost": 100
    }
  ],
  ...
}

شیء skippedShipments در پاسخ حاوی فیلدهای زیر است:

• index: نمایه صفرپایه محموله در درخواست شما (۲ برای محموله سوم).
• label: برچسبی که در درخواست مشخص کرده‌اید («German shepherd» (ژرمن شپرد)).
• penaltyCost: هزینه جریمه‌ای که در درخواست مشخص کرده‌اید و میانای برنامه‌سازی کاربردی آن را به هزینه کل اضافه می‌کند.

برای جلوگیری از رد شدن محموله توسط بهینه‌ساز، محدودیت ایجادکننده تداخل را کاهش دهید. برای مثال، از صاحب سگ ژرمن شپرد بخواهید بازه زمانی منعطف‌تری برای تحویل گرفتن سگ درنظر بگیرد، سپس timeWindows را برای آن تحویل گرفتن در درخواستتان به‌روز کنید.

فیلدهای پاسخ در مثال

جدول زیر همه فیلدهای پاسخ را که در OptimizeToursResponse سناریو نمونه برگردانده شده است شرح می‌دهد. اگرچه برای درک طرح مسیر نیازی به استفاده از همه فیلدها ندارید، می‌توانید این فیلدها را تجزیه‌وتحلیل کنید تا نحوه تنظیم OptimizeToursRequest خود را برای مطابقت با نیازهای کسب‌وکارتان تعیین کنید. برای اطلاعات بیشتر، چرخه حیات طرح مسیر را ببینید.

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