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"] هو مجموع جميع تكاليف الاستلام على طول المسار. يتم هنا عرض جميع التكاليف المحدّدة في النموذج بالتفصيل، باستثناء التكاليف المتعلّقة بسمات الانتقال التي يتم عرضها بشكل مجمّع فقط اعتبارًا من 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.

مدة بالثواني مع ما يصل إلى تسعة أرقام كسور، وتنتهي بـ "s". مثال: "3.5s"
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. لا يتم استخدام الزيارات إلى Stop إلا عند تفعيل ميزة "التحسين المتعدّد الوسائط".

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

الانتقال

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

إذا لم تكن المركبة مزوّدة بـ startLocation و/أو endLocation، تكون مقاييس التنقّل ذات الصلة صفرًا.

تمثيل 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)

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

مدة بالثواني مع ما يصل إلى تسعة أرقام كسور، وتنتهي بـ "s". مثال: "3.5s"
travelDistanceMeters

number

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

boolean

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

string (Duration format)

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

مدة بالثواني مع ما يصل إلى تسعة أرقام كسور، وتنتهي بـ "s". مثال: "3.5s"
breakDuration

string (Duration format)

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

مدة بالثواني مع ما يصل إلى تسعة أرقام كسور، وتنتهي بـ "s". مثال: "3.5s"
waitDuration

string (Duration format)

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

مدة بالثواني مع ما يصل إلى تسعة أرقام كسور، وتنتهي بـ "s". مثال: "3.5s"
totalDuration

string (Duration format)

إجمالي مدة الانتقال، ويتم توفيرها لتسهيل الأمر، وهي تساوي:

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

مدة بالثواني مع ما يصل إلى تسعة أرقام كسور، وتنتهي بـ "s". مثال: "3.5s"
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)

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

مدة بالثواني مع ما يصل إلى تسعة أرقام كسور، وتنتهي بـ "s". مثال: "3.5s"

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

نسبة Vehicle.route_duration_limit إلى [AggregatedMetrics.total_duration_seconds][]. إذا لم يتم ضبط 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) بدلاً منه.