تفسير الرد

المطوّرون في المنطقة الاقتصادية الأوروبية

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