البنية الأساسية (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

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

  • يقع منزل الكلب الأول في Coit Tower في سان فرانسيسكو. إحداثيات هذا الموقع الجغرافي هي خط العرض 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 إحداثيات بدء مسار مركبتك تتطابق هذه الإحداثيات مع موقع مركز الرعاية النهارية للكلاب في Mission Dolores Park في سان فرانسيسكو.
endLocation latitude: 37.759773, longitude: -122.427063 إحداثيات انتهاء مسار مركبتك تتطابق هذه الإحداثيات مع موقع مركز الرعاية النهارية للكلاب في Mission Dolores Park في سان فرانسيسكو.
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"
  }
}