ShipmentRoute

يمكن تقسيم مسار المركبة على محور الوقت على النحو التالي (نفترض أنّ هناك n زيارة):

  |            |            |          |       |  T[2], |        |      |
  | Transition |  Visit #0  |          |       |  V[2], |        |      |
  |     #0     |    aka     |   T[1]   |  V[1] |  ...   | V[n-1] | T[n] |
  |  aka T[0]  |    V[0]    |          |       | V[n-2],|        |      |
  |            |            |          |       | T[n-1] |        |      |
  ^            ^            ^          ^       ^        ^        ^      ^
vehicle    V[0].start   V[0].end     V[1].   V[1].    V[n].    V[n]. vehicle
 start     (arrival)   (departure)   start   end      start    end     end

يُرجى العِلم أنّنا نفرّق بين ما يلي:

  • "الأحداث في الوقت المحدد"، مثل بدء تشغيل المركبة وإيقافها، وبدء كل زيارة وانتهائها (المعروفة أيضًا باسم الوصول والمغادرة) أن تحدث في ثانية معيّنة
  • "الفواصل الزمنية"، مثل الزيارات نفسها والانتقال بين الزيارات على الرغم من أنّ الفواصل الزمنية قد تكون أحيانًا صفرية المدة، أي تبدأ وتنتهي في الثانية نفسها، إلا أنّها غالبًا ما تكون ذات مدة موجبة.

المتغيرات الثابتة:

  • إذا كانت هناك n زيارة، سيكون هناك n+1 عملية انتقال.
  • يجب أن يسبق الزيارة دائمًا انتقال (الفهرس نفسه) وأن يليها انتقال (الفهرس + 1).
  • يتبع بدء تشغيل السيارة دائمًا الانتقال رقم 0.
  • يسبق نهاية المركبة دائمًا الانتقال رقم n.

في ما يلي ما يحدث أثناء Transition وVisit:

---+-------------------------------------+-----------------------------+-->
   |           TRANSITION[i]             |           VISIT[i]          |
   |                                     |                             |
   |  * TRAVEL: the vehicle moves from   |      PERFORM the visit:     |
   |    VISIT[i-1].departure_location to |                             |
   |    VISIT[i].arrival_location, which |  * Spend some time:         |
   |    takes a given travel duration    |    the "visit duration".    |
   |    and distance                     |                             |
   |                                     |  * Load or unload           |
   |  * BREAKS: the driver may have      |    some quantities from the |
   |    breaks (e.g. lunch break).       |    vehicle: the "demand".   |
   |                                     |                             |
   |  * WAIT: the driver/vehicle does    |                             |
   |    nothing. This can happen for     |                             |
   |    many reasons, for example when   |                             |
   |    the vehicle reaches the next     |                             |
   |    event's destination before the   |                             |
   |    start of its time window         |                             |
   |                                     |                             |
   |  * DELAY: *right before* the next   |                             |
   |    arrival. E.g. the vehicle and/or |                             |
   |    driver spends time unloading.    |                             |
   |                                     |                             |
---+-------------------------------------+-----------------------------+-->
   ^                                     ^                             ^
V[i-1].end                           V[i].start                    V[i].end

أخيرًا، إليك كيفية ترتيب TRAVEL وBREAKS وDELAY وWAIT أثناء عملية الانتقال.

  • ولا تتداخل مع بعضها.
  • يجب أن يكون التأخير فريدًا ويجب أن يكون فترة زمنية متجاورة قبل الزيارة التالية (أو نهاية استخدام المركبة). وبالتالي، يكفي معرفة مدة التأخير لمعرفة وقت بدئه وانتهائه.
  • فترات الاستراحة هي فترات زمنية متجاورة وغير متداخلة. يحدّد الردّ وقت بدء كل استراحة ومدتها.
  • يمكن مقاطعة حالتي TRAVEL وWAIT عدة مرات أثناء هذا الانتقال. يمكن للعملاء افتراض أنّ السفر يحدث "في أقرب وقت ممكن" وأنّ "الانتظار" يملأ الوقت المتبقي.

مثال (معقّد):

                               TRANSITION[i]
--++-----+-----------------------------------------------------------++-->
  ||     |       |           |       |           |         |         ||
  ||  T  |   B   |     T     |       |     B     |         |    D    ||
  ||  r  |   r   |     r     |   W   |     r     |    W    |    e    ||
  ||  a  |   e   |     a     |   a   |     e     |    a    |    l    ||
  ||  v  |   a   |     v     |   i   |     a     |    i    |    a    ||
  ||  e  |   k   |     e     |   t   |     k     |    t    |    y    ||
  ||  l  |       |     l     |       |           |         |         ||
  ||     |       |           |       |           |         |         ||
--++-----------------------------------------------------------------++-->
تمثيل JSON 
{
  "vehicleIndex": integer,
  "vehicleLabel": string,
  "vehicleStartTime": string,
  "vehicleEndTime": string,
  "visits": [
    {
      object (Visit)
    }
  ],
  "transitions": [
    {
      object (Transition)
    }
  ],
  "hasTrafficInfeasibilities": boolean,
  "routePolyline": {
    object (EncodedPolyline)
  },
  "breaks": [
    {
      object (Break)
    }
  ],
  "metrics": {
    object (AggregatedMetrics)
  },
  "vehicleFullness": {
    object (VehicleFullness)
  },
  "routeCosts": {
    string: number,
    ...
  },
  "routeTotalCost": number
}
الحقول
vehicleIndex

integer

المركبة التي تنفّذ المسار، ويتم تحديدها من خلال فهرسها في المصدر ShipmentModel.
vehicleLabel

string

تصنيف المركبة التي تسلك هذا المسار، ويساوي ShipmentModel.vehicles(vehicleIndex).label، إذا تم تحديده.
vehicleStartTime

string (Timestamp format)

الوقت الذي تبدأ فيه المركبة مسارها

يستخدم المعيار RFC 3339، حيث يكون الناتج الذي يتم إنشاؤه مُمثلاً بالتوقيت العالمي المنسَّق مع حرف Z في النهاية ويستخدم الأرقام الجزئية 0 أو 3 أو 6 أو 9. تُقبل أيضًا المعادلات الأخرى التي لا تستخدم حرف Z. أمثلة: "2014-10-02T15:01:23Z" أو "2014-10-02T15:01:23.045123456Z" أو "2014-10-02T15:01:23+05:30".
vehicleEndTime

string (Timestamp format)

الوقت الذي تنهي فيه المركبة مسارها

يستخدم المعيار RFC 3339، حيث يكون الناتج الذي يتم إنشاؤه مُمثلاً بالتوقيت العالمي المنسَّق مع حرف Z في النهاية ويستخدم الأرقام الجزئية 0 أو 3 أو 6 أو 9. تُقبل أيضًا المعادلات الأخرى التي لا تستخدم حرف Z. أمثلة: "2014-10-02T15:01:23Z" أو "2014-10-02T15:01:23.045123456Z" أو "2014-10-02T15:01:23+05:30".
visits[]

object (Visit)

تسلسل مرتّب من الزيارات يمثّل مسارًا. visits[i] هي الزيارة رقم i في المسار. إذا كان هذا الحقل فارغًا، سيتم اعتبار المركبة غير مستخدَمة.
transitions[]

object (Transition)

قائمة مرتّبة بعمليات الانتقال للمسار
hasTrafficInfeasibilities

boolean

عندما تكون قيمة OptimizeToursRequest.consider_road_traffic هي "صحيح"، يشير هذا الحقل إلى أنّه يتم توقّع حالات عدم الاتساق في أوقات الرحلات باستخدام تقديرات مدة الرحلة المستندة إلى حركة المرور. قد لا يتوفّر وقت كافٍ لإكمال الرحلة المعدّلة حسب حركة المرور، والتأخيرات، والاستراحات بين الزيارات، أو قبل الزيارة الأولى، أو بعد الزيارة الأخيرة، مع استيفاء النطاقات الزمنية للزيارة والمركبة. على سبيل المثال:

  startTime(previous_visit) + duration(previous_visit) +
  travelDuration(previous_visit, next_visit) > startTime(next_visit)

من المرجّح أن يكون وقت الوصول إلى next_visit متأخرًا عن الفترة الزمنية الحالية بسبب زيادة الوقت المقدّر للرحلة travelDuration(previous_visit, next_visit) نتيجة الازدحام المروري. قد يتم أيضًا فرض استراحة لتتداخل مع زيارة بسبب زيادة في تقديرات مدة الرحلة وقيود على فترة الزيارة أو الاستراحة.
routePolyline

object (EncodedPolyline)

تمثيل الخطوط المتعددة المشفّرة للمسار لا تتم تعبئة هذا الحقل إلا إذا تم ضبط OptimizeToursRequest.populate_polylines على "صحيح".
breaks[]

object (Break)

فترات الاستراحة المجدوَلة للمركبة التي تسلك هذا المسار يمثّل التسلسل breaks الفواصل الزمنية، ويبدأ كل فاصل زمني عند startTime المقابل ويستمر لمدة duration ثانية.
metrics

object (AggregatedMetrics)

مقاييس المدة والمسافة والحِمل لهذا المسار يتم جمع حقول AggregatedMetrics على مستوى جميع ShipmentRoute.transitions أو ShipmentRoute.visits، وذلك حسب السياق.
vehicleFullness

object (VehicleFullness)

VehicleFullness لحساب مدى اقتراب المقاييس المحدودة من حدود المركبة الخاصة بها. حقولها هي نِسب بين حقل مقياس محدود (مثل AggregatedMetrics.travel_distance_meters) والحدّ الأقصى للمركبة ذي الصلة (مثل Vehicle.route_distance_limit).

تجريبي: قد يتغيّر سلوك هذا الحقل أو يتوقف عن الوجود في المستقبل.
routeCosts

map (key: string, value: number)

تكلفة المسار، مقسّمة حسب حقول الطلبات ذات الصلة بالتكلفة المفاتيح هي مسارات أولية، بالنسبة إلى OptimizeToursRequest للإدخال، مثل "model.shipments.pickups.cost"، والقيم هي التكلفة الإجمالية التي تم إنشاؤها بواسطة حقل التكلفة المقابل، ويتم تجميعها على مستوى المسار بأكمله. بعبارة أخرى، costs["model.shipments.pickups.cost"] هو مجموع جميع تكاليف الاستلام على طول المسار. يتم هنا عرض جميع التكاليف المحدّدة في النموذج بالتفصيل، باستثناء التكاليف المتعلّقة بسمات TransitionAttributes التي يتم عرضها بشكل مجمّع فقط اعتبارًا من 2022/01.
routeTotalCost

number

تمثّل هذه السمة التكلفة الإجمالية للمسار. مجموع كل التكاليف في خريطة التكاليف

زيارة

زيارة تم إجراؤها أثناء اتّباع مسار تتطابق هذه الزيارة مع استلام أو توصيل Shipment.

تمثيل JSON 
{
  "shipmentIndex": integer,
  "isPickup": boolean,
  "visitRequestIndex": integer,
  "startTime": string,
  "loadDemands": {
    string: {
      object (Load)
    },
    ...
  },
  "detour": string,
  "shipmentLabel": string,
  "visitLabel": string,
  "visitType": enum (VisitType),
  "injectedSolutionLocationToken": integer
}
الحقول
shipmentIndex

integer

فهرس الحقل shipments في المصدر ShipmentModel.
isPickup

boolean

إذا كانت القيمة صحيحة، تتوافق الزيارة مع عملية استلام Shipment. وفي ما عدا ذلك، يكون مرتبطًا بعملية تسليم.
visitRequestIndex

integer

فهرس VisitRequest في حقل الاستلام أو التوصيل ضمن Shipment (راجِع isPickup)
startTime

string (Timestamp format)

الوقت الذي تبدأ فيه الزيارة. يُرجى العِلم أنّ المركبة قد تصل إلى الموقع الجغرافي قبل هذا الوقت. تتطابق الأوقات مع ShipmentModel.

يستخدم المعيار RFC 3339، حيث يكون الناتج الذي يتم إنشاؤه مُمثلاً بالتوقيت العالمي المنسَّق مع حرف Z في النهاية ويستخدم الأرقام الجزئية 0 أو 3 أو 6 أو 9. تُقبل أيضًا المعادلات الأخرى التي لا تستخدم حرف Z. أمثلة: "2014-10-02T15:01:23Z" أو "2014-10-02T15:01:23.045123456Z" أو "2014-10-02T15:01:23+05:30".
loadDemands

map (key: string, value: object (Load))

إجمالي الطلب على تحميل الزيارات كمجموع الشحنة وطلب الزيارة loadDemands تكون القيم سالبة إذا كانت الزيارة عبارة عن عملية تسليم. يتم تسجيل الطلبات للأنواع نفسها التي يتم تسجيلها في Transition.loads (راجِع هذا الحقل).
detour

string (Duration format)

وقت إضافي للانحراف بسبب الشحنات التي تمت زيارتها على الطريق قبل الزيارة ووقت الانتظار المحتمل الناتج عن الفترات الزمنية. إذا كانت الزيارة عبارة عن عملية تسليم، يتم احتساب الانحراف عن المسار من زيارة الاستلام المقابلة ويكون مساويًا لما يلي:

startTime(delivery) - startTime(pickup)
- (duration(pickup) + travel duration from the pickup location
to the delivery location).

في ما عدا ذلك، يتم احتسابها من المركبة startLocation وتكون مساوية لما يلي:

startTime - vehicleStartTime - travel duration from
the vehicle's `startLocation` to the visit.
shipmentLabel

string

نسخة من Shipment.label المقابلة، إذا تم تحديدها في Shipment
visitLabel

string

نسخة من VisitRequest.label المقابل، إذا تم تحديدها في VisitRequest
visitType

enum (VisitType)

اختيارية: تحدّد هذه السمة نوع الزيارة. تتجاوز قيمة الحقل Visit.is_pickup.
injectedSolutionLocationToken

integer

رمز مميّز غير شفاف يمثّل معلومات عن موقع جغرافي تمت زيارته.

يمكن ملء هذا الحقل في زيارات مسارات النتائج عندما تكون قيمة VisitRequest.avoid_u_turns صحيحة لهذه الزيارة أو إذا كانت قيمة ShipmentModel.avoid_u_turns صحيحة في الطلب OptimizeToursRequest.

تجريبية: يُرجى الاطّلاع على https://developers.google.com/maps/tt/route-optimization/experimental/u-turn-avoidance/make-request لمزيد من التفاصيل.

VisitType

تشير هذه السمة إلى ما إذا كانت الزيارة هي استلام أو توصيل أو زيارة إلى Stop. لا يتم استخدام الزيارات إلى محطة توقّف إلا عند تفعيل ميزة "تحسين التنقّل المتعدّد الوسائط".

عمليات التعداد
VISIT_TYPE_UNSPECIFIED نوع زيارة غير محدّد
PICKUP_SHIPMENT تمثّل الزيارة عملية استلام شحنة.
DELIVER_SHIPMENT تشير الزيارة إلى عملية تسليم شحنة.

الانتقال

الانتقال بين حدثين على المسار اطّلِع على وصف ShipmentRoute.

إذا لم يكن لدى المركبة startLocation و/أو endLocation، تكون مقاييس السفر المقابلة 0.

تمثيل JSON 
{
  "travelDuration": string,
  "travelDistanceMeters": number,
  "trafficInfoUnavailable": boolean,
  "delayDuration": string,
  "breakDuration": string,
  "waitDuration": string,
  "totalDuration": string,
  "startTime": string,
  "routePolyline": {
    object (EncodedPolyline)
  },
  "routeToken": string,
  "vehicleLoads": {
    string: {
      object (VehicleLoad)
    },
    ...
  }
}
الحقول
travelDuration

string (Duration format)

مدة الرحلة خلال هذه الفترة الانتقالية
travelDistanceMeters

number

المسافة المقطوعة أثناء عملية الانتقال
trafficInfoUnavailable

boolean

عند طلب معلومات حركة المرور من خلال OptimizeToursRequest.consider_road_traffic، وتعذّر استرداد معلومات حركة المرور لـ Transition، يتم ضبط قيمة هذا النوع المنطقي على "صحيح". قد يكون ذلك مؤقتًا (خلل نادر في خوادم بيانات حركة المرور في الوقت الفعلي) أو دائمًا (لا تتوفّر بيانات لهذا الموقع الجغرافي).
delayDuration

string (Duration format)

مجموع مدة التأخير المطبَّقة على عملية الانتقال هذه. إذا كان هناك أي تأخير، يبدأ بعد delayDuration ثانية بالضبط من الحدث التالي (الزيارة أو نهاية الرحلة). يمكنك الاطّلاع على TransitionAttributes.delay.
breakDuration

string (Duration format)

مجموع مدة الفواصل الإعلانية التي تحدث أثناء هذا الانتقال، إن وُجدت يتم تخزين تفاصيل حول وقت بدء كل استراحة ومدتها في ShipmentRoute.breaks.
waitDuration

string (Duration format)

الوقت الذي تم قضاؤه في الانتظار خلال هذا الانتقال تتوافق مدة الانتظار مع وقت عدم النشاط ولا تشمل وقت الاستراحة. يُرجى العِلم أيضًا أنّه يمكن تقسيم وقت الانتظار هذا إلى عدة فواصل زمنية غير متجاورة.
totalDuration

string (Duration format)

تمثّل هذه السمة المدة الإجمالية للانتقال، وهي متوفّرة لتسهيل الأمر عليك. وهي تساوي:

  • الزيارة التالية startTime (أو vehicleEndTime إذا كان هذا هو الانتقال الأخير) - startTime هذا الانتقال
  • إذا كانت قيمة ShipmentRoute.has_traffic_infeasibilities هي false، ينطبق ما يلي أيضًا: `totalDuration = travelDuration + delayDuration
  • ‫breakDuration + waitDuration`.
startTime

string (Timestamp format)

وقت بدء هذا الانتقال

يستخدم المعيار RFC 3339، حيث يكون الناتج الذي يتم إنشاؤه مُمثلاً بالتوقيت العالمي المنسَّق مع حرف Z في النهاية ويستخدم الأرقام الجزئية 0 أو 3 أو 6 أو 9. تُقبل أيضًا المعادلات الأخرى التي لا تستخدم حرف Z. أمثلة: "2014-10-02T15:01:23Z" أو "2014-10-02T15:01:23.045123456Z" أو "2014-10-02T15:01:23+05:30".
routePolyline

object (EncodedPolyline)

تمثيل الخطوط المتعددة المشفّرة للمسار الذي تم اتّباعه أثناء الانتقال لا تتم تعبئة هذا الحقل إلا إذا تم ضبط populateTransitionPolylines على "صحيح".
routeToken

string

النتائج فقط. رمز مميّز غير شفاف يمكن تمريره إلى Navigation SDK لإعادة إنشاء المسار أثناء التنقّل، وفي حال إعادة التوجيه، يتم الالتزام بالنية الأصلية عند إنشاء المسار. يجب التعامل مع هذا الرمز المميز على أنّه كائن ثنائي كبير مبهم. لا تقارِن قيمتها بين الطلبات لأنّ قيمتها قد تتغيّر حتى إذا كانت الخدمة تعرض المسار نفسه بالضبط. لا تتم تعبئة هذا الحقل إلا إذا تم ضبط populateTransitionPolylines على "صحيح".
vehicleLoads

map (key: string, value: object (VehicleLoad))

حمولة المركبة أثناء عملية النقل هذه، لكل نوع يظهر في Vehicle.load_limits الخاص بهذه المركبة، أو الذي يحتوي على Shipment.load_demands غير صفري في بعض الشحنات التي يتم تنفيذها على هذا المسار

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

EncodedPolyline

تمثّل هذه السمة التمثيل المرمّز لخط متعدّد الأضلاع. يمكنك الاطّلاع على مزيد من المعلومات حول ترميز الخطوط المتعددة على الرابطين التاليين: https://developers.google.com/maps/documentation/utilities/polylinealgorithm https://developers.google.com/maps/documentation/javascript/reference/geometry#encoding.

تمثيل JSON 
{
  "points": string
}
الحقول
points

string

سلسلة تمثّل النقاط المشفرة للخط المتعدد الأضلاع.

استراحة

بيانات تمثّل تنفيذ استراحة

تمثيل JSON 
{
  "startTime": string,
  "duration": string
}
الحقول
startTime

string (Timestamp format)

وقت بدء الاستراحة

يستخدم المعيار RFC 3339، حيث يكون الناتج الذي يتم إنشاؤه مُمثلاً بالتوقيت العالمي المنسَّق مع حرف Z في النهاية ويستخدم الأرقام الجزئية 0 أو 3 أو 6 أو 9. تُقبل أيضًا المعادلات الأخرى التي لا تستخدم حرف Z. أمثلة: "2014-10-02T15:01:23Z" أو "2014-10-02T15:01:23.045123456Z" أو "2014-10-02T15:01:23+05:30".
duration

string (Duration format)

مدة الاستراحة

VehicleFullness

VehicleFullness هو مقياس يحسب مدى امتلاء مركبة. يتراوح كل حقل VehicleFullness بين 0 و1، ويتم احتسابه كنسبة بين حقل مقياس محدود (مثل AggregatedMetrics.travel_distance_meters) والحد الأقصى للمركبة المرتبط به (مثل Vehicle.route_distance_limit)، إذا كان متاحًا. وفي حال عدم إجراء ذلك، لن يتم تحديد نسبة الامتلاء. إذا كان الحدّ الأقصى هو 0، يتم ضبط الحقل على 1. ملاحظة: عندما يكون المسار عرضة لعدم إمكانية التنقّل بسبب الازدحام، قد تتجاوز بعض نسب الامتلاء الأولية 1.0، مثلاً قد تتجاوز المركبة الحدّ الأقصى للمسافة. في هذه الحالات، نضع حدًا أقصى لقيم الامتلاء عند 1.0.

تمثيل JSON 
{
  "maxFullness": number,
  "distance": number,
  "travelDuration": number,
  "activeDuration": number,
  "maxLoad": number,
  "activeSpan": number
}
الحقول
maxFullness

number

الحد الأقصى لجميع الحقول الأخرى في هذه الرسالة
distance

number

النسبة بين AggregatedMetrics.travel_distance_meters وVehicle.route_distance_limit في حال عدم ضبط Vehicle.route_distance_limit، لن يتم ضبط هذا الحقل.
travelDuration

number

نسبة Vehicle.travel_duration_limit إلى [AggregatedMetrics.travel_duration_seconds][]. في حال عدم ضبط Vehicle.travel_duration_limit، لن يتم ضبط هذا الحقل.
activeDuration

number

النسبة بين [AggregatedMetrics.total_duration_seconds][] وVehicle.route_duration_limit. في حال عدم ضبط Vehicle.route_duration_limit، لن يتم ضبط هذا الحقل.
maxLoad

number

النسبة القصوى بين جميع أنواع [AggregatedMetrics.max_load][] وVehicle.load_limits الخاص بها. إذا تم إلغاء ضبط جميع حقول Vehicle.load_limits، سيتم إلغاء ضبط هذا الحقل.
activeSpan

number

تمثّل هذه السمة النسبة (vehicleEndTime - vehicleStartTime) / (latestVehicleEndTime - earliestVehicleStartTime) لمركبة معيّنة. في حال عدم توفّر المقام، يتم استخدام (ShipmentModel.global_end_time - ShipmentModel.global_start_time) بدلاً منه.