تفسير الرد

تعرض 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).

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

تلخِّص رسالة 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
    }
  }
}