تفسير الرد

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

تحتوي رسالة OptimizeToursResponse (REST وgRPC) على سمتَين أساسيتَين من المستوى الأعلى:

  • routes[] هي مسارات كل مركبة مع الشحنات المخصّصة لها. يحتوي كل Route على مقاييس تعكس خصائص هذا المسار الفردي.
  • metrics هي مقاييس مجمّعة للردّ بالكامل، على مستوى كل المركبات وخطط المسارات. تحتوي المقاييس على مستوى القمة على الخصائص نفسها التي تحتوي عليها ومقاييس كل مسار، مع تجميع القيم على مستوى كل المسارات.

قد لا تتم تعبئة بعض السمات دائمًا استنادًا إلى نتائج التحسين:

  1. skippedShipments[] يعرض الشحنات التي لا يتم نقلها بواسطة أي مركبة. يمكن تخطّي شحنة إذا تعذّر تنفيذها ضمن قيود محدّدة أو إذا تجاوزت تكلفة تنفيذها تكلفة العقوبة. على سبيل المثال، إذا كان وقت تسليم أو استلام الشحنة محدودًا للغاية، قد لا يكون من الممكن أو ذا تكلفة معقولة أن تُجري المركبة التسليم أو الاستلام خلال الفترة الزمنية المطلوبة.timeWindow
  2. يحدِّد validationErrors[] الأخطاء التي تجعل الطلب غير صالح أو مستحيل حلّه عند ضبط solvingMode للطلب على VALIDATE_ONLY. في الوضع العادي DEFAULT_SOLVE، ستظهر أخطاء التحقّق في رسالة خطأ بدلاً من نص الاستجابة. يُرجى العلم أنّه VALIDATE_ONLY يمكن أن يُبلغ وضع حلّ المشاكل عن أخطاء متعددة في آنٍ واحد، ما هو مفيد لتصحيح أخطاء الطلبات بسرعة.

خصائص المسار

كل إدخال routes[] هو رسالة ShipmentRoute (REST أو gRPC). يمثّل كل ShipmentRoute تعيين المسار لمركبة معيّنة من الطلب. تشمل السمات المهمة في ShipmentRoute ذات الصلة بالVehicle المقابلة لها ما يلي:

  • vehicleIndex هو الفهرس بالاستناد إلى الصفر لـ Vehicle في رسالة الطلب المقابلة. تحذف ردود REST هذه السمة عندما تكون القيمة صفرًا.
  • vehicleStartTime هو الوقت الذي يجب أن تبدأ فيه المركبة مسارها.
  • vehicleEndTime هو الوقت المتوقّع لإنهاء المركبة مسارها.

في الردّ، سيظهر الرمز routes على النحو التالي:

{
  "routes": [
    {
      "vehicleStartTime": "2024-02-13T00:00:00Z",
      "vehicleEndTime": "2024-02-13T00:38:42Z",
      "visits": [
        ...
      ],
      "transitions": [
        ...
      ],
      "metrics": {
        ...
      },
      ...
    }
  ],
  ...
}

يحتوي كل ShipmentRoute على قائمة مرتبة بالvisits التي ستكملها المركبة. يمثّل كل Visit (REST وgRPC) VisitRequest (REST وgRPC) من الطلب المقابل. تشمل Visit السمات المهمة ما يلي:

  • shipmentIndex هو الفهرس الذي يبدأ من الصفر للشحنة التي تنتمي إليها هذه الزيارة في الطلب المقابل.
  • تكون القيمة isPickup صحيحة عندما تكون الزيارة عملية استلام وخاطئة عندما تكون عملية تسليم. تحذف ردود REST هذه السمة عندما تكون القيمة خطأ.
  • visitRequestIndex هو الفهرس الذي يبدأ من الصفر للعنصر VisitRequest من Shipment.pickups أو Shipment.deliveries في الطلب المقابل الذي يمثّله Visit. تحذف ردود REST هذه السمة عندما تكون قيمة صفر.
  • startTime هو الوقت المتوقّع لبدء الزيارة.
  • تُحدِّد loadDemands نوع التحميل حسب كمية التحميل المطلوبة لإكمال Visit. تكون كميات الحمولة سالبة لزيارات التسليم، ما يشير إلى إزالة الحمولة من المركبة.

في ما يلي مثال على Visit:

{
  "routes": [
    {
      ...
      "visits": [
        {
          "isPickup": true,
          "startTime": "2024-02-13T00:00:00Z",
          "detour": "0s"
        },
        ...
      ],
    },
    ...
  ],
  ...
}

يتضمّن كل ShipmentRoute قائمة مرتبة من transitions تمثّل التنقّل بين visits لمركبة معيّنة. تشمل خصائص رسائل Transition (REST وgRPC) المهمة ما يلي:

  • startTime هو الوقت الذي ستبدأ فيه المركبة في تنفيذ عملية الانتقال.
  • travelDuration هي المدة التي يجب أن تقطعها المركبة لإكمال عملية النقل.
  • travelDistanceMeters هي المسافة التي يجب أن تقطعها المركبة بالمتر لإكمال عملية النقل.
  • يشير trafficInfoUnavailable إلى ما إذا كانت بيانات عدد الزيارات متاحة لحالة الانتقال.
  • يمثّل waitDuration وقت التوقف الذي تقضيه المركبة في الانتظار قبل أن تتمكّن من بدء Visit التالي. قد يرجع ذلك إلى start_time Visit التالي.
  • totalDuration هي إجمالي مدة الانتقال، بما في ذلك أوقات التنقّل والانتظار والاستراحة والتأخير.
  • vehicleLoads يحدِّد نوع الحمولة حسب كمية الحمولة التي تحملها المركبة أثناء هذا النقل.

في ما يلي مثال على Transition:

{
  "routes": [
    {
      ...
      "transitions": [
        ...
        {
          "travelDuration": "1171s",
          "travelDistanceMeters": 9004,
          "waitDuration": "0s",
          "totalDuration": "1171s",
          "startTime": "2024-02-13T00:00:00Z"
        },
        ...
      ],
      ...
    }
  ],
  ...
}

لمزيد من المعلومات عن العلاقة بين vists وtransitions، يُرجى الاطّلاع على تحسين طلبات التوقف في نقاط الاستلام والتسليم والمستندات المرجعية ShipmentRoute (REST وgRPC). لمزيد من المعلومات عن سمتَي routePolyline وrouteToken في رسالة Transition، اطّلِع على الخطوط المتعددة المنحنية للانتقال ورموز المسارات.

خصائص المقاييس

تلخّص رسالة Metrics (REST وgRPC) الحلّ بأكمله. تشمل بعض خصائص Metrics المهمة ما يلي:

  • totalCost هي التكلفة الإجمالية المتكبّدة في إكمال المسارات. اطّلِع على مزيد من المعلومات عن التكاليف في مَعلمات نموذج التكلفة.
  • usedVehicleCount هو إجمالي عدد المركبات المستخدَمة في الحلّ. قد تتضمّن المركبات مسارات فارغة عندما يحدّد المحسِّن أنّ استخدامها غير ضروري.
  • skippedMandatoryShipmentCount هو عدد الشحنات التي تم تخطّيها والتي هي "إلزامية". لا تحدِّد الشحنة الإلزامية قيمة penaltyCost التي يتمّ تحمّلها في حال تخطّي الشحنة. سيظل بإمكانك تخطّي الشحنات الإلزامية إذا لم يكن أداؤها ممكنًا بموجب قيود محدّدة. اطّلِع على مزيد من المعلومات عن التكاليف في مَعلمات نموذج التكلفة.

يتم تسجيل المقاييس الإضافية كرسائل AggregatedMetrics (REST، gRPC). يتم استخدام نوع الرسالة AggregatedMetrics للسمة Metrics.aggregatedRouteMetrics وللسمة ShipmentRoute.metrics Metrics.aggregatedRouteMetrics التي تحتوي على مقاييس مجمّعة من جميع ShipmentRoute في OptimizeToursResponse. تحتوي كلّ سمة ShipmentRoute.metrics على مقاييس لهذا ShipmentRoute المحدّد.

تشمل خصائص AggregatedMetrics المهمة ما يلي:

  • performedShipmentCount هو عدد الشحنات التي تُجريها المركبات على طول مساراتها بالكامل.
  • travelDuration هو إجمالي الوقت الذي تقضيه المركبات في النقل أثناء إكمال مساراتها.
  • ‫waitDuration هو إجمالي الوقت الذي تقضيه المركبات في الانتظار أثناء إكمال مساراتها.
  • delayDuration هو إجمالي وقت التأخير للمركبات. يكون هذا عادةً صفرًا ما لم يتم استخدام TransitionAttributes في الطلب.
  • breakDuration هو إجمالي الوقت الذي تقضيه المركبات في فترات الراحة أثناء إكمال مساراتها.
  • visitDuration هو إجمالي الوقت الذي تقضيه المركبات في إجراء الزيارات أثناء إكمال مساراتها. وهذا هو مجموع كل قيم VisitRequest.duration لعناصر VisitRequest التي تتوافق مع عناصر Visit المخصّصة للمركبة السارية.
  • totalDuration هي إجمالي المدة المطلوبة لإكمال مسار المركبات.
  • travelDistanceMeters هي إجمالي المسافة التي قطعتها المركبات أثناء إكمال مساراتها.
  • maxLoads تربط أنواع الحمولة بحدّ الحمولة الأقصى الذي تنقله المركبات في أيّ نقطة على مساراتها.

في ما يلي مثال على رسالة Metrics:

{
  "routes": [
    ...
  ],
  "metrics": {
    "aggregatedRouteMetrics": {
      "performedShipmentCount": 1,
      "travelDuration": "2322s",
      "waitDuration": "0s",
      "delayDuration": "0s",
      "breakDuration": "0s",
      "visitDuration": "0s",
      "totalDuration": "2322s",
      "travelDistanceMeters": 18603
    },
    "usedVehicleCount": 1,
    "earliestVehicleStartTime": "2024-02-13T00:00:00Z",
    "latestVehicleEndTime": "2024-02-13T00:38:42Z",
    "totalCost": 18.603,
    "costs": {
      "model.vehicles.cost_per_kilometer": 18.603
    }
  }
}

مثال كامل

مثال كامل على ردّ الطلب من إنشاء طلب يشبه ما يلي:

{
  "routes": [
    {
      "vehicleStartTime": "2024-02-13T00:00:00Z",
      "vehicleEndTime": "2024-02-13T00:38:42Z",
      "visits": [
        {
          "isPickup": true,
          "startTime": "2024-02-13T00:00:00Z",
          "detour": "0s"
        },
        {
          "startTime": "2024-02-13T00:19:31Z",
          "detour": "0s"
        }
      ],
      "transitions": [
        {
          "travelDuration": "0s",
          "waitDuration": "0s",
          "totalDuration": "0s",
          "startTime": "2024-02-13T00:00:00Z"
        },
        {
          "travelDuration": "1171s",
          "travelDistanceMeters": 9004,
          "waitDuration": "0s",
          "totalDuration": "1171s",
          "startTime": "2024-02-13T00:00:00Z"
        },
        {
          "travelDuration": "1151s",
          "travelDistanceMeters": 9599,
          "waitDuration": "0s",
          "totalDuration": "1151s",
          "startTime": "2024-02-13T00:19:31Z"
        }
      ],
      "metrics": {
        "performedShipmentCount": 1,
        "travelDuration": "2322s",
        "waitDuration": "0s",
        "delayDuration": "0s",
        "breakDuration": "0s",
        "visitDuration": "0s",
        "totalDuration": "2322s",
        "travelDistanceMeters": 18603
      },
      "routeCosts": {
        "model.vehicles.cost_per_kilometer": 18.603
      },
      "routeTotalCost": 18.603
    }
  ],
  "metrics": {
    "aggregatedRouteMetrics": {
      "performedShipmentCount": 1,
      "travelDuration": "2322s",
      "waitDuration": "0s",
      "delayDuration": "0s",
      "breakDuration": "0s",
      "visitDuration": "0s",
      "totalDuration": "2322s",
      "travelDistanceMeters": 18603
    },
    "usedVehicleCount": 1,
    "earliestVehicleStartTime": "2024-02-13T00:00:00Z",
    "latestVehicleEndTime": "2024-02-13T00:38:42Z",
    "totalCost": 18.603,
    "costs": {
      "model.vehicles.cost_per_kilometer": 18.603
    }
  }
}