تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

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

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

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

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

السيناريو

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

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

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

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

استلِم كلب جبل البرنيز بالقرب من برج كويت.
يمكنك استلام كلب الشيواوا من حديقة South Sunset Playground Park.
أوصل الكلبَين إلى مركز رعاية الكلاب في "متنزّه ميشن دولوريس".

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

قبل البدء

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

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

ابدأ ببنية الطلب الأساسية، وهي كالتالي:
```
{
  "timeout": ...,
  "model": {
    "shipments": [...],
    "vehicles": [...],
    "globalStartTime": "...",
    "globalEndTime": "..."
  }
}
```
لمزيد من المعلومات حول البنية، يُرجى الاطّلاع على دليل المفاهيم الأساسية حول البنية الأساسية (ShipmentModel وShipment وVehicle).
حدِّد الشحنات. في الحقل shipments، أضِف رسالة Shipment لكل كلب يجب اصطحابه وإعادته في الصباح. هذا هو المكان الذي تحدد فيه كل موقع من المواقع المفضلة لمالك الكلب وأوقات وموقع مركز الرعاية النهارية وأوقات إنزال الكلاب.
1. لكل كلب، أنشئ VisitRequest لعمليات الاستلام وآخر لعمليات التسليم، والتي يُشار إليها في هذا السيناريو باسم التسليم في مركز الرعاية النهارية.
  - في عمليات الاستلام، اضبط arrivalWaypoint على موقع استلام الكلب (برج كويت لكلب جبل بيرنيز أو حديقة ساوث صن سيت بلاي غراوند لكلب الشيواوا) وtimeWindows على وقت الاستلام الذي يطلبه المالك (من 7:30 صباحًا إلى 9:30 صباحًا).
  - في عمليات التسليم، اضبط arrivalWaypoint على مركز الرعاية النهارية وtimeWindows على وقت التسليم المطلوب (من الساعة 9:30 صباحًا إلى الساعة 11:30 صباحًا).
  لمزيد من المعلومات حول النوافذ الزمنية، يُرجى الاطّلاع على النوافذ الزمنية.
2. يمكنك استخدام حقل label لإضافة معرّف لكل شحنة، مثل "كلب جبل بيرنيز" و "شيواوا". يمكن أن يساعدك ذلك في تحديد الشحنات في الردّ.
لمزيد من المعلومات حول تحديد الشحنات، يُرجى الاطّلاع على الشحنة.
تحديد المركبات: في حقل vehicles، أضِف رسالة Vehicle تتضمّن تفاصيل حول الحافلة الواحدة، مثل مركز الرعاية النهارية كنقطة البداية والنهاية، وتكلفة أجر السائق، وساعات عمل الحافلة.
1. اضبط startWaypoint وendWaypoint للشاحنة الصغيرة لتحديد موقعَي البدء والانتهاء لهذا اليوم، وهما مركز الرعاية النهارية بالقرب من "منتزه ميشن دولوريس".
2. لتقليل تكاليف التشغيل، يجب عليك تحديد قيود التكلفة لعملك. اضبط مَعلمة التكلفة costPerHour على 27، وهو المبلغ الذي تدفعه للسائق مقابل قيادة شاحنة مركز رعاية الكلاب. لمزيد من المعلومات عن مَعلمات التكلفة، اطّلِع على نموذج التكلفة.
  
  ملاحظة مهمة: التكاليف ضرورية لكي يعثر المحسِّن على أفضل مسار. وبدونها، يتعامل المحسِّن مع جميع الحلول على أنّها متساوية.
3. لضمان إنشاء أداة تحسين المسار مسارًا ضمن ساعات عمل الحافلة، حدِّد startTimeWindows ضمن النطاق المقبول لبدء السائق تشغيل الحافلة، وendTimeWindows ضمن النطاق المقبول لموعد عودة السائق إلى مركز الرعاية النهارية. لمزيد من المعلومات حول النوافذ الزمنية، يُرجى الاطّلاع على النوافذ الزمنية.
لمزيد من المعلومات حول تحديد المركبات، يُرجى الاطّلاع على المركبة.
اضبط نافذة زمنية عامة. تمثّل فترة الوقت العالمية الفترة الزمنية التي يمكن أن تنفّذ فيها الحافلة عمليات الاستلام والتسليم في مركز الرعاية النهارية على مدار اليوم. في هذا السيناريو، اضبط 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`). يمكنك اعتبارها المخطط الكامل للمشكلة التي عليك تحسينها.
`OptimizeToursRequest`	`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`.
`VisitRequest`	`timeWindows[]`	مصفوفة من العناصر (`TimeWindow`)	هذه السمة عبارة عن مصفوفة من العناصر التي تحدّد القيود الزمنية للاستلام أو التسليم. في هذا السيناريو، استخدِم هذه السمة لتحديد فترة الاستلام لكل كلب وفترة التسليم المقبولة في مركز الرعاية النهارية.
`Vehicle`	`startWaypoint[]`	كائن (`Waypoint`)	تمثّل هذه السمة الموقع الجغرافي الذي تبدأ منه رحلة المركبة، ويتم تحديدها باستخدام إحداثيات خط العرض وخط الطول أو رقم تعريف المكان. تُعلم هذه المَعلمة أداة التحسين بالمكان الذي يجب أن تبدأ فيه المركبة المسار. إذا لم تحدّد هذه النقطة على المسار، يختار المحسِّن إحدى عمليات الاستلام أو التسليم كموقع جغرافي للبدء. في سيناريو مركز رعاية الكلاب هذا، بما أنّ السائق يبدأ يومه في مركز الرعاية، استخدِم إحداثيات حديقة "ميشين دولوريس".
	`endWaypoint[]`	كائن (`Waypoint`)	هذه هي الوجهة النهائية لمسار المركبة، ويتم تحديدها باستخدام إحداثيات خطوط العرض والطول أو رقم تعريف المكان. تُعلم هذه المَعلمة المحسِّن بالمكان الذي يجب أن تنهي فيه المركبة المسار. إذا لم تحدّد هذه النقطة على المسار، سيختار المحسِّن إحدى عمليات الاستلام أو التسليم كنهاية للمسار. في سيناريو مركز رعاية الكلاب هذا، بما أنّ السائق يجب أن ينهي يومه في مركز الرعاية، استخدِم إحداثيات حديقة "ميشن دولوريس".
	`costPerHour`	الرقم	هذه هي التكلفة التي يتم تحمّلها مقابل كل ساعة يتم فيها استخدام المركبة، بغض النظر عمّا إذا كانت تتحرك أو متوقفة. في سيناريو مركز رعاية الكلاب هذا، استخدِم هذا النموذج لحساب الأجر بالساعة للسائق.
	`startTimeWindows[]`	مصفوفة من العناصر (`TimeWindow`)	هذه هي الفترة الزمنية المقبولة التي يمكن للسائق خلالها بدء قيادة الشاحنة الصغيرة لنقل الكلاب في الصباح.
	`endTimeWindows[]`	مصفوفة من العناصر (`TimeWindow`)	هذه هي الفترة الزمنية المقبولة للسائق لإنهاء قيادة الشاحنة والعودة إلى مركز رعاية الكلاب.

تفسير الردّ