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 انتقال وجود دارد.
  • یک بازدید همیشه توسط یک گذار قبل از آن (همان شاخص) و یک گذار بعد از آن (شاخص + ۱) احاطه شده است.
  • روشن شدن خودرو همیشه با انتقال شماره ۰ دنبال می‌شود.
  • انتهای وسیله نقلیه همیشه با انتقال #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

در نهایت، در اینجا نحوه‌ی تنظیم زمان سفر، زمان استراحت، زمان تأخیر و زمان انتظار در طول یک انتقال آورده شده است.

  • آنها همپوشانی ندارند.
  • مقدار DELAY منحصر به فرد است و باید یک دوره زمانی پیوسته درست قبل از بازدید بعدی (یا پایان وسیله نقلیه) باشد. بنابراین، دانستن مدت زمان تأخیر برای دانستن زمان شروع و پایان آن کافی است.
  • وقفه‌ها (BREAKS) دوره‌های زمانی پیوسته و بدون همپوشانی هستند. پاسخ، زمان شروع و مدت هر وقفه را مشخص می‌کند.
  • سفر و انتظار «قابل پیشگیری» هستند: می‌توانند در طول این انتقال چندین بار قطع شوند. مشتریان می‌توانند فرض کنند که سفر «در اسرع وقت» اتفاق می‌افتد و «انتظار» زمان باقی‌مانده را پر می‌کند.

یک مثال (پیچیده):

                               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-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده می‌کند. آفست‌های غیر از "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-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده می‌کند. آفست‌های غیر از "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 روی true تنظیم شده باشد، این فیلد نشان می‌دهد که ناهماهنگی‌ها در زمان‌بندی مسیر با استفاده از تخمین‌های مدت زمان سفر مبتنی بر ترافیک پیش‌بینی می‌شوند. ممکن است زمان کافی برای تکمیل سفر تنظیم‌شده بر اساس ترافیک، تأخیرها و استراحت‌های بین بازدیدها، قبل از اولین بازدید یا بعد از آخرین بازدید، در حالی که هنوز پنجره‌های زمانی بازدید و وسیله نقلیه را برآورده می‌کند، وجود نداشته باشد. به عنوان مثال،

  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 روی true تنظیم شده باشد.

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,
  "injectedSolutionLocationToken": integer
}
فیلدها
shipmentIndex

integer

فهرست فیلد shipments در مدل منبع ShipmentModel .

isPickup

boolean

اگر درست باشد، بازدید معادل دریافت Shipment است. در غیر این صورت، معادل تحویل کالا است.

visitRequestIndex

integer

فهرست VisitRequest در فیلد دریافت یا تحویل Shipment (به isPickup مراجعه کنید).

startTime

string ( Timestamp format)

زمان شروع بازدید. توجه داشته باشید که ممکن است وسیله نقلیه زودتر از این به محل بازدید برسد. زمان‌ها با ShipmentModel سازگار هستند.

از RFC 3339 استفاده می‌کند، که در آن خروجی تولید شده همیشه به صورت Z-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده می‌کند. آفست‌های غیر از "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 برای این بازدید روی true تنظیم شده باشد یا اگر ShipmentModel.avoid_u_turns در درخواست OptimizeToursRequest روی true تنظیم شده باشد، پر شود.

آزمایشی: برای جزئیات بیشتر به https://developers.google.com/maps/tt/route-optimization/experimental/u-turn-avoidance/make-request مراجعه کنید.

گذار

انتقال بین دو رویداد در مسیر. به توضیحات 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)

مدت زمان سفر در طول این انتقال.

مدت زمانی بر حسب ثانیه با حداکثر نه رقم کسری که به ' s ' ختم می‌شود. مثال: "3.5s" .

travelDistanceMeters

number

مسافت طی شده در طول انتقال.

trafficInfoUnavailable

boolean

وقتی ترافیک از طریق OptimizeToursRequest.consider_road_traffic درخواست می‌شود و اطلاعات ترافیک برای Transition قابل بازیابی نیست، این مقدار بولی روی true تنظیم می‌شود. این می‌تواند موقت (ایرادات نادر در سرورهای ترافیک بلادرنگ) یا دائمی (عدم وجود داده برای این مکان) باشد.

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`
  • مدت زمان استراحت + مدت زمان انتظار`.

مدت زمانی بر حسب ثانیه با حداکثر نه رقم کسری که به ' s ' ختم می‌شود. مثال: "3.5s" .

startTime

string ( Timestamp format)

زمان شروع این انتقال.

از RFC 3339 استفاده می‌کند، که در آن خروجی تولید شده همیشه به صورت Z-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده می‌کند. آفست‌های غیر از "Z" نیز پذیرفته می‌شوند. مثال‌ها: "2014-10-02T15:01:23Z" ، "2014-10-02T15:01:23.045123456Z" یا "2014-10-02T15:01:23+05:30" .

routePolyline

object ( EncodedPolyline )

نمایش چندخطی کدگذاری‌شده از مسیری که در طول انتقال دنبال می‌شود. این فیلد فقط در صورتی پر می‌شود که populateTransitionPolylines روی true تنظیم شده باشد.

routeToken

string

فقط خروجی. یک توکن مبهم که می‌تواند به Navigation SDK منتقل شود تا مسیر را در حین ناوبری بازسازی کند و در صورت تغییر مسیر، هدف اصلی هنگام ایجاد مسیر را رعایت کند. با این توکن به عنوان یک حباب مبهم رفتار کنید. مقدار آن را در درخواست‌های مختلف مقایسه نکنید زیرا ممکن است مقدار آن حتی اگر سرویس دقیقاً همان مسیر را برگرداند، تغییر کند. این فیلد فقط در صورتی پر می‌شود که populateTransitionPolylines روی true تنظیم شده باشد.

vehicleLoads

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

بارهای وسیله نقلیه در طول این انتقال، برای هر نوعی که یا در Vehicle.load_limits این وسیله نقلیه ظاهر می‌شود، یا Shipment.load_demands غیر صفر برای برخی از محموله‌های انجام شده در این مسیر دارد.

بارهای اولین انتقال، بارهای اولیه مسیر وسیله نقلیه هستند. سپس، پس از هر بازدید، بسته به اینکه بازدید، بارگیری یا تحویل بوده است، loadDemands بازدید یا اضافه یا کم می‌شود تا بارهای انتقال بعدی به دست آید.

پلی‌لاین رمزگذاری‌شده

نمایش کدگذاری شده یک چندخطی. اطلاعات بیشتر در مورد کدگذاری چندخطی را می‌توانید اینجا بیابید: 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-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده می‌کند. آفست‌های غیر از "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 بین ۰ و ۱ است که به عنوان نسبت بین یک فیلد معیار محدود شده (مثلاً AggregatedMetrics.travel_distance_meters ) و محدودیت وسیله نقلیه مرتبط با آن (مثلاً Vehicle.route_distance_limit ) در صورت وجود محاسبه می‌شود. در غیر این صورت، نسبت پر بودن تنظیم نشده باقی می‌ماند. اگر محدودیت ۰ باشد، فیلد روی ۱ تنظیم می‌شود. توجه: وقتی یک مسیر در معرض عدم امکان ترافیک قرار دارد، برخی از نسبت‌های خام پر بودن ممکن است از ۱.۰ فراتر روند، مثلاً وسیله نقلیه ممکن است از حد مسافت خود فراتر رود. در این موارد، مقادیر پر بودن را روی ۱.۰ محدود می‌کنیم.

نمایش 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 - earlyVehicleStartTime) برای یک وسیله نقلیه معین. اگر مخرج کسر وجود نداشته باشد، به جای آن از ( ShipmentModel.global_end_time - ShipmentModel.global_start_time ) استفاده می‌کند.