تفسير الرد

تعرض واجهة برمجة التطبيقات 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
    }
  }
}