تفسير الرد

تعرض 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 هو إجمالي الوقت الذي تقضيه المركبات في فترات الراحة أثناء completing their routes.
• 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
    }
  }
}