تفسير الرد

تعرض 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 هذه السمة عندما تكون القيمة false.
  • 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
    }
  }
}