البنية الأساسية (ShipmentModel وShipment وVehicle)

يحتوي ShipmentModel على عنصر `shipments` واحد يتضمّن نوع رسالة `Shipment` وعنصر `vehicles` واحد يتضمّن نوع رسالة `Vehicle`.

الهدف من Route Optimization API هو تخطيط المسارات لأسطول من المركبات لزيارة مجموعة من المواقع الجغرافية. يصف عنصر OptimizeToursRequest خصائص هذه المركبات والمواقع الجغرافية، وهو البنية الأساسية لنص طلب كل نقطة نهاية.

البنية الأساسية لعنصر OptimizeToursRequest هي كما يلي:

  • يحتوي الحقل model على رسالة ShipmentModel تتضمّن حقلَين رئيسيَين:
    • حقل shipments واحد يحتوي على رسالة واحدة أو أكثر من رسائل Shipment.
    • حقل vehicles واحد يحتوي على رسالة واحدة أو أكثر من رسائل Vehicle.

يصف هذا المستند أنواع الرسائل التالية:

  • ‫ShipmentModel: تحتوي على قائمة الشحنات والمركبات المتاحة والعناصر الأخرى التي تصف علاقاتها.
  • ‫Shipment: تصف المواقع الجغرافية التي ستزورها المركبة. ويمكن أن تمثّل الطرود الفعلية التي يجب استلامها وتسليمها أو الأماكن التي يؤدي فيها سائق المركبة خدمة معيّنة.
  • ‫Vehicle: تصف وسيلة النقل بين مواقع الشحنات. تمثّل كل مركبة مركبة فعلية أو شخصًا يتنقّل سيرًا على الأقدام.

ShipmentModel

يحتوي ShipmentModel على عناصر مسألة تحسين المسار. وتحتوي على مجموعة من الشحنات التي يمكن تنفيذها من خلال مجموعة من المركبات، مع مراعاة القيود وتقليل التكلفة الإجمالية.

يوضّح الجدول أدناه بعض السمات ذات الصلة بـ ShipmentModel:

الخصائص الوصف
shipments وvehicles عناصر مطلوبة تحتوي على تفاصيل شحنة واحدة أو أكثر ومركبة واحدة أو أكثر
globalStartTime وglobalEndTime تشير إلى بداية ونهاية الفترة الزمنية التي يجب أن تُكمل فيها جميع المركبات جميع عمليات الشحن. على الرغم من أنّ هذه السمات ليست مطلوبة، ننصحك بتضمينها لأنّ المحسِّن يعمل بشكل أفضل عند الالتزام بالقيود الزمنية.

يمكنك الاطّلاع على المستندات المرجعية للحصول على القائمة الكاملة للسمات في ShipmentModel.

ShipmentModel مثال

في هذا المثال، لديك خدمة رعاية نهارية للكلاب وتبدأ في إنشاء طلبك. أنت تحدّد الشحنات والمركبات لاحقًا، ولكنك تريد البدء بتحديد ساعات العمل وتكلفة التشغيل في الساعة.

في هذا المثال، تكون قيم السمة ShipmentModel في طلبك على النحو التالي:

الموقع القيمة الوصف
globalStartTime 2024-02-13T00:00:00.000Z تاريخ ووقت بدء ساعات العمل
globalEndTime 2024-02-14T06:00:00.000Z تاريخ ووقت انتهاء ساعات العمل

في ما يلي نموذج رمز لرسالة ShipmentModel يتضمّن قيم السيناريو النموذجي.

{
  "model": {
    "shipments": [
      ...
    ],
    "vehicles": [
      ...
    ],
   "globalStartTime": "2024-02-13T00:00:00.000Z",
   "globalEndTime": "2024-02-14T06:00:00.000Z"
  }
}

Shipment

يحدّد نوع الرسالة Shipment بنية السمة لشحنة يمكن تسليمها أو خدمة يمكن تنفيذها على مسار معيّن.

تساوي الشحنة الفعلية رسالة `Shipment` واحدة، والتي يتم تضمينها في عنصر `shipments`

كما هو موضّح في المخطّط البياني:

  • تحتوي رسالة Shipment على جميع المعلومات المتعلّقة بشحنة أو خدمة حقيقية.
  • يتم تحديد جميع رسائل Shipment في الحقل shipments.
  • يحتوي الحقل shipments على رسالة واحدة أو أكثر من رسائل Shipment.

تتطلّب رسالة Shipment عنصرًا واحدًا على الأقل من النوع pickups أو deliveries. في ما يلي تعريف هذه العناصر:

  • تحدّد السمة pickups الموقع الجغرافي لاستلام الشحنة.
  • تحدّد السمة deliveries الموقع الجغرافي لتسليم الشحنة.
  • يحتوي كل من pickups وdeliveries على نوع رسالة VisitRequest يحدّد المواقع الجغرافية وتفاصيل أخرى.

يوضّح الجدول التالي السيناريوهات المختلفة استنادًا إلى إعدادات pickups وdeliveries في رسالة Shipment.

السيناريو الوصف
pickups فقط يُفترض أنّك تستلم الشحنة فقط.
deliveries فقط يُفترض أنّك حمّلت الشحنة مسبقًا أو أنّك تقدّم خدمة.
‫pickups وdeliveries يجب أن تُكمل المركبة المخصّصة عملية الاستلام أولاً، ثم عملية التسليم. يمكن للمركبة التي نفّذت عملية الاستلام فقط تنفيذ عملية التسليم.
عدة pickups أو deliveries إذا كانت الشحنة تتضمّن احتمالات متعددة لـ pickups أو deliveries، يختار المحسِّن خيار استلام واحد وخيار تسليم واحد لاستخدامهما، وذلك استنادًا إلى تقليل التكلفة واستيفاء القيود.

يمكنك الاطّلاع على المستندات المرجعية للحصول على القائمة الكاملة للسمات في Shipment.

Shipment مثال

في هذا المثال، لديك خدمة رعاية نهارية للكلاب حيث تلتقط الكلاب من منزلهم وتسليمهم إلى الرعاية النهارية الخاصة بك. تريد ضبط موقع استلام كلبَين، وضبط موقع تسليمهما على موقع مؤسستك:

  • يقع منزل الكلب الأول في برج كويت في سان فرانسيسكو. إحداثيات هذا الموقع هي خط العرض 37.8024 وخط الطول -122.4058.
  • يقع منزل الكلب الثاني في حديقة South Sunset Playground Park في سان فرانسيسكو. إحداثيات هذا الموقع الجغرافي هي خط العرض 37.7359 وخط الطول ‎-122.5011.
  • يقع مركز رعاية الكلاب في حديقة Mission Dolores Park في سان فرانسيسكو. إحداثيات هذا الموقع الجغرافي هي خط العرض 37.759773 وخط الطول ‎-122.427063.

في ما يلي عينة تعليمات برمجية لرسالة Shipment، حيث يحتوي العنصر shipments على نوعَي رسائل Shipment مع الإحداثيات النموذجية.

{
  "model": {
    "shipments": [
      {
        "pickups": [
          {
            "arrivalLocation": {
              "latitude": 37.8024,
              "longitude": -122.4058
            }
          }
        ],
        "deliveries": [
          {
            "arrivalLocation": {
              "latitude": 37.759773,
              "longitude": -122.427063
            }
          }
        ]
      },
      {
        "pickups": [
          {
            "arrivalLocation": {
              "latitude": 37.7359,
              "longitude": -122.5011
            }
          }
        ],
        "deliveries": [
          {
            "arrivalLocation": {
              "latitude": 37.759773,
              "longitude": -122.427063
            }
          }
        ]
      }
    ],
    "vehicles": [
    ...
    ]
  }
}

Vehicle

يحدّد نوع الرسالة Vehicle بنية سمات المركبة التي يمكنها تنفيذ شحنة في مسار معيّن.

تمثّل المركبة في الحياة الواقعية رسالة `Vehicle` واحدة، وهي مضمّنة في عنصر `vehicles`

كما هو موضّح في المخطّط البياني:

  • تحتوي رسالة Vehicle على جميع معلومات المركبة في الحياة الواقعية.
  • يتم تحديد جميع رسائل Vehicle في الحقل vehicles.
  • يحتوي الحقل vehicles على رسائل Vehicle متعددة.

يوضّح الجدول التالي بعض السمات ذات الصلة لـ Vehicle.

الخصائص الوصف
startLocation وendLocation الموقع الجغرافي لبدء وانتهاء المركبات، وهو جزء من المسار النهائي المحسّن وفي حال عدم تحديدها، يتم ضبطها تلقائيًا على موقعَي استلام الشحنة الأولى وتسليم الشحنة الأخيرة.
‫costPerHour، costPerKilometer، costPerTraveledHour مَعلمات التكلفة الخاصة بالمركبة ننصحك بتضمين مَعلمة تكلفة واحدة على الأقل في طلبك لكي تعرض واجهة برمجة التطبيقات مسارًا محسّنًا. يمكنك الاطّلاع على المفهوم الرئيسي نموذج التكلفة لمزيد من المعلومات عن التكاليف.
startTimeWindows وendTimeWindows حدِّد الفترات الزمنية التي يمكن فيها تشغيل مركبة على مسار معيّن. يجب أن تقع هذه التواريخ ضمن الفترة الزمنية بين ‎globalStartTime و‎globalEndTime المحدّدة في ShipmentModel. على الرغم من أنّ هذه السمة ليست مطلوبة، ننصح بتضمينها لأنّ المحسِّن يعمل بشكل أفضل عند الالتزام بالقيود الزمنية.

Vehicle مثال

في هذا المثال، لديك خدمة رعاية نهارية للكلاب وتريد تحديد موقع مركبتك في بداية اليوم ونهايته ومقدار البنزين الذي تستهلكه. ليس عليك تحديد ساعات عمل المركبة لأنّها تتطابق مع الساعات التي حدّدتها في السمتَين globalStartTime وglobalEndTime ضمن العنصر ShipmentModel.

في هذا المثال، تكون قيم السمة Vehicle في طلبك على النحو التالي:

الموقع القيمة الوصف
startLocation latitude: 37.759773، longitude: -122.427063 إحداثيات بداية مسار مركبتك تتطابق هذه مع موقع مركز رعاية الكلاب الخاص بك والذي يقع في حديقة ميشن دولوريس، سان فرانسيسكو.
endLocation latitude: 37.759773، longitude: -122.427063 إحداثيات نهاية مسار مركبتك تتطابق هذه مع موقع مركز رعاية الكلاب الخاص بك والذي يقع في حديقة ميشن دولوريس، سان فرانسيسكو.
costPerHour 27 المبلغ الذي تدفعه للسائق مقابل قيادة مركبة مركز رعاية الكلاب. تدفع للسائق 27 دولارًا في الساعة.

في ما يلي نموذج رمز لرسالة Vehicle يتضمّن قيم السيناريو النموذجي.

{
  "model": {
    "shipments": [
    ...
    ],
    "vehicles": [
      {
        "startLocation": {
          "latitude": 37.759773,
          "longitude": -122.427063
        },
        "endLocation": {
          "latitude": 37.759773,
          "longitude": -122.427063
        },
        "costPerHour": 27
      }
    ]
  }
}

يمكنك الاطّلاع على المستندات المرجعية للحصول على القائمة الكاملة للسمات في Vehicle.

مثال على طلب مكتمل

تقدّم عيّنة التعليمات البرمجية التالية مثالاً كاملاً على الطلب، وتجمع بين الأمثلة ShipmentModel وShipment وVehicle المعروضة في هذا المستند.

{
  "model": {
    "shipments": [
      {
        "pickups": [
          {
            "arrivalLocation": {
              "latitude": 37.8024,
              "longitude": -122.4058
            }
          }
        ],
        "deliveries": [
          {
            "arrivalLocation": {
              "latitude": 37.759773,
              "longitude": -122.427063
            }
          }
        ]
      },
      {
        "pickups": [
          {
            "arrivalLocation": {
              "latitude": 37.7359,
              "longitude": -122.5011
            }
          }
        ],
        "deliveries": [
          {
            "arrivalLocation": {
              "latitude": 37.759773,
              "longitude": -122.427063
            }
          }
        ]
      }
    ],
    "vehicles": [
      {
        "startLocation": {
          "latitude": 37.759773,
          "longitude": -122.427063
        },
        "endLocation": {
          "latitude": 37.759773,
          "longitude": -122.427063
        },
        "costPerHour": 27
      }
    ],
    "globalStartTime": "2024-02-13T00:00:00.000Z",
    "globalEndTime": "2024-02-14T06:00:00.000Z"
  }
}