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