تفسير الرد

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