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

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

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

سناریو

شما یک سرویس مهدکودک سگ را از ساعت ۷:۰۰ صبح تا ۷:۰۰ عصر در سان فرانسیسکو اداره می‌کنید. امروز صبح، باید دو سگ را از مکان‌های مختلفی در شهر تحویل بگیرید. هر دو مالک سگ بازه زمانی تحویل را بین ۷:۳۰ صبح و ۹:۳۰ صبح به شما دادند.

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

امروز ۱۳ فوریه ۲۰۲۴ است و راننده تکالیف زیر را دارد:

• سگ کوهستانی بِرنِس را در نزدیکی برج کویت تحویل بگیرید.
• سگ شی‌واوا را در پارک زمین بازی South Sunset بردارید.
• هر دو سگ را در مرکز مراقبت روزانه سگ‌ها در پارک Mission Dolores پیاده کنید.

به مسیری نیاز دارید که زمان حضور سگ‌ها در ون را به حداقل برساند و درعین‌حال الزامات سوار کردن و پیاده کردن را برآورده کند.

قبل‌از شروع

برای اجرای کد در این سناریو نمونه، ابتدا باید دستورالعمل‌های راه‌اندازی «میانای برنامه‌سازی کاربردی بهینه‌سازی مسیر» را تکمیل کنید.

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

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

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

برای درخواست 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 را روی زمان تحویل موردنیاز (۹:۳۰ صبح تا ۱۱:۳۰ صبح) تنظیم کنید.

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

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

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

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

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

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

   3. برای اطمینان از اینکه بهینه‌ساز مسیری را در ساعات کاری ون ایجاد می‌کند، startTimeWindows را روی محدوده قابل‌قبول برای شروع رانندگی ون توسط راننده و 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-13T07:30:00Z",
                "endTime": "2024-02-13T09:30:00Z"
              }
            ]
          }
        ],
        "deliveries": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.760202,
                  "longitude": -122.426796
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T09:30:00Z",
                "endTime": "2024-02-13T11:30:00Z"
              }
            ]
          }
        ],
        "label": "Bernese mountain dog"
      },
      {
        "pickups": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.738067,
                  "longitude": -122.498593
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T07:30:00Z",
                "endTime": "2024-02-13T09:30:00Z"
              }
            ]
          }
        ],
        "deliveries": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.760202,
                  "longitude": -122.426796
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T09:30:00Z",
                "endTime": "2024-02-13T11:30:00Z"
              }
            ]
          }
        ],
        "label": "Chihuahua"
      }
    ],
    "vehicles": [
      {
        "startWaypoint": {
          "location": {
            "latLng": {
              "latitude": 37.760202,
              "longitude": -122.426796
            }
          }
        },
        "endWaypoint": {
          "location": {
            "latLng": {
              "latitude": 37.760202,
              "longitude": -122.426796
            }
          }
        },
        "costPerHour": 27,
        "startTimeWindows": [
          {
            "startTime": "2024-02-13T07:00:00Z",
            "endTime": "2024-02-13T07:15:00Z"
          }
        ],
        "endTimeWindows": [
          {
            "startTime": "2024-02-13T11:45:00Z",
            "endTime": "2024-02-13T12:00:00Z"
          }
        ]
      }
    ],
    "globalStartTime": "2024-02-13T07:00:00Z",
    "globalEndTime": "2024-02-13T19:00:00Z"
  }
}
EOM

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

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

بعدی

تفسیر پاسخarrow_forward