تفسير ردّ من واجهة برمجة التطبيقات Route Optimization API... باستخدام الكلاب

بعد إرسال الطلب في تقديم طلبك الأول، يعرض المحسِّن OptimizeToursResponse. هذا الردّ هو خطة المسار التي يجب أن يتّبعها السائق. يوضّح لك هذا الدليل كيفية قراءته.

ملخّص خطة المسار

بالنسبة إلى سيناريو رعاية الكلاب، يخصّص المحسِّن كلب جبل البرنيز وكلب الشيواوا لشاحنتك ويتخطّى كلب الراعي الألماني. خطة مسار السائق هي كما يلي:

• تبدأ نوبة العمل في الساعة 7:55 صباحًا في مركز رعاية الأطفال.
• اصطحب كلب جبل البرنيز بالقرب من برج كويت في الساعة 8:20 صباحًا.
• اصطحب كلب الشيواوا من حديقة "ساوث سانسيت بلاي غراوند" في الساعة 8:58 صباحًا.
• العودة إلى مركز الرعاية النهارية في الساعة 9:24 صباحًا، والانتظار حتى تفتح نافذة التسليم في الساعة 9:30 صباحًا.
• أريد توصيل كلب جبل البرنيز عند الساعة 9:30 صباحًا.
• يجب توصيل كلب الشيواوا عند الساعة 9:35 صباحًا.
• تنتهي نوبة العمل في الساعة 9:40 صباحًا.

تبلغ تكلفة خطة المسار 147.22 دولارًا، بما في ذلك غرامة قدرها 100 دولار مقابل تخطي الراعي الألماني.

للتحقّق من نتائجك، قارِن ردّك بالردّ الكامل في المثال. قد تختلف نتائجك قليلاً لأن مدة الرحلة والمسافات تعتمد على بيانات الطريق الحالية.

{
  "routes": [
    {
      "vehicleStartTime": "2024-02-13T15:55:04Z",
      "vehicleEndTime": "2024-02-13T17:40:00Z",
      "visits": [
        {
          "isPickup": true,
          "startTime": "2024-02-13T16:20:00Z",
          "detour": "0s",
          "shipmentLabel": "Bernese mountain dog",
          "visitType": "PICKUP_SHIPMENT"
        },
        {
          "shipmentIndex": 1,
          "isPickup": true,
          "startTime": "2024-02-13T16:58:12Z",
          "detour": "2600s",
          "shipmentLabel": "Chihuahua",
          "visitType": "PICKUP_SHIPMENT"
        },
        {
          "startTime": "2024-02-13T17:30:00Z",
          "detour": "2297s",
          "shipmentLabel": "Bernese mountain dog",
          "visitType": "DELIVER_SHIPMENT"
        },
        {
          "shipmentIndex": 1,
          "startTime": "2024-02-13T17:35:00Z",
          "detour": "656s",
          "shipmentLabel": "Chihuahua",
          "visitType": "DELIVER_SHIPMENT"
        }
      ],
      "transitions": [
        {
          "travelDuration": "1496s",
          "travelDistanceMeters": 7082,
          "waitDuration": "0s",
          "totalDuration": "1496s",
          "startTime": "2024-02-13T15:55:04Z"
        },
        {
          "travelDuration": "1992s",
          "travelDistanceMeters": 16589,
          "waitDuration": "0s",
          "totalDuration": "1992s",
          "startTime": "2024-02-13T16:25:00Z"
        },
        {
          "travelDuration": "1252s",
          "travelDistanceMeters": 7860,
          "waitDuration": "356s",
          "totalDuration": "1608s",
          "startTime": "2024-02-13T17:03:12Z"
        },
        {
          "travelDuration": "0s",
          "waitDuration": "0s",
          "totalDuration": "0s",
          "startTime": "2024-02-13T17:35:00Z"
        },
        {
          "travelDuration": "0s",
          "waitDuration": "0s",
          "totalDuration": "0s",
          "startTime": "2024-02-13T17:40:00Z"
        }
      ],
      "metrics": {
        "performedShipmentCount": 2,
        "travelDuration": "4740s",
        "waitDuration": "356s",
        "delayDuration": "0s",
        "breakDuration": "0s",
        "visitDuration": "1200s",
        "totalDuration": "6296s",
        "travelDistanceMeters": 31531,
        "performedShipmentPenaltyCostSum": 2000
      },
      "routeCosts": {
        "model.vehicles.cost_per_hour": 47.22
      },
      "routeTotalCost": 47.22,
      "vehicleFullness": {
        "maxFullness": 0.3497777777777778,
        "activeSpan": 0.3497777777777778
      }
    }
  ],
  "skippedShipments": [
    {
      "index": 2,
      "label": "German shepherd",
      "penaltyCost": 100
    }
  ],
  "metrics": {
    "aggregatedRouteMetrics": {
      "performedShipmentCount": 2,
      "travelDuration": "4740s",
      "waitDuration": "356s",
      "delayDuration": "0s",
      "breakDuration": "0s",
      "visitDuration": "1200s",
      "totalDuration": "6296s",
      "travelDistanceMeters": 31531,
      "performedShipmentPenaltyCostSum": 2000
    },
    "usedVehicleCount": 1,
    "earliestVehicleStartTime": "2024-02-13T15:55:04Z",
    "latestVehicleEndTime": "2024-02-13T17:40:00Z",
    "totalCost": 147.22,
    "costs": {
      "model.vehicles.cost_per_hour": 47.22,
      "model.shipments.penalty_cost": 100
    }
  }
}
    

بنية الردّ

يحتوي OptimizeToursResponse على مكوّنَين رئيسيَّين:

• ‫routes: خطة المسار لكل مركبة في أسطولك، بما في ذلك ترتيب وأوقات كل عملية استلام وتسليم لديك شاحنة واحدة، لذا هناك خطة مسار واحدة.
• ‫metrics: ملخّص لخطة المسار بالكامل، بما في ذلك إجمالي التكلفة والمدة والمسافة

بما أنّ المحسِّن يتخطّى كلب الراعي الألماني، تتضمّن الاستجابة أيضًا skippedShipments.

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

ما هي المركبة التي تسلك أي مسار؟

تنشئ أداة التحسين خطة مسار (مصفوفة routes) تتوافق مع ترتيب vehicles في طلبك.

يحدّد الحقل vehicleIndex كل مركبة استنادًا إلى موضعها الذي يبدأ من الصفر، وهو 0 لشاحنتك. يحدّد الحقلان vehicleStartTime وvehicleEndTime للسائق وقت بدء نوبة عمله وانتهائها.

تعرض واجهة برمجة التطبيقات Route Optimization API الطوابع الزمنية بالتوقيت العالمي المنسق (UTC)، والتي يتم تمييزها باللاحقة Z، بغض النظر عن الإزاحة في طلبك. للحصول على توقيت سان فرانسيسكو، اطرح 8 ساعات. بالنسبة إلى شاحنتك، تبدأ المناوبة من الساعة 7:55 صباحًا إلى الساعة 9:40 صباحًا، كما هو موضّح في عينة التعليمات البرمجية التالية.

{
"routes": [
    {
    // "vehicleIndex": 0, // Omitted in actual JSON response because it's 0
    "vehicleStartTime": "2024-02-13T15:55:04Z",
    "vehicleEndTime": "2024-02-13T17:40:00Z",
    ...
    }
  ]
  ...
}

ما هو ترتيب الاستلام والتسليم؟

ضمن كل مسار، تحتوي مصفوفة visits على كل عملية استلام وتسليم للمركبة المحدّدة بترتيب زمني.

shipmentIndex لكل زيارة هو موضع الشحنة المستند إلى الصفر في طلبك: 0 هو كلب جبل بيرنيز، و1 هو كلب تشيواوا. يعرض الحقل shipmentLabel التصنيف الذي حدّدته لكل شحنة.

للتمييز بين الاستلام والتسليم، يمكنك الاطّلاع على الحقلَين visitType أو isPickup:

• visitType: يحدّد إجراء الزيارة بشكل صريح.
  • استلام الطلب: visitType = "PICKUP_SHIPMENT"
  • التسليم: visitType = "DELIVER_SHIPMENT"
• isPickup: حقل مساعِد للقيم المنطقية.
  • استلام الطلب: isPickup = true
  • التسليم: isPickup = false (تم حذفه في JSON)

لتحديد التسلسل الدقيق للأحداث ووقت الوصول المتوقّع إلى كل موقع جغرافي، يُرجى قراءة مصفوفة visits بالترتيب. يوضّح الجدول التالي إجراء خطة المسار استنادًا إلى ترتيب وقيم الحقول shipmentIndex وisPickup أو visitType وstartTime.

يوضّح نموذج الرمز البرمجي التالي كيف يوفّر الردّ هذا التسلسل:

{
  "routes": [
    {
      "visits": [
        {
          // "shipmentIndex": 0, // Omitted in actual JSON response because it's 0
          "isPickup": true,
          "startTime": "2024-02-13T16:20:00Z",
          "shipmentLabel": "Bernese mountain dog",
          "visitType": "PICKUP_SHIPMENT"
        },
        {
          "shipmentIndex": 1,
          "isPickup": true,
          "startTime": "2024-02-13T16:58:12Z",
          "shipmentLabel": "Chihuahua",
          "visitType": "PICKUP_SHIPMENT"
        },
        {
          // "shipmentIndex": 0, // Omitted in actual JSON response because it's 0
          // "isPickup": false, // Omitted in actual JSON response because it's false
          "startTime": "2024-02-13T17:30:00Z",
          "shipmentLabel": "Bernese mountain dog",
          "visitType": "DELIVER_SHIPMENT"
        },
        {
          "shipmentIndex": 1,
          // "isPickup": false, // Omitted in actual JSON response because it's false
          "startTime": "2024-02-13T17:35:00Z",
          "shipmentLabel": "Chihuahua",
          "visitType": "DELIVER_SHIPMENT"
        }
      ]
    }
  ]
}

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

ماذا يحدث بين الزيارات؟

ضمن كل مسار، تعرض مصفوفة transitions تفاصيل التنقّل بين الزيارات. على الرغم من أنّ visits وtransitions هما قائمتان منفصلتان، إلا أنّهما تتداخلان في الوقت، على النحو التالي:

1. ‫transitions[0] (القيادة من نقطة البداية إلى الزيارة الأولى)
2. ‫visits[0] (الزيارة الأولى)
3. transitions[1] (القيادة من الزيارة الأولى إلى الزيارة الثانية)
4. ‫visits[1] (الزيارة الثانية)
5. ...
6. ‫visits[N-1] (الزيارة الأخيرة، حيث يمثّل N إجمالي عدد الزيارات)
7. ‫transitions[N] (القيادة من آخر زيارة إلى النهاية)

يمكنك تتبُّع المخطط الزمني للمسار من خلال الاطّلاع على الحقل startTime في كلتا المصفوفتَين. startTime الانتقال هو الوقت الذي يبدأ فيه السائق رحلته، وstartTime الزيارة هو الوقت الذي يبدأ فيه السائق عملية الاستلام أو التسليم.

يعرض كل انتقال وقت القيادة والمسافة المتوقّعة بين المواقع الجغرافية. يعرض الجدول التالي كلاً من حقلَي transitions وvisits لإجراءات المسار الزمني لسيناريو مركز رعاية الكلاب.

توضّح عيّنة التعليمات البرمجية التالية كيف يوفّر الردّ هذا التسلسل لـ transitions[0] وtransitions[1]:

{
  "routes": [
    {
      "transitions": [
        {
          "travelDuration": "1496s",
          "travelDistanceMeters": 7082,
          "waitDuration": "0s",
          "totalDuration": "1496s",
          "startTime": "2024-02-13T15:55:04Z"
        },
        {
          "travelDuration": "1992s",
          "travelDistanceMeters": 16589,
          "waitDuration": "0s",
          "totalDuration": "1992s",
          "startTime": "2024-02-13T16:25:00Z"
        },
        ...
      ]
    }
  ]
}

ما هي تكلفة المسار؟

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

يسرد الجدول التالي جميع الطرق التي يمكنك من خلالها العثور على معلومات التكلفة في الردّ:

تعكس التكاليف المحدّدة في routeCosts وcosts قيود التكلفة التي تحدّدها في طلبك. لمزيد من المعلومات، يُرجى الاطّلاع على مستند المفهوم الأساسي لنموذج التكلفة.

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

{
  "routes": [
    {
      "vehicleStartTime": "2024-02-13T15:55:04Z",
      "vehicleEndTime": "2024-02-13T17:40:00Z",
      ...
      "routeCosts": {
        "model.vehicles.cost_per_hour": 47.22
      },
      "routeTotalCost": 47.22
    }
  ],
  "metrics": {
    "totalCost": 147.22,
    "costs": {
      "model.shipments.penalty_cost": 100,
      "model.vehicles.cost_per_hour": 47.22
    },
    ...
  }
}

وفقًا لخطة المسار، يشغّل السائق الشاحنة من الساعة 7:55 صباحًا إلى الساعة 9:40 صباحًا، أي لمدة ساعة و45 دقيقة تقريبًا (6296 ثانية). وبمعدّل 27 دولار أمريكي في الساعة الذي حدّدته، تبلغ تكلفة المسار 47.22 دولار أمريكي. بما أنّ المحسِّن تخطّى شحنة الراعي الألماني، يضيف تكلفة جزائية بقيمة 100 دولار أمريكي، ما يجعل إجمالي التكلفة المجمّعة 147.22 دولار أمريكي.

لماذا تم تخطّي شحنة؟

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

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

بالنسبة لهذا السيناريو، تتعارض نافذة التقاط كلب الراعي الألماني مع نافذة كلب جبل بيرنيز. يقع "برج كويت" و"لاندز إند" على بُعد 25 دقيقة من بعضهما، لذلك لا يمكن للسائق إجراء عمليتَي الاستلام خلال فترة الـ 20 دقيقة. يجب أن يتخطّى المحسِّن أحدهما. بما أنّ تكلفة الغرامة المترتبة على عدم تلبية طلب مربّي كلاب الراعي الألماني أقل (100 دولار أمريكي مقابل 1,000 دولار أمريكي للعميل العادي)، يتخطّى المحسِّن هذا الطلب ويتحمّل غرامة قدرها 100 دولار أمريكي.

تعرض عيّنة التعليمات البرمجية التالية عنصر skippedShipments في الردّ:

{
  ...
  "skippedShipments": [
    {
      "index": 2,
      "label": "German shepherd",
      "penaltyCost": 100
    }
  ],
  ...
}

يحتوي عنصر skippedShipments في الاستجابة على الحقول التالية:

• ‫index: الفهرس المستند إلى الصفر للشحنة في طلبك (2 للشحنة الثالثة)
• ‫label: التصنيف الذي حدّدته في الطلب ("كلب الراعي الألماني").
• penaltyCost: تكلفة الغرامة التي حدّدتها في الطلب، والتي تضيفها واجهة برمجة التطبيقات إلى التكلفة الإجمالية.

لمنع المحسِّن من تخطّي شحنة، يمكنك تخفيف القيود التي تسبّب التعارض. على سبيل المثال، اطلب من مالك الراعي الألماني الحصول على نافذة استلام أكثر مرونة، ثم قم بتحديث timeWindows لهذا الاستلام في طلبك.

حقول الردّ في المثال

يوضّح الجدول التالي جميع حقول الاستجابة التي يتم عرضها في OptimizeToursResponse للسيناريو النموذجي. على الرغم من أنّه ليس عليك استخدام كل حقل لفهم خطة المسار، يمكنك تحليل هذه الحقول لتحديد كيفية تعديل OptimizeToursRequest لتناسب احتياجات نشاطك التجاري. لمزيد من المعلومات، يُرجى الاطّلاع على مراحل نشاط خطة المسار.

يمكنك فلترة المحتوى حسب العنصر الرئيسي أو البحث النصي.