اولین درخواست «بهینه‌سازی مسیر» خود را… با سگ‌ها انجام دهید

این سند به شما نشان می‌دهد که چگونه اولین درخواست خود را به Route Optimization API بااستفاده از یک سناریوی کاربردی در دنیای واقعی ارسال کنید.

برای سادگی، در این مثال از HTTP و JSON برای نمایش REST API استفاده می‌شود. بااین‌حال، برای محیط تولید شما، توصیه کلی این است که از gRPC به‌دلیل مزایای عملکردی آن استفاده کنید. بااین‌حال، gRPC به نصب نیاز دارد. برای اطلاعات بیشتر، به کتابخانه‌های کارخواه Route Optimization API مراجعه کنید.

سناریو

شما یک سرویس مهدکودک سگ را از ساعت ۷ صبح تا ۷ بعدازظهر در سان فرانسیسکو اداره می‌کنید. امروز صبح می‌خواهید سه سگ را از مکان‌های مختلف در شهر بگیرید و آن‌ها را به مرکز مراقبت روزانه خود بیاورید.

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

یک ون برای این کار دارید و به راننده ساعتی ۲۷ دلار پرداخت می‌کنید. راننده و ون روز را در ساعت ۷ صبح در مهدکودک شما شروع می‌کنند و باید تا ظهر برای استراحت ناهار از سوار کردن‌های صبحگاهی برگردند.

امروز ۱۳ فوریه ۲۰۲۴ است. همه زمان‌ها در این سناریو به وقت محلی سان‌فرانسیسکو است که در ماه فوریه «زمان استاندارد اقیانوس آرام» (UTC-8) است. راننده تکالیف زیر را دارد:

• سگ کوهستانی برن را نزدیک برج کویت سوار کنید. مالک درخواست کرد بازه زمانی تحویل محدود بین ۸:۰۰ تا ۸:۲۰ صبح باشد.
• سگ شی‌واوا را در پارک زمین بازی South Sunset بردارید. مالک بازه زمانی تحویل انعطاف‌پذیرتری بین ۷:۳۰ صبح و ۹:۳۰ صبح پیشنهاد داد.
• ژرمن شپرد را در لندز اند سوار کن. مالک همچنین درخواست کرد که پنجره تحویل محدود بین ساعت ۸ تا ۸:۲۰ صبح باشد.
• سگ‌ها را در مرکز نگهداری روزانه در پارک میشن دولورس پیاده کنید. مهدکودک تحویل کودکان را بین ۹:۳۰ صبح تا ۱۱:۳۰ صبح الزامی می‌کند.

هر بازدید برای سوار کردن و پیاده کردن سگ ۵ دقیقه طول می‌کشد.

چون «لندز اند» از «برج کویت» دور است و زمان‌های تحویل آن‌ها باهم تداخل دارد، راننده نمی‌تواند هر سه تحویل را انجام دهد. بهینه‌ساز باید انتخاب کند که از کدام سگ صرف‌نظر کند تا هزینه کل (دستمزد راننده و هرگونه جریمه صرف‌نظر کردن) را به‌حداقل برساند.

قبل‌از شروع

برای اجرای کد در این سناریو نمونه، ابتدا باید دستورالعمل‌های موجود در راه‌اندازی Route Optimization API را تکمیل کنید.

۱. رویکرد بهینه‌سازی مسیرتان را انتخاب کنید

Route Optimization API روش‌های متعددی دارد که می‌توانید بسته به پیچیدگی مسئله بهینه‌سازی‌تان از بین آن‌ها انتخاب کنید.

چون این سناریوی مهد سگ‌ها درخواستی کوچک و ساده است، از روش مسدودسازی مثل optimizeTours استفاده کنید که نتایج را به‌سرعت برای درخواست‌های کوچک ارائه می‌دهد. برای اطلاعات بیشتر درباره نقاط پایانی Route Optimization API، انتخاب نقطه پایانی را ببینید.

از نشانی وب زیر برای ایجاد درخواست HTTP POST به روش optimizeTours استفاده کنید:

https://routeoptimization.googleapis.com/v1/projects/PROJECT_OR_ID:optimizeTours

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

• پارامتر timeout را روی ۲ ثانیه تنظیم کنید.
• تنظیمات مهلت را روی پیش‌فرض بگذارید که برای درخواست‌های REST،‏ ۶۰ ثانیه است.

۲. ساختن متن اصلی پیام درخواست

پس‌از انتخاب روش مسدود کردن optimizeTours و تعریف تنظیمات مهلت و زمان اتمام، مرحله بعدی شما ساختن بدنه پیام درخواست است.

برای این سناریو، درخواست یک پیام OptimizeToursRequest است که به‌صورت JSON در REST API کدگذاری شده است.

برای ساختن پیام درخواست، مراحل زیر را دنبال کنید:

1. با ساختار درخواست پایه شروع کنید که به‌صورت زیر است:

   {
     "timeout": ...,
     "model": {
       "shipments": [...],
       "vehicles": [...],
       "globalStartTime": "...",
       "globalEndTime": "..."
     }
   }
   

   برای اطلاعات بیشتر درباره ساختار، به راهنمای مفهوم کلیدی برای ساختار پایه (ShipmentModel،‏ Shipment، و Vehicle) مراجعه کنید.

2. محموله‌ها را تعریف کنید. در فیلد shipments، برای هر سگی که باید صبح سوار و پیاده شود، پیامی Shipment اضافه کنید. اینجا جایی است که هریک از مکان‌ها و زمان‌های ترجیحی صاحب سگ برای تحویل گرفتن سگ و مکان و زمان‌های مرکز نگهداری روزانه برای تحویل دادن سگ را تعریف می‌کنید.

   1. برای هر سگ، یک VisitRequest برای تحویل گرفتن و یک دیگر برای تحویل دادن ایجاد کنید که در این سناریو به آن تحویل دادن به مهدکودک گفته می‌شود.

      • در سوار کردن، arrivalWaypoint را روی محل سوار کردن سگ تنظیم کنید (برج کویت برای سگ کوهستانی برن، پارک زمین بازی غروب آفتاب جنوبی برای شی‌واوا، یا لندز اند برای سگ ژرمن شپرد). timeWindows را روی زمان تحویل درخواستی مالک تنظیم کنید (۸ تا ۸:۲۰ صبح برای سگ کوهستانی برنی و ژرمن شپرد، و ۷:۳۰ تا ۹:۳۰ صبح برای چی‌واوا).

      • در ارسال‌ها، arrivalWaypoint را روی مهدکودک و timeWindows را روی زمان تحویل موردنیاز (۹:۳۰ تا ۱۱:۳۰ صبح) تنظیم کنید.

      • برای همه سوار کردن‌ها و تحویل دادن‌ها، duration را روی ۵ دقیقه (300s) تنظیم کنید تا زمان سوار و پیاده کردن سگ‌ها درنظر گرفته شود.

      برای اطلاعات بیشتر درباره پنجره‌های زمانی، به پنجره‌های زمانی مراجعه کنید.

   2. برای اولویت دادن به مشتریان همیشگی، penaltyCost را برای سگ کوهستانی برنی و چی‌واوا روی 1000 و برای ژرمن شپرد روی 100 تنظیم می‌کنید. با تنظیم هزینه‌های جریمه، بهینه‌ساز می‌تواند از هرکدام از سگ‌ها صرف‌نظر کند، اما اگر محدودیت‌ها انجام همه سوار کردن‌ها را غیرممکن کند، ابتدا صرف‌نظر کردن از ژرمن شپرد (که جریمه کمتری دارد) را درنظر می‌گیرد.

   3. می‌توانید از فیلد label برای افزودن شناسه برای هر محموله استفاده کنید، مثلاً «سگ کوهستانی برن»، «چی‌واوا»، و «ژرمن شپرد». این کار می‌تواند به شما کمک کند محموله‌ها را در پاسخ شناسایی کنید.

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

3. تعریف وسایل نقلیه. در فیلد vehicles، پیامی Vehicle برای یک ون خود اضافه کنید که مرکز مهدکودک را به‌عنوان نقطه شروع و پایان، هزینه دستمزد راننده، و ساعات کاری ون نشان دهد.

   1. startWaypoint و endWaypoint را برای ون روی مکان‌های شروع و پایان روز تنظیم کنید، که همان مهدکودک نزدیک پارک میشن دولورس است.

   2. برای به‌حداقل رساندن هزینه‌های عملیاتی، باید محدودیت‌های هزینه کسب‌وکارتان را تعریف کنید. پارامتر هزینه costPerHour را روی 27 تنظیم کنید، که همان مبلغی است که به راننده برای رانندگی ون مهدکودک سگ‌ها پرداخت می‌کنید. برای اطلاعات بیشتر درباره پارامترهای هزینه، مدل هزینه را ببینید.

   3. برای اطمینان از اینکه بهینه‌ساز مسیری را در ساعات کاری ون ایجاد می‌کند، یک پنجره عملیاتی برای خودرو تعریف کنید. این پنجره محدودیت‌های زمانی شروع و پایان را برای مسیر تنظیم می‌کند. با تعریف کردن فقط یک نیمه از هر پنجره زمانی، به بهینه‌ساز انعطاف‌پذیری می‌دهید تا مسیر را دیرتر شروع کند یا زودتر به‌پایان برساند:

      • تنظیم startTime در startTimeWindows روی ساعت ۷ صبح یعنی راننده می‌تواند نوبت کاری‌اش را از ساعت ۷ صبح شروع کند. همچنین اگر سوار کردن زودهنگام در صبح وجود نداشته باشد، می‌تواند دیرتر شروع کند.

      • تنظیم endTime در endTimeWindows روی ظهر یعنی راننده باید نوبت کاری‌اش را تا ظهر تمام کند. همچنین می‌توانند به‌محض تکمیل آخرین تحویل، شیفت خود را پایان دهند.

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

   برای اطلاعات بیشتر درباره تعریف خودروها، خودرو را ببینید.

4. پنجره زمانی سراسری تنظیم کنید. پنجره زمانی جهانی نشان‌دهنده چارچوب زمانی‌ای است که طی آن ون می‌تواند درطول روز سوار و پیاده کردن را برای مهدکودک شما انجام دهد. برای این سناریو، globalStartTime را روی ۷ صبح و globalEndTime را روی ۷ عصر برای ۱۳ فوریه ۲۰۲۴ تنظیم کنید که نشان‌دهنده ساعت کاری مهد سگ شما است.

۳. ارسال درخواست

در زیر یک درخواست ساده curl براساس سناریو مهدکودک سگ‌ها آورده شده است که از روش مسدودسازی optimizeTours استفاده می‌کند.

قبل‌از ارسال درخواست، PROJECT_NUMBER_OR_ID را در کد نمونه با شناسه پروژه Google Cloud خودتان جایگزین کنید.

curl -X POST 'https://routeoptimization.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID:optimizeTours' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
--data @- << EOM
{
  "timeout": "2s",
  "model": {
    "shipments": [
      {
        "pickups": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.802395,
                  "longitude": -122.405822
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T08:00:00-08:00",
                "endTime": "2024-02-13T08:20:00-08:00"
              }
            ],
            "duration": "300s"
          }
        ],
        "deliveries": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.759719,
                  "longitude": -122.42798
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T09:30:00-08:00",
                "endTime": "2024-02-13T11:30:00-08:00"
              }
            ],
            "duration": "300s"
          }
        ],
        "label": "Bernese mountain dog",
        "penaltyCost": 1000
      },
      {
        "pickups": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.738067,
                  "longitude": -122.498593
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T07:30:00-08:00",
                "endTime": "2024-02-13T09:30:00-08:00"
              }
            ],
            "duration": "300s"
          }
        ],
        "deliveries": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.759719,
                  "longitude": -122.42798
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T09:30:00-08:00",
                "endTime": "2024-02-13T11:30:00-08:00"
              }
            ],
            "duration": "300s"
          }
        ],
        "label": "Chihuahua",
        "penaltyCost": 1000
      },
      {
        "pickups": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.78018,
                  "longitude": -122.51194
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T08:00:00-08:00",
                "endTime": "2024-02-13T08:20:00-08:00"
              }
            ],
            "duration": "300s"
          }
        ],
        "deliveries": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.759719,
                  "longitude": -122.42798
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T09:30:00-08:00",
                "endTime": "2024-02-13T11:30:00-08:00"
              }
            ],
            "duration": "300s"
          }
        ],
        "label": "German shepherd",
        "penaltyCost": 100
      }
    ],
    "vehicles": [
      {
        "startWaypoint": {
          "location": {
            "latLng": {
              "latitude": 37.759719,
              "longitude": -122.42798
            }
          }
        },
        "endWaypoint": {
          "location": {
            "latLng": {
              "latitude": 37.759719,
              "longitude": -122.42798
            }
          }
        },
        "costPerHour": 27,
        "startTimeWindows": [
          {
            "startTime": "2024-02-13T07:00:00-08:00"
          }
        ],
        "endTimeWindows": [
          {
            "endTime": "2024-02-13T12:00:00-08:00"
          }
        ]
      }
    ],
    "globalStartTime": "2024-02-13T07:00:00-08:00",
    "globalEndTime": "2024-02-13T19:00:00-08:00"
  }
}
EOM

پارامترهای درخواست استفاده‌شده در درخواست

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

بعدی

تفسیر پاسخarrow_forward