تفسير الرد

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

تعرض واجهة 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 الخاصة بـ VisitRequests المرتبطة بـ Visits المخصّصة للمركبة المعنية.
  • 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
    }
  }
}