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,
  "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
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 لمزيد من التفاصيل.

الانتقال

الانتقال بين حدثَين على المسار اطّلِع على وصف 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

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