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

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

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

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

السيناريو

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

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

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

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

  • اصطحاب كلب جبل البرنيز بالقرب من برج كويت
  • اصطحاب كلب الشيواوا في متنزّه South Sunset Playground
  • إيصال الكلبَين إلى مركز رعاية الكلاب في متنزّه Mission Dolores

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

قبل البدء

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

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

  1. ابدأ بهيكل الطلب الأساسي، وهو كما يلي:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  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
                }
              }
            },
            "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

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

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

أحد الوالدين المَعلمة نوع الموقع الوصف
OptimizeToursRequest model كائن (ShipmentModel) هذا هو جوهر طلبك. وهو كائن واحد تحدِّد فيه مشكلتك بالكامل، بما في ذلك جميع الكلاب التي عليك اصطحابها وإيصالها (shipments) والشاحنة في أسطولك (vehicles). يمكنك اعتباره المخطط الكامل للمشكلة التي عليك تحسينها.
timeout المدة تحدِّد هذه المَعلمة الحد الأقصى للوقت الذي يعمل فيه الخادم على طلب قبل عرض ردّ. استخدِم هذه المَعلمة لتقليل وقت الانتظار. بالنسبة إلى الطلبات الصغيرة والسريعة، مثل سيناريو رعاية الكلاب هذا، اضبط هذه القيمة على 2s.
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.
endWaypoint[] كائن (Waypoint) هذه هي الوجهة النهائية لمسار المركبة، ويتم تحديدها باستخدام إحداثيات خطوط الطول والعرض أو رقم تعريف مكان. تُعلم هذه المَعلمة أداة التحسين بالمكان الذي يجب أن تنتهي فيه المركبة من المسار. إذا لم تحدِّد نقطة على المسار هذه، تختار أداة التحسين إحدى عمليات الاصطحاب أو الإيصال كنهاية للمسار. بالنسبة إلى سيناريو رعاية الكلاب هذا، بما أنّ السائق يجب أن ينهي اليوم في مركز الرعاية، استخدِم إحداثيات متنزّه Mission Dolores.
costPerHour الرقم هذه هي التكلفة المتكبَّدة لكل ساعة يتم فيها استخدام مركبة، بغض النظر عمّا إذا كانت تتحرّك أو متوقفة. بالنسبة إلى سيناريو رعاية الكلاب هذا، استخدِم هذه المَعلمة لنمذجة الأجر بالساعة للسائق.
startTimeWindows[] مصفوفة من الكائنات (TimeWindow) هذه هي الفترة المقبولة لبدء السائق قيادة الشاحنة لعمليات اصطحاب الكلاب الصباحية.
endTimeWindows[] مصفوفة من الكائنات (TimeWindow) هذه هي الفترة المقبولة لإنهاء السائق قيادة الشاحنة وركنها مرة أخرى في مركز رعاية الكلاب.

التالي

تفسير الردّ