تفسير الرد

تعرض واجهة برمجة التطبيقات Route Optimization API مسارات المركبات في الطلب المقابل. يتم تخصيص الشحنات للمركبات أو قد يتم تخطّيها حسب خصائص الطلب.

تحتوي رسالة OptimizeToursResponse (REST وgRPC) على سمتَين أساسيتَين من المستوى الأعلى:

• routes[] هي مسارات كل مركبة مع الشحنات المخصّصة لها. على كل يحتوي Route على مقاييس تعكس خصائص ذلك المسار الفردي.
• تمثّل metrics مقاييس مجمّعة للردود بأكملها على مستوى جميع المركبات وخطط المسارات. تحتوي مقاييس المستوى الأعلى على الخصائص نفسها مثل المقاييس لكل مسار، مع القيم المجمّعة على مستوى جميع المسارات

قد لا تتم تعبئة بعض السمات دائمًا استنادًا إلى نتائج التحسين:

1. skippedShipments[] يعرض الشحنات التي لا يتم نقلها بواسطة أي مركبة. يمكن تخطّي شحنة إذا تعذّر تنفيذها ضمن قيود محدّدة أو إذا تجاوزت تكلفة تنفيذها تكلفة العقوبة. على سبيل المثال، إذا كان وقت تسليم أو استلام الشحنة محدودًا للغاية، قد لا يكون من الممكن أو ذا تكلفة معقولة أن تُجري المركبة التسليم أو الاستلام خلال الفترة الزمنية المطلوبة.
2. يحدّد validationErrors[] الأخطاء التي تجعل الطلب غير صالح أو من المستحيل حله عند ضبط solvingMode للطلب على VALIDATE_ONLY في وضع DEFAULT_SOLVE العادي، ستظهر أخطاء التحقّق من الصحة في رسالة خطأ بدلاً من نص الاستجابة. يُرجى العلم أنّه VALIDATE_ONLY يمكن أن يُبلغ وضع حلّ المشاكل عن أخطاء متعدّدة في آنٍ واحد، ما هو مفيد لتصحيح أخطاء الطلبات بسرعة.

ملاحظة: لتفسير الرد، يجب توفير الطلب المقابل. الردّ يتضمن إشارات إلى كيانات في الطلب، مما يجعل الرد صعبًا تفسيره من تلقاء نفسه. بعض الرسائل مثل Shipment وVehicle لها تصنيف لتسهيل مطابقة بيانات الطلبات والاستجابة.

خصائص المسار

كل إدخال في 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": {
        ...
      },
      ...
    }
  ],
  ...
}

ملاحظة: تستخدِم استجابات REST تمثيل JSON في Protocol Buffers، الذي يحذف الحقول التي تحتوي على القيمة التلقائية لفئة الحقل ذات الصلة ولا تتيح عرض الحقل. وهذا يعني أن خصائص الأعداد الصحيحة مثل vehicleIndex هي إذا كانت قيمها صفرًا. يمكنك أيضًا الاطّلاع على المستند الرسمي Protocol Buffers JSON) مستندات عملية الربط

تشمل كل 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)

خصائص المقاييس

تلخِّص رسالة 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
    }
  }
}

ملاحظة مهمة: إذا لم تكن جميع التكاليف صفرًا في رسائل Metrics أو ShipmentRoute، من غير المحتمل أن يكون المحسِّن قد وجد ترتيبًا مثاليًا لإكمال Visit. يجب تحديد معلمة تكلفة واحدة على الأقل، مثل Vehicle.costPerKilometer أو globalDurationCostPerHour، أو المحسِّن الآخر أي حلّ يستوفي القيود المحدّدة.

المثال الكامل

مثال كامل لرد مكتمل على الطلب من قسم إنشاء طلب مثل:

{
  "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
    }
  }
}