إرسال أول طلب لتحسين المسار... باستخدام الكلاب

المطوّرون في المنطقة الاقتصادية الأوروبية

يوضّح لك هذا المستند كيفية إرسال طلبك الأول إلى Route Optimization API باستخدام سيناريو حالة استخدام واقعية.

لتبسيط الأمر، يستخدم المثال HTTP وJSON لتوضيح REST API. ومع ذلك، بالنسبة إلى بيئة التشغيل الفعلي، يُنصح بشكل عام باستخدام gRPC للاستفادة من مزايا الأداء التي يوفّرها. ومع ذلك، يتطلب gRPC بعض التثبيت. لمزيد من المعلومات، يُرجى الاطّلاع على مكتبات عملاء Route Optimization API.

السيناريو

خريطة لمدينة سان فرانسيسكو مع دبابيس لـ "برج كويت" و"منتزه ميشن دولوريس" و"منتزه ساوث سانسيت بلاي غراوند"

أنت تدير خدمة رعاية نهارية للكلاب من الساعة 7 صباحًا حتى الساعة 7 مساءً في القاهرة. هذا الصباح، تريد اصطحاب ثلاثة كلاب من مواقع مختلفة في المدينة وإحضارهم إلى مركز الرعاية النهارية الخاص بك.

كلب جبل بيرنيز والشيواوا من العملاء المنتظمين الذين حجزوا مواعيدهم الأسبوع الماضي. الراعي الألماني هو طلب جديد في اللحظة الأخيرة. تريد استيعاب الراعي الألماني إن أمكن، ولكن ليس على حساب عملائك المنتظمين.

لديك شاحنة واحدة للوظيفة، وتدفع للسائق 27 دولارًا في الساعة. يبدأ السائق والشاحنة اليوم في مركز الرعاية النهارية الخاص بك في الساعة 7 صباحًا ويجب أن يعودا من عمليات النقل الصباحية بحلول الظهر لقضاء استراحة الغداء.

اليوم هو 13 فبراير 2024. جميع الأوقات في هذا السيناريو هي بالتوقيت المحلي لمدينة سان فرانسيسكو، وهو توقيت المحيط الهادئ الرسمي (UTC-8) في فبراير. يؤدي السائق المهام التالية:

  • استلِم كلب جبل البرنيز بالقرب من برج كويت. طلب المالك نافذة استلام ضيقة بين الساعة 8 صباحًا و8:20 صباحًا.
  • استلِم كلب الشيواوا من حديقة South Sunset Playground Park. عرض المالك فترة استلام أكثر مرونة بين الساعة 7:30 صباحًا و9:30 صباحًا.
  • استلِم كلب الراعي الألماني من "لاندز إند". طلب المالك أيضًا فترة استلام ضيقة بين الساعة 8 صباحًا و8:20 صباحًا.
  • أريد توصيل الكلاب إلى مركز الرعاية النهارية في "متنزه ميشن دولوريس". تتطلب الحضانة التوصيل بين الساعة 9:30 صباحًا و11:30 صباحًا.

تستغرق كل زيارة لاستلام الكلب أو تسليمه 5 دقائق لتحميل الكلب أو إنزاله.

بما أنّ "لاندز إند" بعيدة عن "برج كويت" وتتعارض فترات الاستلام، لا يمكن للسائق تنفيذ عمليات الاستلام الثلاث. يجب أن يختار المحسِّن الكلب الذي يجب تخطّيه لتقليل التكلفة الإجمالية (أجور السائقين وأي غرامات تخطّي).

قبل البدء

لتشغيل الرمز في هذا السيناريو، عليك أولاً إكمال التعليمات الواردة في مقالة إعداد Route Optimization API.

1. اختيار منهج تحسين المسارات

تتضمّن واجهة Route Optimization API طرقًا متعدّدة يمكنك الاختيار من بينها استنادًا إلى مدى تعقيد مشكلة التحسين.

بما أنّ سيناريو مركز رعاية الكلاب هذا هو طلب صغير ومباشر، يمكنك استخدام طريقة حظر، مثل optimizeTours، والتي تقدّم نتائج سريعة للطلبات الصغيرة. لمزيد من المعلومات عن نقاط نهاية Route Optimization API، يُرجى الاطّلاع على مقالة اختيار نقطة نهاية.

استخدِم عنوان URL التالي لإرسال طلب HTTP POST إلى الطريقة optimizeTours:

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

عليك أيضًا ضبط إعدادات المهلة والموعد النهائي لتكون قصيرة لتقليل أي وقت انتظار غير ضروري. بالنسبة إلى سيناريو مركز رعاية الكلاب هذا، لا يحتاج المحسِّن إلى الكثير من الوقت للردّ على طلبك، لذا استخدِم الإعدادات التالية:

  • اضبط المَعلمة timeout على ثانيتَين.
  • اترك إعدادات الموعد النهائي على الإعدادات التلقائية، وهي 60 ثانية لطلبات REST.

2. إنشاء نص رسالة الطلب

بعد اختيار طريقة الحظر optimizeTours وتحديد إعدادات المهلة والموعد النهائي، تتمثل الخطوة التالية في إنشاء نص رسالة الطلب.

في هذا السيناريو، يكون الطلب عبارة عن رسالة OptimizeToursRequest مُرمَّزة بتنسيق JSON في واجهة برمجة التطبيقات REST API.

لإنشاء رسالة الطلب، اتّبِع الخطوات التالية:

  1. ابدأ ببنية الطلب الأساسية، وهي كالتالي:

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

    لمزيد من المعلومات حول البنية، يُرجى الاطّلاع على دليل المفاهيم الأساسية حول البنية الأساسية (ShipmentModel وShipment وVehicle).

  2. حدِّد الشحنات. في حقل shipments، أضِف رسالة Shipment لكل كلب يجب اصطحابه وإعادته في الصباح. هذا هو المكان الذي تحدد فيه كل موقع من المواقع المفضلة لمالك الكلب وأوقات وموقع مركز الرعاية النهارية وأوقات إنزال الكلاب.

    1. لكل كلب، أنشئ VisitRequest لعمليات الاستلام وآخر لعمليات التسليم، والتي يُشار إليها في هذا السيناريو باسم التسليم في مركز الرعاية النهارية.

      • في عمليات الاستلام، اضبط arrivalWaypoint على موقع استلام الكلب (برج كويت لكلب جبل بيرنيز، أو حديقة ملعب ساوث صن سيت لكلب الشيواوا، أو لاندز إند لكلب الراعي الألماني). اضبط timeWindows على وقت الاستلام الذي يطلبه المالك (من الساعة 8 صباحًا إلى 8:20 صباحًا لكلب جبل بيرنيز والراعي الألماني، ومن الساعة 7:30 صباحًا إلى 9:30 صباحًا لكلب الشيواوا).

      • في عمليات التسليم، اضبط arrivalWaypoint على مركز الرعاية النهارية وtimeWindows على وقت التسليم المطلوب (من 9:30 صباحًا إلى 11:30 صباحًا).

      • بالنسبة إلى جميع عمليات الاستلام والتسليم، اضبط duration على 5 دقائق (300s) لمراعاة وقت تحميل الكلاب وتفريغها.

      لمزيد من المعلومات حول النوافذ الزمنية، يُرجى الاطّلاع على النوافذ الزمنية.

    2. لإعطاء الأولوية للعملاء المنتظمين، يمكنك ضبط السمة penaltyCost على 1000 لكل من كلب جبل بيرنيز والشيواوا، وعلى 100 لكلب الراعي الألماني. بعد ضبط تكاليف الجزاءات، يمكن للمحسِّن تخطّي أي من الكلاب، ولكنه يضع في اعتباره تخطّي كلب الراعي الألماني (الذي له جزاء أقل) أولاً إذا كانت القيود تجعل من المستحيل تنفيذ جميع عمليات الاستلام.

    3. يمكنك استخدام حقل label لإضافة معرّف لكل شحنة، مثل "كلب جبل بيرنيز" و"شيواوا" و "كلب الراعي الألماني". يمكن أن يساعدك ذلك في تحديد الشحنات في الردّ.

    لمزيد من المعلومات حول تحديد الشحنات، يُرجى الاطّلاع على الشحنة.

  3. تحديد المركبات: في حقل vehicles، أضِف رسالة Vehicle لشاحنتك الواحدة مع مركز الرعاية النهارية كنقطة بداية ونهاية، وتكلفة أجر السائق، وساعات العمل للشاحنة.

    1. اضبط startWaypoint وendWaypoint للشاحنة على موقعي البدء والانتهاء لليوم، وهو مركز الرعاية النهارية بالقرب من حديقة ميشن دولوريس.

    2. لتقليل تكاليف التشغيل، يجب عليك تحديد قيود التكلفة لعملك. اضبط مَعلمة التكلفة costPerHour على 27، وهي المبلغ الذي تدفعه للسائق مقابل قيادة شاحنة نقل الكلاب إلى مركز الرعاية النهارية. لمزيد من المعلومات عن مَعلمات التكلفة، يُرجى الاطّلاع على نموذج التكلفة.

    3. لضمان أن ينشئ المحسِّن مسارًا ضمن ساعات عمل الشاحنة، حدِّد فترة عمل للمركبة. تحدّد هذه النافذة القيود الزمنية لبدء المسار وانتهائه. من خلال تحديد نصف واحد فقط من كل نافذة زمنية، ستمنح المحسِّن المرونة لبدء المسار في وقت لاحق أو إنهائه في وقت مبكر:

      • يعني ضبط startTime في startTimeWindows على الساعة 7 صباحًا أنّ السائق يمكنه بدء نوبة عمله في الساعة 7 صباحًا، ويمكنه أيضًا البدء في وقت لاحق إذا لم تكن هناك عمليات استلام في الصباح الباكر.

      • يعني ضبط endTime في endTimeWindows على الظهر أنّه يجب على السائق إنهاء نوبة عمله بحلول الظهر. ويمكنهم أيضًا إنهاء نوبة عملهم بمجرد إكمال عملية التسليم الأخيرة.

      يؤدي حذف النصف الآخر من النوافذ إلى تقليل وقت انتظار السائق وأوقات الالتفاف. لمزيد من المعلومات حول النوافذ الزمنية، يُرجى الاطّلاع على النوافذ الزمنية.

    لمزيد من المعلومات حول تحديد المركبات، يُرجى الاطّلاع على المركبة.

  4. اضبط نافذة زمنية عامة. تمثّل النافذة الزمنية العامة الإطار الزمني الذي يمكن فيه للشاحنة إجراء عمليات الاستلام والتسليم لمركز الرعاية النهارية على مدار اليوم. في هذا السيناريو، اضبط globalStartTime على الساعة 7 صباحًا وglobalEndTime على الساعة 7 مساءً في 13 فبراير 2024، ما يمثّل ساعات عمل مركز رعاية الكلاب.

3- إرسال الطلب

في ما يلي طلب 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

مَعلمات الطلب المستخدَمة في الطلب

يوضّح الجدول التالي مَعلمات الطلب المستخدَمة في نص الطلب في السيناريو النموذجي. يمكنك فلترة المحتوى حسب العنصر الرئيسي أو البحث النصي.

أحد الوالدين المَعلمة نوع الموقع الوصف
OptimizeToursRequest model كائن (ShipmentModel) هذا هو جوهر طلبك. وهو عنصر واحد تحدّد فيه المشكلة بأكملها، بما في ذلك جميع الكلاب التي تحتاج إلى اصطحابها وإنزالها (shipments) والشاحنة في أسطولك (vehicles). يمكنك اعتباره المخطط الكامل للمشكلة التي تحتاج إلى تحسينها.
timeout المدة تحدّد هذه المَعلمة الحد الأقصى للوقت الذي يعمل فيه الخادم على طلب قبل عرض استجابة. استخدِم هذه المَعلمة لتقليل وقت الانتظار. بالنسبة إلى الطلبات الصغيرة والسريعة، مثل سيناريو مركز رعاية الكلاب، اضبط هذه القيمة على ثانيتين.
ShipmentModel shipments[] مصفوفة من العناصر (Shipment) هذه مصفوفة من العناصر يمثّل كل عنصر فيها كلبًا يجب اصطحابه أو توصيله.
vehicles[] مصفوفة من العناصر (Vehicle) هذه مصفوفة من العناصر يحدّد فيها كل عنصر مركبة في أسطولك. وهي المكان الذي تصف فيه مواردك، مثل الشاحنة التي تُجري عمليات الاستلام والتسليم. يجب تحديد مركبة واحدة على الأقل للحصول على مسار محسَّن.
globalStartTime الطابع الزمني هذا هو أقرب وقت ممكن لحدوث أي حدث في نموذجك بالكامل. تضيّق هذه المَعلمة نطاق مشكلة التحسين في الوقت المناسب، وهو أمر بالغ الأهمية لإجراء حسابات دقيقة لحركة المرور والمسارات. في سيناريو مركز رعاية الكلاب هذا، اضبط هذا الحقل على أقرب وقت يمكن للسائق فيه تشغيل الشاحنة في اليوم، وهو الساعة 7 صباحًا في 13 فبراير 2024.
globalEndTime الطابع الزمني هذا هو آخر وقت ممكن لحدوث أي حدث في النموذج بأكمله. بالنسبة إلى سيناريو مركز رعاية الكلاب، اضبط هذا الخيار على الوقت الذي من المتوقع أن تنتهي فيه عملية الشاحنة، وهو الساعة 7 مساءً في 13 فبراير 2024.
Shipment pickups[] مصفوفة من العناصر (VisitRequest) هذه قائمة بجميع خيارات الاستلام الممكنة للشحنة. يختار المحسِّن أفضل طريقة لحلّ مشكلتك. في سيناريو مركز رعاية الكلاب هذا، أدرِج المواقع الجغرافية لاستلام الكلاب والفترات الزمنية التي حدّدها كل مالك لكل كلب.
deliveries[] مصفوفة من العناصر (VisitRequest) هذه قائمة بجميع خيارات التسليم الممكنة للشحنة. يختار المحسِّن أفضل طريقة لحلّ مشكلتك. بالنسبة إلى سيناريو مركز رعاية الكلاب هذا، أدرِج الموقع الجغرافي للمركز والوقت الذي يحتاج فيه السائق إلى العودة لتناول الغداء لكل كلب.
label سلسلة هذا معرّف لشحنة معيّنة في طلبك. يمكنك تحديد التصنيفات في طلبك لتسهيل قراءة الردّ. في سيناريو مركز رعاية الكلاب هذا، استخدِم سلسلة وصفية مثل "تشيواوا" أو "كلب جبل بيرنيز" أو اسم الكلب لمطابقة الحلّ مع الإدخال عند تلقّي الردّ من واجهة برمجة التطبيقات.
penaltyCost مزدوج هذه هي تكلفة الغرامة التي يتم تحمّلها إذا تخطّى المحسِّن هذه الشحنة. تكون الشحنات إلزامية تلقائيًا، وتمنح أداة التحسين الأولوية لتقليل الشحنات الإلزامية التي يتم تخطّيها، ولا تتخطّاها إلا في حال عدم توفّر خيار آخر. يتيح ضبط تكلفة الغرامة لأداة التحسين تخطّي شحنة إذا كان تنفيذها غير ممكن أو مكلفًا للغاية، كما يتيح لك تحديد الأولويات بين الشحنات. في هذا السيناريو، يمكنك ضبط تكلفة جزاء أعلى (1000) لعملائك المنتظمين (كلب جبل بيرنيز وشيواوا) وتكلفة جزاء أقل (100) لطلب الراعي الألماني في اللحظة الأخيرة. يؤدي ذلك إلى توجيه المحسِّن إلى إعطاء الأولوية للعملاء العاديين، لذا يضع في اعتباره تخطّي كلب الراعي الألماني أولاً عندما لا يتمكّن من تنفيذ جميع عمليات الاستلام.
VisitRequest arrivalWaypoint كائن (Waypoint) هذا هو الموقع الجغرافي لزيارة معيّنة على المسار. ويمكنك تحديد ذلك باستخدام إحداثيات خطوط العرض والطول أو رقم تعريف المكان أو العنوان. في سيناريو مركز رعاية الكلاب هذا، اضبط هذه السمة على الموقع الجغرافي الذي قدّمه المالك لـ pickups وعلى عنوان مركز الرعاية لـ deliveries.
timeWindows[] مصفوفة من العناصر (TimeWindow) هذه مصفوفة من العناصر التي تحدّد القيود الزمنية لعملية الاستلام أو التسليم. في هذا السيناريو، استخدِم هذه السمة لتحديد الفترة الزمنية المخصّصة لاصطحاب كل كلب والفترة الزمنية المقبولة لتوصيل الكلاب إلى مركز الرعاية النهارية.
duration المدة تحدّد هذه المَعلمة مدة الزيارة (مثل وقت التحميل أو التفريغ). في هذا السيناريو، يمكنك ضبط فترة احتياطية مدتها 5 دقائق (300s) لجميع عمليات الاستلام والتسليم لمراعاة تحميل السائق للكلاب وتفريغها.
Vehicle startWaypoint كائن (Waypoint) هذا هو الموقع الجغرافي لبداية مسار المركبة، ويتم تحديده باستخدام إحداثيات خطوط العرض والطول أو رقم تعريف المكان. تُعلم هذه المَعلمة المُحسِّن بالمكان الذي يجب أن تبدأ منه المركبة المسار. إذا لم تحدّد هذه النقطة على المسار، يختار المحسِّن إحدى عمليات الاستلام أو التسليم كموقع جغرافي للبدء. في سيناريو مركز رعاية الكلاب هذا، بما أنّ السائق يبدأ يومه في مركز الرعاية، استخدِم إحداثيات حديقة "ميشين دولوريس".
endWaypoint كائن (Waypoint) هذه هي الوجهة النهائية لمسار المركبة، ويتم تحديدها باستخدام إحداثيات خطوط العرض والطول أو رقم تعريف المكان. تُعلم هذه المَعلمة المحسِّن بالمكان الذي يجب أن تنهي فيه المركبة المسار. إذا لم تحدّد هذه النقطة على المسار، سيختار المحسِّن إحدى عمليات الاستلام أو التسليم كنهاية للمسار. في سيناريو مركز رعاية الكلاب هذا، بما أنّ السائق يجب أن ينهي يومه في مركز الرعاية، استخدِم إحداثيات حديقة "ميشن دولوريس".
costPerHour الرقم هذه هي التكلفة التي يتم تحمّلها مقابل كل ساعة يتم فيها استخدام المركبة، بغض النظر عمّا إذا كانت تتحرك أو متوقفة. في سيناريو مركز رعاية الكلاب هذا، استخدِم هذا النموذج لحساب الأجر بالساعة للسائق.
startTimeWindows[] مصفوفة من العناصر (TimeWindow) هذه هي الفترة الزمنية المقبولة التي يمكن للسائق أن يبدأ فيها مناوبته. بالنسبة إلى سيناريو مركز رعاية الكلاب هذا، حدِّد السمة startTime على أنّها الساعة 7 صباحًا ولكن احذف السمة endTime. يتيح ذلك لأداة التحسين تأخير بدء الوردية إذا كان موعد أول عملية استلام في وقت متأخر من الصباح. يُرجى العِلم أنّه حتى في حال عدم تقديم endTime لـ startTimeWindows، يكون وقت البدء مرتبطًا ضمنيًا بـ endTimeWindows. يجب أن تبدأ المركبة المسار قبل انتهائه.
endTimeWindows[] مصفوفة من العناصر (TimeWindow) هذه هي الفترة الزمنية المقبولة للسائق لإنهاء المسار. بالنسبة إلى سيناريو مركز رعاية الكلاب هذا، حدِّد endTime على أنّه الظهر ولكن احذف startTime. يتيح ذلك للسائق العودة إلى مركز الرعاية النهارية مباشرةً بعد آخر عملية توصيل.

التالي

تفسير الردّ