تقديم طلبك الأول لتحسين المسار

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

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

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

السيناريو

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

تدير خدمة رعاية نهارية للكلاب من الساعة 7:00 صباحًا حتى الساعة 7:00 مساءً في القاهرة. عليك هذا الصباح اصطحاب كلبَين من موقعَين مختلفَين في المدينة. حدّد لك مالكا الكلاب فترة استلام بين الساعة 7:30 صباحًا و9:30 صباحًا.

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

اليوم هو 13 فبراير 2024، ولديك المهام التالية:

  • التقِ بكلب جبل البرنيز بالقرب من "برج كويت".
  • يمكنك استلام كلب الشيواوا من متنزه "ساوث صنست بلايغراوند".
  • اصطحب الكلبَين إلى مركز رعاية الكلاب في "متنزّه ميشن دولوريس".

عليك تحديد مسار يقلّل الوقت الذي تقضيه الكلاب في الشاحنة، مع استيفاء متطلبات الاستلام والتسليم.

قبل البدء

لتشغيل الرمز البرمجي في سيناريو المثال هذا، عليك أولاً إكمال التعليمات الواردة في إعداد 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 لعمليات الاستلام وVisitRequest أخرى لعمليات التسليم، والتي يُشار إليها في هذا السيناريو باسم عمليات التسليم في مركز الرعاية النهارية.

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

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

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

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

    لمزيد من المعلومات حول تحديد الشحنات، راجِع مقالة الشحنة.

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

    1. اضبط startWaypoint وendWaypoint على الموقعَين الجغرافيَين الذي ستبدأ منهما وتنتهي فيهما رحلة الحافلة في اليوم، أي مركز الرعاية النهارية بالقرب من Mission Dolores Park.

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

    3. لضمان إنشاء أداة التحسين مسارًا ضمن ساعات عمل الحافلة، حدِّد startTimeWindows للنطاق المقبول لبدء السائق تشغيل الحافلة، وendTimeWindows للنطاق المقبول لموعد عودة السائق إلى مركز الرعاية النهارية. لمزيد من المعلومات حول الفترات الزمنية، يُرجى الاطّلاع على الفترات الزمنية.

  4. ضبط فترة زمنية عالمية تمثّل فترة الوقت العالمية الفترة الزمنية التي يمكن أن تنفّذ فيها الحافلة عمليات الاستلام والتسليم في مركز الرعاية النهارية على مدار اليوم. في هذه الحالة، اضبط globalStartTime على الساعة 7:00 صباحًا وglobalEndTime على الساعة 7:00 مساءً ليوم 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-13T07:30:00Z",
                "endTime": "2024-02-13T09:30:00Z"
              }
            ]
          }
        ],
        "deliveries": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.760202,
                  "longitude": -122.426796
                }
              }
            },
            "timeWindow": [
              {
                "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
                }
              }
            },
            "timeWindow": [
              {
                "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

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

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

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

التالي

تفسير الردّ