البنية الأساسية (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.
  • يقع منزل الكلب الثاني في حديقة "ساوث صنست بلايغراوند" في سان فرانسيسكو. إحداثيات هذا الموقع الجغرافي هي خط العرض 37.7359 وخط الطول -122.5011.
  • يقع مركز رعاية الكلاب في "متنزّه ميشن دولوريس" في سان فرانسيسكو. إحداثيات هذا الموقع الجغرافي هي خط العرض 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"
  }
}