تفسير الرد

تعرض واجهة 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
    }
  }
}