Package google.maps.routeoptimization.v1

אינדקס

RouteOptimization

שירות לאופטימיזציה של סיורים ברכב.

תוקף של סוגי שדות מסוימים:

  • google.protobuf.Timestamp
    • השעות מוצגות לפי זמן יוניקס: שניות מאז 1970-01-01T00:00:00+00:00.
    • השניות צריכות להיות בטווח [0, 253402300799], כלומר בטווח [1970-01-01T00:00:00+00:00, 9999-12-31T23:59:59+00:00].
    • צריך לבטל את ההגדרה של nanos או להגדיר אותה כ-0.
  • google.protobuf.Duration
    • השניות צריכות להיות בטווח [0, 253402300799], כלומר בטווח [1970-01-01T00:00:00+00:00, 9999-12-31T23:59:59+00:00].
    • צריך לבטל את ההגדרה של nanos או להגדיר אותה כ-0.
  • google.type.LatLng
    • קו הרוחב חייב להיות בטווח [-90.0, 90.0].
    • קו האורך חייב להיות בטווח [-180.0, 180.0].
    • לפחות אחד מהערכים של קו הרוחב או קו האורך חייב להיות שונה מאפס.
BatchOptimizeTours

rpc BatchOptimizeTours(BatchOptimizeToursRequest) returns (Operation)

אופטימיזציה של סיורים לכלי רכב עבור הודעה אחת או יותר מסוג OptimizeToursRequest כקבוצה.

השיטה הזו היא פעולה ממושכת (LRO). הקלט לצורך אופטימיזציה (הודעות OptimizeToursRequest) והפלט (הודעות OptimizeToursResponse) נקראים מ-Cloud Storage ונכתבים אליו בפורמט שצוין על ידי המשתמש. בדומה לשיטה OptimizeTours, כל OptimizeToursRequest מכיל ShipmentModel ומחזיר OptimizeToursResponse שמכיל שדות ShipmentRoute, שהם קבוצה של מסלולים שכלי הרכב צריכים לבצע כדי למזער את העלות הכוללת.

המשתמש יכול לדגום את operations.get כדי לבדוק את סטטוס ה-LRO:

אם השדה done של LRO הוא false, סימן שעדיין מתבצע עיבוד של בקשה אחת לפחות. יכול להיות שבקשות אחרות הושלמו בהצלחה והתוצאות שלהן זמינות ב-Cloud Storage.

אם השדה done של ה-LRO הוא true, כל הבקשות עובדו. התוצאות של בקשות שתעובדו בהצלחה יהיו זמינות ב-Cloud Storage. התוצאות של בקשות שנכשלו לא יהיו זמינות ב-Cloud Storage. אם השדה error של ה-LRO מוגדר, הוא מכיל את השגיאה מאחד מהבקשות שנכשלו.

היקפי הרשאה

נדרש היקף הרשאות OAuth הבא:

  • https://www.googleapis.com/auth/cloud-platform
הרשאות IAM

נדרשת ההרשאה הבאה ב-IAM במשאב parent:

  • routeoptimization.operations.create

למידע נוסף, עיינו במסמכי העזרה של IAM.
OptimizeTours

rpc OptimizeTours(OptimizeToursRequest) returns (OptimizeToursResponse)

הפונקציה שולחת OptimizeToursRequest שמכיל ShipmentModel ומחזירה OptimizeToursResponse שמכיל ShipmentRoute, שהם קבוצה של מסלולים שכלי רכב צריכים לבצע כדי למזער את העלות הכוללת.

מודל ShipmentModel מורכב בעיקר מ-Shipment שצריך לבצע ומ-Vehicle שאפשר להשתמש בהם כדי להעביר את ה-Shipment. ShipmentRoute מקצים Shipment ל-Vehicle. באופן ספציפי יותר, הם מקצים לכל רכב סדרה של Visit, כאשר Visit תואם ל-VisitRequest, שהוא איסוף או מסירה של Shipment.

המטרה היא לספק הקצאה של ShipmentRoute ל-Vehicle שמקטינה את העלות הכוללת, כאשר העלות כוללת הרבה רכיבים שמוגדרים ב-ShipmentModel.

היקפי הרשאה

נדרש היקף הרשאות OAuth הבא:

  • https://www.googleapis.com/auth/cloud-platform
הרשאות IAM

נדרשת ההרשאה הבאה ב-IAM במשאב parent:

  • routeoptimization.locations.use

למידע נוסף, עיינו במסמכי העזרה של IAM.

AggregatedMetrics

מדדים מצטברים של ShipmentRoute (לחלופין, של OptimizeToursResponse בכל הרכיבים מסוג Transition ו/או Visit (לחלופין, בכל הרכיבים מסוג ShipmentRoute).

שדות
performed_shipment_count

int32

מספר המשלוחים שבוצעו. חשוב לזכור שזוג של איסוף ומשלוח נספר רק פעם אחת.
travel_duration

Duration

משך הנסיעה הכולל במסלול או בפתרון.
wait_duration

Duration

משך ההמתנה הכולל למסלול או לפתרון.
delay_duration

Duration

משך העיכוב הכולל במסלול או בפתרון.
break_duration

Duration

משך ההפסקה הכולל במסלול או בפתרון.
visit_duration

Duration

משך הביקור הכולל במסלול או בפתרון.
total_duration

Duration

משך הזמן הכולל צריך להיות שווה לסכום של כל משכי הזמן שלמעלה. במסלולים, הוא תואם גם לפרטים הבאים:

[ShipmentRoute.vehicle_end_time][google.maps.routeoptimization.v1.ShipmentRoute.vehicle_end_time] - [ShipmentRoute.vehicle_start_time][google.maps.routeoptimization.v1.ShipmentRoute.vehicle_start_time]
travel_distance_meters

double

מרחק הנסיעה הכולל במסלול או בפתרון.
max_loads

map<string, VehicleLoad>

העומס המקסימלי שהושג לאורך המסלול כולו (או הפתרון כולו), לכל אחת מהכמויות במסלול הזה (או בפתרון הזה), מחושב כערך המקסימלי מכל Transition.vehicle_loads (או ShipmentRoute.metrics.max_loads.

BatchOptimizeToursMetadata

אין שדות לסוג הזה.

מטא-נתונים של פעולות לשיחות BatchOptimizeToursRequest.

BatchOptimizeToursRequest

בקשה לביצוע אופטימיזציה של סיורים בכמות גדולה כפעולה אסינכרונית. כל קובץ קלט צריך להכיל OptimizeToursRequest אחד, וכל קובץ פלט יכיל OptimizeToursResponse אחד. הבקשה מכילה מידע לקריאה/כתיבה ולניתוח של הקבצים. כל קובצי הקלט והפלט צריכים להיות באותו פרויקט.

שדות
parent

string

חובה. בחירת הפרויקט והמיקום לקריאה.

פורמט: * projects/{project-id} * projects/{project-id}/locations/{location-id}

אם לא מציינים מיקום, המערכת בוחרת אזור באופן אוטומטי.
model_configs[]

AsyncModelConfig

חובה. פרטי קלט/פלט של כל מודל רכישה, כמו נתיבי קבצים ופורמטים של נתונים.

AsyncModelConfig

מידע לפתרון של מודל אופטימיזציה אחד באופן אסינכרוני.

שדות
display_name

string

זה שינוי אופציונלי. שם מודל שהוגדר על ידי משתמש. המשתמשים יכולים להשתמש בו ככינוי כדי לעקוב אחרי מודלים.
input_config

InputConfig

חובה. מידע על מודל הקלט.
output_config

OutputConfig

חובה. פרטי המיקום של הפלט הרצוי.

BatchOptimizeToursResponse

אין שדות לסוג הזה.

תגובה לBatchOptimizeToursRequest. הערך הזה מוחזר בפעולה הממושכת אחרי שהפעולה מסתיימת.

BreakRule

כללים ליצירת הפסקות זמן לכלי רכב (למשל הפסקות צהריים). הפסקה היא תקופה רציפה של זמן שבמהלכה הרכב נשאר במצב מנוחה במיקום הנוכחי שלו ולא יכול לבצע ביקור כלשהו. הפסקה עשויה להתרחש:

  • במהלך הנסיעה בין שני ביקורים (כולל הזמן שלפני הביקור או אחריו, אבל לא באמצע הביקור). במקרה כזה, זמן הנסיעה המתאים בין הביקורים יתארך.
  • או לפני הפעלת הרכב (לא ניתן להפעיל את הרכב באמצע הפסקה), במקרה כזה הוא לא משפיע על מועד הפעלת הרכב.
  • או אחרי סיום הנסיעה ברכב (אותו הדבר, עם זמן סיום הנסיעה ברכב).
שדות
break_requests[]

BreakRequest

רצף ההפסקות. הצגת ההודעה BreakRequest.
frequency_constraints[]

FrequencyConstraint

יכול להיות שיחולו כמה FrequencyConstraint. כל התנאים האלה חייבים להתקיים לגבי ה-BreakRequest של ה-BreakRule הזה. ראו FrequencyConstraint.

BreakRequest

צריך לדעת מראש את רצף ההפסקות (כלומר המספר והסדר שלהן) שחלות על כל רכב. הערכים החוזרים של BreakRequest מגדירים את הרצף הזה, בסדר שבו הם חייבים להתרחש. חלונות הזמן שלהם (earliest_start_time / latest_start_time) עשויים לחפוף, אבל הם חייבים להיות תואמים להזמנה (הבדיקה הזו מתבצעת).

שדות
earliest_start_time

Timestamp

חובה. גבול תחתון (כולל) לתחילת ההפסקה.
latest_start_time

Timestamp

חובה. הגבול העליון (כולל) של תחילת ההפסקה.
min_duration

Duration

חובה. משך הזמן המינימלי של ההפסקה. חייב להיות חיובי.

FrequencyConstraint

אפשר להגביל עוד יותר את התדירות והמשך הזמן של ההפסקות שצוינו למעלה, על ידי אכיפת תדירות מינימלית של ההפסקות, למשל "חובה להוסיף הפסקה של שעה אחת לפחות בכל 12 שעות". בהנחה שאפשר לפרש את המשפט הזה כ "בכל חלון זמן נע באורך 12 שעות, חייבת להיות הפסקה אחת לפחות באורך שעה אחת לפחות", הדוגמה הזו תועבר ל-FrequencyConstraint הבא:

{
   min_break_duration { seconds: 3600 }         # 1 hour.
   max_inter_break_duration { seconds: 39600 }  # 11 hours (12 - 1 = 11).
}

התזמון והמשך ההפסקות בפתרון יהיו בהתאם לכל האילוצים האלה, בנוסף לחלונות הזמן ולמשכים המינימליים שכבר צוינו ב-BreakRequest.

בפועל, FrequencyConstraint עשוי לחול על הפסקות לא רצופות. לדוגמה, התזמון הבא עומד בדרישות של הדוגמה 'שעה אחת כל 12 שעות':

  04:00 vehicle start
   .. performing travel and visits ..
  09:00 1 hour break
  10:00 end of the break
   .. performing travel and visits ..
  12:00 20-min lunch break
  12:20 end of the break
   .. performing travel and visits ..
  21:00 1 hour break
  22:00 end of the break
   .. performing travel and visits ..
  23:59 vehicle end
שדות
min_break_duration

Duration

חובה. משך ההפסקה המינימלי של האילוץ הזה. מספר חיובי. ראו את התיאור של FrequencyConstraint.
max_inter_break_duration

Duration

חובה. התקופה המקסימלית המותרת של כל מרווח זמן במסלול שלא כולל לפחות חלק מההפסקה של duration >= min_break_duration. חייב להיות חיובי.

DataFormat

פורמטים של נתונים לקובצי קלט ופלט.

טיפוסים בני מנייה (enum)
DATA_FORMAT_UNSPECIFIED ערך לא חוקי, הפורמט לא יכול להיות UNSPECIFIED.
JSON JavaScript Object Notation.
PROTO_TEXT פורמט טקסט של מאגרי אחסון לפרוטוקולים. https://protobuf.dev/reference/protobuf/textformat-spec/

DistanceLimit

מגבלה שמגדירה את המרחק המקסימלי שאפשר לנסוע. הוא יכול להיות קשה או רך.

אם מוגדרת מגבלה רכה, צריך להגדיר גם את soft_max_meters וגם את cost_per_kilometer_above_soft_max, והם לא יכולים להיות שליליים.

שדות
max_meters

int64

מגבלה קשיחה שמגבילה את המרחק ל-max_meters לכל היותר. המגבלה חייבת להיות לא שלילית.
soft_max_meters

int64

הגבלה רכה שלא אוכפת מגבלה מרחק מקסימלית, אבל אם היא מופרת, היא גורמת לעלות שמתווספת לעלויות אחרות שהוגדרו במודל, באותה יחידה.

אם הערך של soft_max_meters מוגדר, הוא חייב להיות קטן מ-max_meters ולא שלילי.
cost_per_kilometer_below_soft_max

double

העלות לקילומטר שנצברה, ועולה עד soft_max_meters, לפי הנוסחה:

  min(distance_meters, soft_max_meters) / 1000.0 *
  cost_per_kilometer_below_soft_max.

העלות הזו לא נתמכת ב-route_distance_limit.
cost_per_kilometer_above_soft_max

double

העלות לקילומטר תחויב אם המרחק חורג מהמגבלה soft_max_meters. העלות הנוספת היא 0 אם המרחק נמוך מהמגבלה, אחרת הנוסחה לחישוב העלות היא:

  (distance_meters - soft_max_meters) / 1000.0 *
  cost_per_kilometer_above_soft_max.

העלות חייבת להיות לא שלילית.

GcsDestination

המיקום ב-Google Cloud Storage שאליו ייכתבו קובצי הפלט.

שדות
uri

string

חובה. URI של Google Cloud Storage.

GcsSource

המיקום ב-Google Cloud Storage שממנו יקרא קובץ הקלט.

שדות
uri

string

חובה. URI של אובייקט ב-Google Cloud Storage בפורמט gs://bucket/path/to/object.

InjectedSolutionConstraint

פתרון שהוזרק לבקשה, כולל מידע על הביקורים שצריך להגביל ואיך צריך להגביל אותם.

שדות
routes[]

ShipmentRoute

המסלולים של הפתרון להזרקה. יכול להיות שחלק מהמסלולים יוסרו מהפתרון המקורי. המסלולים והמשלוחים שהושמטו חייבים לעמוד בהנחות הבסיסיות לגבי תקינות שמפורטות עבור injected_first_solution_routes.
skipped_shipments[]

SkippedShipment

משלוחים של הפתרון להזרקה שקודמו. יכול להיות שחלק מהם לא ייכללו בפתרון המקורי. מידע נוסף מפורט בשדה routes.
constraint_relaxations[]

ConstraintRelaxation

לקבוצות אפס או יותר של כלי רכב, מציין מתי ואיך להקל על האילוצים. אם השדה הזה ריק, כל מסלולי כלי הרכב שאינם ריקים מוגבלים לחלוטין.

ConstraintRelaxation

עבור קבוצה של כלי רכב, מציינים את ערכי הסף שבהם ההגבלות על הביקורים יתרופפו ואת רמת ההרפיה. משלוחים שמפורטים בשדה skipped_shipment מוגבלים לדילוג, כלומר אי אפשר לבצע אותם.

שדות
relaxations[]

Relaxation

כל ההקלות על אילוצים של ביקורים שחלות על ביקורים במסלולים עם כלי רכב ב-vehicle_indices.
vehicle_indices[]

int32

מציין את אינדקסי כלי הרכב שאליהם חל האילוץ relaxations על ביקורים. אם השדה ריק, הוא נחשב לברירת המחדל והשדה relaxations יחול על כל הרכבים שלא צוינו בשדות constraint_relaxations אחרים. יכולה להיות ברירת מחדל אחת לכל היותר, כלומר, מותר ששדה אחד של הרפיית אילוצים יהיה ריק vehicle_indices. אפשר להוסיף אינדקס רכב לרשימת הנכסים רק פעם אחת, גם אם הוא מופיע בכמה constraint_relaxations.

אם הערך של interpret_injected_solutions_using_labels הוא true, מערכי הרכב ממופה באופן זהה ל-ShipmentRoute.vehicle_index (ראו הערה fields).

הירגעות

אם השדה relaxations ריק, שעת ההתחלה והסדר של כל הביקורים ב-routes מוגבלים לחלוטין, ואי אפשר להוסיף או להכניס ביקורים חדשים למסלולים האלה. בנוסף, שעת ההתחלה ושעת הסיום של הרכב ב-routes מוגבלות לחלוטין, אלא אם הרכב ריק (כלומר, אין לו ביקורים והערך של used_if_route_is_empty מוגדר כ-false במודל).

relaxations(i).level מציין את רמת ההרפיה של האילוצים שחלה על ביקור מס' j שעומד בדרישות הבאות:

  • route.visits(j).start_time >= relaxations(i).threshold_time וגם
  • j + 1 >= relaxations(i).threshold_visit_count

באופן דומה, התנאי להתנעת הרכב משוחרר ל-relaxations(i).level אם הוא עומד בתנאים הבאים:

  • vehicle_start_time >= relaxations(i).threshold_time וגם
  • relaxations(i).threshold_visit_count == 0 והקצה של הרכב משוחרר ל-relaxations(i).level אם הוא עומד בתנאים הבאים:
  • vehicle_end_time >= relaxations(i).threshold_time וגם
  • route.visits_size() + 1 >= relaxations(i).threshold_visit_count

כדי להחיל רמת הפחתת עומס אם הביקור עומד בקריטריון threshold_visit_count או בקריטריון threshold_time, מוסיפים שני relaxations עם אותו level: אחד עם הגדרת threshold_visit_count בלבד והשני עם הגדרת threshold_time בלבד. אם ביקור עומד בתנאים של כמה relaxations, המערכת מחילה את הרמה הכי פחות מחמירה. כתוצאה מכך, מרגע היציאה מהרכב ועד לסיום הנסיעה, רמת ההרפיה הולכת וגדלה: כלומר, רמת ההרפיה לא פוחתת ככל שהנסיעה מתקדמת.

התזמון והרצף של ביקורים במסלול שלא עומדים בתנאי הסף של אף relaxations מוגבלים לחלוטין, ואי אפשר להוסיף ביקורים לרצפים האלה. כמו כן, אם התחלה או סיום של נסיעה ברכב לא עומדים בתנאי של כל הקלות, השעה קבועה, אלא אם הרכב ריק.

שדות
level

Level

רמת ההרפיה של האילוצים שחלה כאשר התנאים מתקיימים ב-threshold_time או לאחר מכן וגם ב-threshold_visit_count לפחות.
threshold_time

Timestamp

המועד שבו ניתן להחיל את ההרפיה level או אחריו.
threshold_visit_count

int32

מספר הביקורים שבהם ניתן להחיל את ההקלה level או אחריהם. אם הערך של threshold_visit_count הוא 0 (או לא מוגדר), יכול להיות שהערך של level יוחל ישירות בזמן הפעלת הרכב.

אם הערך הוא route.visits_size() + 1, ה-level עשוי לחול רק על קצה הרכב. אם הערך גדול מ-route.visits_size() + 1, הכלל level לא יחול בכלל על המסלול הזה.

רמה

מייצג את רמות ההרפיה השונות של האילוצים, שחלות על ביקור ועל הביקורים הבאים אחריו אם הוא עומד בתנאי הסף.

הרשימה הבאה מסודרת לפי רמת הרפיה גוברת.

טיפוסים בני מנייה (enum)
LEVEL_UNSPECIFIED

רמת ההרפיה המשתמעת שמוגדרת כברירת מחדל: לא מתבצעת הרפיה של אף אחת מהמגבלות, כלומר כל הביקורים מוגבלים באופן מלא.

אסור להשתמש בערך הזה באופן מפורש ב-level.
RELAX_VISIT_TIMES_AFTER_THRESHOLD לא תהיה הגבלה על שעות ההתחלה של הביקורים ועל שעות ההתחלה/הסיום של הרכב, אבל כל ביקור יישאר קשור לאותו רכב וצריך לציית לסדר הביקורים: אי אפשר להוסיף ביקור ביניהן או לפניהן.
RELAX_VISIT_TIMES_AND_SEQUENCE_AFTER_THRESHOLD זהה ל-RELAX_VISIT_TIMES_AFTER_THRESHOLD, אבל גם רצף הביקורים משוחרר יותר: אפשר לבצע ביקורים רק ברכב הזה, אבל יכול להיות שהם לא יבוצעו.
RELAX_ALL_AFTER_THRESHOLD זהה ל-RELAX_VISIT_TIMES_AND_SEQUENCE_AFTER_THRESHOLD, אבל הרכב גם משוחרר: הביקורים הם בחינם לחלוטין אחרי מועד הסף או במועד הסף, ויכול להיות שהם לא יבוצעו.

InputConfig

מציינים קלט עבור [BatchOptimizeTours][google.maps.routeoptimization.v1.RouteOptimizationService.BatchOptimizeTours].

שדות
data_format

DataFormat

חובה. הפורמט של נתוני הקלט.
שדה האיחוד source. חובה. הערך של source יכול להיות רק אחת מהאפשרויות הבאות:
gcs_source

GcsSource

מיקום ב-Google Cloud Storage. זה חייב להיות אובייקט יחיד (קובץ).

מיקום

עטיפה של מיקום (נקודה גיאוגרפית וכותרת אופציונלית).

שדות
lat_lng

LatLng

הקואורדינטות הגיאוגרפיות של נקודת הציון.
heading

int32

כיוון המצפן שמשויך לכיוון של זרימת התנועה. הערך הזה משמש לציון הצד של הכביש שבו יתבצע האיסוף וההחזרה. ערכי הכיוון יכולים להיות מ-0 עד 360, כאשר 0 מציין כיוון צפון, 90 מציין כיוון מזרח וכו'.

OptimizeToursRequest

בקשה שניתנת לפתרון של אופטימיזציה של סיור, שמגדיר את מודל המשלוח לפתרון וגם את פרמטרים האופטימיזציה.

שדות
parent

string

חובה. בוחרים את הפרויקט או המיקום שאליהם רוצים להתקשר.

פורמט: * projects/{project-id} * projects/{project-id}/locations/{location-id}

אם לא מציינים מיקום, המערכת בוחרת אזור באופן אוטומטי.
timeout

Duration

אם מגדירים את הזמן הקצוב הזה, השרת מחזיר תשובה לפני שחלפו פרק הזמן הקצוב או לפני שחלף מועד היעד של השרת לבקשות סינכרוניות, המוקדם מביניהם.

בבקשות אסינכררוניות, השרת ייצור פתרון (אם אפשר) לפני שפג תוקף הזמן הקצוב.
model

ShipmentModel

מודל המשלוח לפתרון.
solving_mode

SolvingMode

כברירת מחדל, מצב הפתרון הוא DEFAULT_SOLVE (0).
search_mode

SearchMode

מצב החיפוש ששימש לפתרון הבקשה.
injected_first_solution_routes[]

ShipmentRoute

הנחיה של אלגוריתם האופטימיזציה למצוא פתרון ראשון שדומה לפתרון קודם.

המודל מוגבל כשיוצרים את הפתרון הראשון. כל משלוחים שלא בוצעו במסלול מסוים יועברו אוטומטית לשלב הבא בפתרון, אבל יכול להיות שהם יבוצעו בפתרון הבא.

הפתרון צריך לעמוד בהנחות בסיסיות לגבי תקינות:

  • לכל המסלולים, הערך של vehicle_index חייב להיות בטווח ולא כפול.
  • לכל הביקורים, הערכים של shipment_index ו-visit_request_index חייבים להיות בטווח.
  • אפשר להפנות למשלוח רק במסלול אחד.
  • האיסוף של משלוח עם איסוף והעברה צריך להתבצע לפני המסירה.
  • לא ניתן לבצע יותר מאפשרות אחת לאיסוף או למשלוח של משלוח.
  • בכל המסלולים, הזמנים הולכים וגדלים (כלומר, vehicle_start_time <= visits[0].start_time <= visits[1].start_time ... <= vehicle_end_time).
  • אפשר לבצע משלוח רק ברכב מורשה. מותר להשתמש ברכב אם השדה Shipment.allowed_vehicle_indices ריק או אם השדה vehicle_index שלו נכלל בשדה Shipment.allowed_vehicle_indices.

אם הפתרון שהוזן לא מתאים, לא בהכרח תוחזר שגיאת אימות. יכול להיות שתוחזר שגיאה שמציינת את חוסר ההתאמה.
injected_solution_constraint

InjectedSolutionConstraint

להגביל את אלגוריתם האופטימיזציה כדי למצוא פתרון סופי שדומה לפתרון קודם. לדוגמה, אפשר להשתמש באפשרות הזו כדי להקפיא חלקים של מסלולים שכבר הושלמו או שעוד צריך להשלים, אבל אסור לשנות אותם.

אם הפתרון שהוזן לא מתאים, לא בהכרח תוחזר שגיאת אימות. יכול להיות שתוחזר שגיאה שמציינת את חוסר ההתאמה.
refresh_details_routes[]

ShipmentRoute

אם הערך לא ריק, המסלולים הנתונים יתרעננו בלי לשנות את הרצף הבסיסי של הביקורים או זמני הנסיעה שלהם: רק פרטים אחרים יעודכנו. הפעולה הזו לא פותרת את הבעיה במודל.

נכון ל-11 בנובמבר 2020, הפונקציה מאכלסת רק את הקווים הפוליגונליים של מסלולים שאינם ריקים, וצריך שהערך של populate_polylines יהיה True.

יכול להיות שהשדות route_polyline של המסלולים שהועברו לא יהיו עקביים עם המסלול transitions.

אסור להשתמש בשדה הזה יחד עם injected_first_solution_routes או injected_solution_constraint.

ל-Shipment.ignore ול-Vehicle.ignore אין השפעה על ההתנהגות. קווים פוליגונים עדיין מאוכלסים בין כל הביקורים בכל המסלולים שאינם ריקים, גם אם המערכת מתעלמת מהמשלוחים או מהרכבים הקשורים.
interpret_injected_solutions_using_labels

bool

אם הערך הוא true:

הפרשנות הזו חלה על השדות injected_first_solution_routes,‏ injected_solution_constraint ו-refresh_details_routes. אפשר להשתמש בה כשהאינדקסים של המשלוחים או הרכבים בבקשה השתנו מאז יצירת הפתרון, אולי כי הוספו או הוסרו משלוחים או רכבים מהבקשה.

אם הערך הוא True, תוויות בקטגוריות הבאות חייבות להופיע לכל היותר פעם אחת בקטגוריה שלהן:

אם הערך של vehicle_label בפתרון שהוזן לא תואם לרכב של בקשה, המסלול התואם יוסר מהפתרון יחד עם הביקורים שלו. אם הערך של shipment_label בפתרון שהוזן לא תואם לשליחת בקשה, הביקור התואם יוסר מהפתרון. אם SkippedShipment.label בפתרון שהוזן לא תואם לשליחת בקשה, ה-SkippedShipment מוסר מהפתרון.

הסרה של ביקורים במסלולים או של מסלולים שלמים מהפתרון שהוזן יכולה להשפיע על האילוצים המשתמעים, וכתוצאה מכך לגרום לשינוי בפתרון, לשגיאות אימות או לכך שהפתרון לא יהיה ריאלי.

הערה: מבצע הקריאה החוזרת צריך לוודא שכל Vehicle.label (resp. Shipment.label) מזהה באופן ייחודי ישות של רכב (או משלוח) שמופיעה בשתי הבקשות הרלוונטיות: הבקשה הקודמת שהניבה את OptimizeToursResponse ששימש בפתרון שהוזן, והבקשה הנוכחית שכוללת את הפתרון שהוזן. בדיקות הייחודיות המתוארות למעלה לא מספיקות כדי להבטיח את העמידה בדרישה הזו.
consider_road_traffic

bool

כדאי להביא בחשבון את אומדן התנועה בזמן החישוב של השדות ShipmentRoute‏ Transition.travel_duration,‏ Visit.start_time ו-vehicle_end_time, בזמן ההגדרה של השדה ShipmentRoute.has_traffic_infeasibilities ובזמן החישוב של השדה OptimizeToursResponse.total_cost.
populate_polylines

bool

אם הערך הוא true, קווים פוליגונליים יאוכלסו בתשובות ShipmentRoute.
populate_transition_polylines

bool

אם הערך הוא True, קווים פוליגונליים ואסימונים של מסלולים יאוכלסו בתגובה ShipmentRoute.transitions.
allow_large_deadline_despite_interruption_risk

bool

אם ההגדרה הזו מוגדרת, לבקשה יכול להיות מועד יעד (מידע נוסף זמין בכתובת https://grpc.io/blog/deadlines) של עד 60 דקות. אחרת, מועד ההגשה האחרון הוא 30 דקות בלבד. חשוב לזכור שלבקשות לטווח ארוך יש סיכון גבוה יותר (אבל עדיין קטן) להפרעה.
use_geodesic_distances

bool

אם הערך הוא true, מרחקי הנסיעה יחושבו לפי מרחקים גיאודזיים במקום מרחקים במפות Google, וזמני הנסיעה יחושבו לפי מרחקים גיאודזיים עם מהירות שמוגדרת על ידי geodesic_meters_per_second.
label

string

תווית שעשויה לשמש לזיהוי הבקשה הזו, שתדווח ב-OptimizeToursResponse.request_label.
geodesic_meters_per_second

double

כשהערך של use_geodesic_distances הוא true, צריך להגדיר את השדה הזה. השדה הזה מגדיר את המהירות שחלה על חישוב זמני הנסיעה. הערך שלו חייב להיות לפחות 1.0 מטרים לשנייה.
max_validation_errors

int32

חיתוך מספר שגיאות האימות שמוחזרות. בדרך כלל השגיאות האלה מצורפות לעומס הנתונים של שגיאת INVALID_ARGUMENT כפרטי שגיאה של BadRequest (https://cloud.google.com/apis/design/errors#error_details), אלא אם הוגדר solving_mode=VALIDATE_ONLY: ראו את השדה OptimizeToursResponse.validation_errors. ברירת המחדל היא 100, והמגבלה המקסימלית היא 10,000.

SearchMode

מצב שמגדיר את התנהגות החיפוש, תוך התחשבות בזמן האחזור לעומת איכות הפתרון. בכל המצבים, מועד ההגשה האחרון של הבקשה ברמת החשבון הארגוני נאכף.

טיפוסים בני מנייה (enum)
SEARCH_MODE_UNSPECIFIED מצב חיפוש לא צוין, שווה ל-RETURN_FAST.
RETURN_FAST כדאי להפסיק את החיפוש אחרי שמוצאים את הפתרון הראשון שטוב.
CONSUME_ALL_AVAILABLE_TIME כדאי להקדיש את כל הזמן הזמין לחיפוש פתרונות טובים יותר.

SolvingMode

הגדרה של האופן שבו הפתרון צריך לטפל בבקשה. בכל המצבים מלבד VALIDATE_ONLY, אם הבקשה לא חוקית, תתקבל הודעת השגיאה INVALID_REQUEST. אפשר להיעזר במאמר max_validation_errors כדי להגביל את מספר השגיאות שיוחזרו.

טיפוסים בני מנייה (enum)
DEFAULT_SOLVE פותרים את המודל. יכול להיות שיופיעו אזהרות ב-[OptimizeToursResponse.validation_errors][google.cloud.optimization.v1.OptimizeToursResponse.validation_errors].
VALIDATE_ONLY רק מאמת את המודל בלי לפתור אותו: מאכלס כמה שיותר OptimizeToursResponse.validation_errors.
DETECT_SOME_INFEASIBLE_SHIPMENTS

מאכלס רק את OptimizeToursResponse.validation_errors או את OptimizeToursResponse.skipped_shipments, ולא פותר את שאר הבקשה (status ו-routes לא מוגדרים בתגובה). אם מתגלות בעיות בביצוע במסלולים של injected_solution_constraint, הן מאוכלסות בשדה OptimizeToursResponse.validation_errors והשדה OptimizeToursResponse.skipped_shipments נשאר ריק.

חשוב: לא כל המשלוחים שלא ניתן לבצע אותם מוחזרים כאן, אלא רק אלה שזוהו כבלתי אפשריים במהלך העיבוד המקדים.

OptimizeToursResponse

תגובה לאחר פתרון בעיה באופטימיזציה של סיור, שמכילה את המסלולים שבהם כל רכב נוסע, את המשלוחים שנדחו ואת העלות הכוללת של הפתרון.

שדות
routes[]

ShipmentRoute

מסלולים שחושבו לכל רכב. המסלול ה-i תואם לרכב ה-i במודל.
request_label

string

עותק של OptimizeToursRequest.label, אם צוינה תווית בבקשה.
skipped_shipments[]

SkippedShipment

רשימה של כל המשלוחים שנדחו.
validation_errors[]

OptimizeToursValidationError

רשימה של כל שגיאות האימות שזיהינו באופן עצמאי. אפשר לעיין בהסבר לגבי 'שגיאות מרובות' לגבי ההודעה OptimizeToursValidationError. במקום שגיאות, הסטטוס הזה יכלול אזהרות במקרה ש-solving_mode הוא DEFAULT_SOLVE.
metrics

Metrics

מדדי משך זמן, מרחק ושימוש של הפתרון הזה.

מדדים

מדדים כלליים, שמצטברים מכל המסלולים.

שדות
aggregated_route_metrics

AggregatedMetrics

נתון נצבר מכל הנתיבים. כל מדד הוא הסכום (או הערך המקסימלי, עבור עומסי עבודה) של כל שדות ShipmentRoute.metrics באותו שם.
skipped_mandatory_shipment_count

int32

מספר המשלוחים החובה שקודם להם עברה 'דילוג'.
used_vehicle_count

int32

מספר כלי הרכב שבהם נעשה שימוש. הערה: אם מסלול של רכב ריק ו-Vehicle.used_if_route_is_empty הוא true, הרכב נחשב ל'בשימוש'.
earliest_vehicle_start_time

Timestamp

שעת ההתחלה המוקדמת ביותר של רכב משומש, מחושבת כערך המינימלי של ShipmentRoute.vehicle_start_time בכל כלי הרכב המשומשים.
latest_vehicle_end_time

Timestamp

שעת הסיום האחרונה של רכב משומש, מחושבת כערך המקסימלי של ShipmentRoute.vehicle_end_time בכל הרכבים המשומשים.
costs

map<string, double>

עלות הפתרון, לפי פירוט של שדות הבקשה שקשורים לעלויות. המפתחות הם נתיבים של פרוטו, ביחס לקלט OptimizeToursRequest, למשל 'model.shipments.pickups.cost', והערכים הם העלות הכוללת שנוצרה על ידי שדה העלות התואם, שנצברה לאורך כל הפתרון. במילים אחרות, costs["model.shipments.pickups.cost"] הוא הסכום של כל עלויות האיסוף בפתרון. כל העלויות שמוגדרות במודל מדווחות כאן בפירוט, למעט עלויות שקשורות ל-TransitionAttributes שמדווחות רק באופן מצטבר החל מינואר 2022.
total_cost

double

העלות הכוללת של הפתרון. הסכום של כל הערכים במפת העלויות.

OptimizeToursValidationError

תיאור של שגיאה או אזהרה שנתקלו בהן במהלך אימות של OptimizeToursRequest.

שדות
code

int32

שגיאת אימות מוגדרת על ידי הצמד (code, display_name) שתמיד נמצא.

השדות שמופיעים אחרי הקטע הזה מספקים הקשר נוסף לגבי השגיאה.

MULTIPLE ERRORS: כשיש כמה שגיאות, תהליך האימות מנסה להפיק כמה מהן. בדומה למה שמתרחש במהלך הידור, זהו תהליך לא מושלם. חלק משגיאות האימות יהיו 'קריטיות', כלומר הן יעצרו את כל תהליך האימות. זה המצב, בין היתר, בשגיאות מסוג display_name="UNSPECIFIED". שגיאות מסוימות עלולות לגרום לתהליך האימות לדלג על שגיאות אחרות.

יציבות: הערכים של code ו-display_name אמורים להיות יציבים מאוד. עם זאת, קודים ושמות תצוגה חדשים עשויים להופיע לאורך זמן, וכתוצאה מכך בקשה (לא חוקית) מסוימת עשויה להניב צמד (code, display_name) שונה כי השגיאה החדשה הסתירה את השגיאה הישנה. לדוגמה, 'שגיאות מרובות'.
display_name

string

השם המוצג של השגיאה.
fields[]

FieldReference

הקשר של שגיאה יכול לכלול 0, 1 (בדרך כלל) או יותר שדות. לדוגמה, אפשר להפנות לכלי הרכב מס' 4 ולאיסוף הראשון של משלוח מס' 2 באופן הבא:

fields { name: "vehicles" index: 4}
fields { name: "shipments" index: 2 sub_field {name: "pickups" index: 0} }

עם זאת, חשוב לזכור שהעוצמה של fields לא אמורה להשתנות עבור קוד שגיאה נתון.
error_message

string

מחרוזת לתיאור השגיאה, שאנשים יכולים לקרוא. יש מיפוי אחד-לאחד בין code לבין error_message (כשהקוד שונה מ-'UNSPECIFIED').

יציבות: לא יציבה: הודעת השגיאה שמשויכת ל-code נתון עשויה להשתנות עם הזמן (בתקווה שהיא תתבהר). במקום זאת, יש להשתמש ב-display_name וב-code.
offending_values

string

יכול להכיל את הערכים של השדות. האפשרות הזו לא תמיד זמינה. אין להסתמך עליו בשום אופן, וצריך להשתמש בו רק לניפוי באגים ידני של מודל.

FieldReference

הקשר של שגיאת האימות. הערך FieldReference תמיד מתייחס לשדה נתון בקובץ הזה, ופועל לפי אותו מבנה היררכי. לדוגמה, אפשר לציין את רכיב מס' 2 של start_time_windows ברכב מס' 5 באמצעות:

name: "vehicles" index: 5 sub_field { name: "end_time_windows" index: 2 }

עם זאת, אנחנו משמיטים ישויות ברמה העליונה כמו OptimizeToursRequest או ShipmentModel כדי למנוע עומס בהודעה.

שדות
name

string

שם השדה, למשל "vehicles".
sub_field

FieldReference

שדה משנה בתצוגת עץ רפלקטיבית, אם יש צורך.

שדה האיחוד index_or_key.

הערך של index_or_key יכול להיות רק אחת מהאפשרויות הבאות:
index

int32

האינדקס של השדה אם הוא חוזר.
key

string

מפתח אם השדה הוא מפה.

OutputConfig

מציינים יעד לתוצאות של [BatchOptimizeTours][google.maps.routeoptimization.v1.RouteOptimizationService.BatchOptimizeTours].

שדות
data_format

DataFormat

חובה. פורמט הנתונים של הפלט.
שדה האיחוד destination. חובה. הערך של destination יכול להיות רק אחת מהאפשרויות הבאות:
gcs_destination

GcsDestination

המיקום ב-Google Cloud Storage שאליו רוצים לכתוב את הפלט.

RouteModifiers

האובייקט הזה מכיל קבוצה של תנאים אופציונליים שצריך לעמוד בהם כשמחשבים מסלולים לכלי רכב. הערך הזה דומה ל-RouteModifiers בממשק ה-API המועדף של מסלולים בפלטפורמה של מפות Google. מידע נוסף זמין בכתובת https://developers.google.com/maps/documentation/routes/reference/rest/v2/RouteModifiers.

שדות
avoid_tolls

bool

מציין אם להימנע מכבישי אגרה במקרים סבירים. המערכת תעדיף מסלולים שלא כוללים כבישי אגרה. המאפיין הזה רלוונטי רק לאמצעי הגעה ממונעים.
avoid_highways

bool

מציין אם להימנע מכבישים מהירים במקרים סבירים. המערכת תעדיף מסלולים שלא כוללים כבישים מהירים. המאפיין הזה רלוונטי רק לאמצעי הגעה ממונעים.
avoid_ferries

bool

קובעת אם להימנע ממעבורות במקרים סבירים. המערכת תעדיף מסלולים שלא כוללים נסיעה במעבורות. המאפיין הזה רלוונטי רק לאמצעי הגעה ממונעים.
avoid_indoor

bool

זה שינוי אופציונלי. ההגדרה הזו קובעת אם להימנע מניהול ניווט בתוך מבנים, במקרים שבהם זה אפשרי. המערכת תעדיף מסלולים שלא כוללים ניווט בתוך מבנים. ההגדרה חלה רק על מצב הנסיעה WALKING.

משלוח

המשלוח של פריט אחד, מאחד המקומות שבהם הוא נאסף ועד לאחד המקומות שבהם הוא נמסר. כדי שהמשלוח ייחשב כמיושם, רכב ייחודי צריך לבקר באחד ממיקומי האיסוף שלו (ולצמצם את הקיבולת הפנויה שלו בהתאם), ולאחר מכן לבקר באחד ממיקומי המסירה שלו בשלב מאוחר יותר (ולכן להגדיל מחדש את הקיבולת הפנויה שלו בהתאם).

שדות
display_name

string

שם התצוגה שהוגדר על ידי המשתמש למשלוח. השם יכול להכיל עד 63 תווים, וניתן להשתמש בתווים של UTF-8.
pickups[]

VisitRequest

קבוצה של חלופות לאיסוף המשוכות למשלוח. אם לא צוין מיקום, הרכב צריך להגיע רק למיקום שמתאים להעברות.
deliveries[]

VisitRequest

קבוצה של חלופות משלוח שמשויכות למשלוח. אם לא צוין מיקום, הרכב צריך להגיע רק למיקום שמתאים לאיסוף.
load_demands

map<string, Load>

דרישות הטעינה של המשלוח (למשל משקל, נפח, מספר משטחים וכו'). המפתחות במפה צריכים להיות מזהים שמתארים את סוג העומס התואם, רצוי שגם יחד עם היחידות. לדוגמה: weight_kg,‏ volume_gallons,‏ pallet_count וכו'. אם מפתח נתון לא מופיע במפה, העומס התואם נחשב כ-null.
allowed_vehicle_indices[]

int32

קבוצת כלי הרכב שיכולים לבצע את המשלוח הזה. אם השדה ריק, כל כלי הרכב יכולים לבצע את הפעולה. הרכבים מוצגים לפי המדד שלהם ברשימה vehicles של ShipmentModel.
costs_per_vehicle[]

double

העלות שנצברת כשהמשלוח הזה נמסר על ידי כל רכב. אם מציינים את השדה, הוא חייב לכלול:

  • את אותו מספר רכיבים כמו costs_per_vehicle_indices. costs_per_vehicle[i] תואם לרכב costs_per_vehicle_indices[i] מהדגם.
  • אותו מספר רכיבים כמו מספר כלי הרכב בדגם. הרכיב ה-i תואם לרכב מספר i מהדגם.

העלויות האלה חייבות להיות באותה יחידה כמו penalty_cost, והן לא יכולות להיות שליליות. אם אין עלויות כאלה, משאירים את השדה הזה ריק.
costs_per_vehicle_indices[]

int32

אינדקסים של כלי הרכב שאליהם costs_per_vehicle חל. אם הוא לא ריק, הוא חייב להכיל את אותו מספר רכיבים כמו costs_per_vehicle. אסור לציין אינדקס רכב יותר מפעם אחת. אם רכב מסוים מוחרג מ-costs_per_vehicle_indices, העלות שלו היא אפס.
pickup_to_delivery_absolute_detour_limit

Duration

משך הזמן המרבי המוחלט של הסטייה מהמסלול בהשוואה לנתיב הקצר ביותר מהאיסוף אל המשלוח. אם יצוין, הערך חייב להיות חיובי, והמשלוח חייב לכלול לפחות איסוף ומשלוח.

לדוגמה, נניח ש-t הוא הזמן הקצר ביותר שנדרש כדי לעבור מאפשרות האיסוף שנבחרה ישירות לאפשרות המסירה שנבחרה. לאחר מכן, ההגדרה pickup_to_delivery_absolute_detour_limit אוכפת:

start_time(delivery) - start_time(pickup) <=
t + pickup_to_delivery_absolute_detour_limit

אם צוינו מגבלות יחסיות ומוחלטות באותה משלוח, המערכת תשתמש במגבלה המחמירה יותר לכל צמד אפשרי של איסוף/מסירה. החל מאוקטובר 2017, יש תמיכה במסלולי עקיפה רק כשמשך הנסיעה לא תלוי בסוג הרכב.
pickup_to_delivery_time_limit

Duration

משך הזמן המקסימלי מתחילת האיסוף ועד תחילת המסירה של המשלוח. אם יצוין, הערך חייב להיות חיובי, והמשלוח חייב לכלול לפחות איסוף ומשלוח. הזמן הזה לא תלוי בחלופות שנבחרו לאיסוף ולמשלוח, או במהירות הרכב. אפשר לציין את האפשרות הזו לצד אילוצים של עיקוף מקסימלי: הפתרון יתייחס לשתי המפרטים.
shipment_type

string

מחרוזת לא ריקה שצוינה בה 'סוג' למשלוח הזה. אפשר להשתמש בתכונה הזו כדי להגדיר אי-תאימות או דרישות בין shipment_types (ראו shipment_type_incompatibilities ו-shipment_type_requirements בקובץ ShipmentModel).

שונה מ-visit_types שמצוין לביקור יחיד: כל האיסופים או המסירות ששייכים לאותו משלוח משויכים לאותו shipment_type.
label

string

תווית של המשלוח. התווית הזו מדווחת בתגובה בשדה shipment_label של ShipmentRoute.Visit התואם.
ignore

bool

אם הערך הוא True, המערכת תדלג על המשלוח הזה, אבל לא תחיל penalty_cost.

התעלמות משליחה גורמת לשגיאת אימות אם יש shipment_type_requirements כלשהו במודל.

מותר להתעלם משליחה שמתבצעת ב-injected_first_solution_routes או ב-injected_solution_constraint. הפתרון מסיר מהמסלול את הביקורים הקשורים לאיסוף או למסירה. precedence_rules שמתייחסים למשלוחים שנדחו.
penalty_cost

double

אם המשלוח לא יושלם, העונש הזה יתווסף לעלות הכוללת של הנתיבים. משלוח נחשב כסגור אם מתבצעת ביקור באחת מהאפשרויות לאיסוף ולמסירה. העלות יכולה להיות מבוטאת באותה יחידה שבה נעשה שימוש בכל שאר השדות הקשורים לעלות במודל, והיא חייבת להיות חיובית.

חשוב: אם לא מציינים את הקנס הזה, הוא נחשב כקנס ללא הגבלת זמן, כלומר חובה להשלים את המשלוח.
pickup_to_delivery_relative_detour_limit

double

משך הזמן המקסימלי של הסטייה היחסית בהשוואה לנתיב הקצר ביותר מהאיסוף למסירה. אם יצוין, הערך חייב להיות חיובי, והמשלוח חייב לכלול לפחות איסוף ומשלוח.

לדוגמה, נניח ש-t הוא הזמן הקצר ביותר שנדרש כדי לעבור מאפשרות האיסוף שנבחרה ישירות לאפשרות המסירה שנבחרה. לאחר מכן, ההגדרה pickup_to_delivery_relative_detour_limit אוכפת:

start_time(delivery) - start_time(pickup) <=
std::ceil(t * (1.0 + pickup_to_delivery_relative_detour_limit))

אם צוינו מגבלות יחסיות ומוחלטות באותה משלוח, המערכת תשתמש במגבלה המחמירה יותר לכל צמד אפשרי של איסוף/מסירה. החל מאוקטובר 2017, יש תמיכה במסלולי עקיפה רק כשמשך הנסיעה לא תלוי בסוג הרכב.

טען

כשמבצעים ביקור, סכום מוגדר מראש יכול להתווסף לעומס הרכב אם מדובר באיסוף עצמי, או להחסור ממנו אם מדובר במשלוח. הסכום הזה מוגדר בהודעה הזו. load_demands.

שדות
amount

int64

הסכום שלפיו העומס ברכב שבו מתבצע הביקור המתאים ישתנה. מכיוון שמדובר במספר שלם, מומלץ למשתמשים לבחור יחידה מתאימה כדי למנוע אובדן דיוק. הערך חייב להיות ≥ 0.

VisitRequest

בקשה לביקור שאפשר לבצע ברכב: יש לה מיקום גיאוגרפי (או שניים, ראו בהמשך), שעות פתיחה וסגירה שמיוצגות על ידי חלונות זמן ומשך זמן השירות (הזמן שהרכב נמצא במקום לאחר שהוא הגיע לאיסוף או להעברת סחורות).

שדות
arrival_location

LatLng

המיקום הגיאוגרפי שאליו מגיע הרכב במהלך ביצוע ה-VisitRequest הזה. אם למודל המשלוח יש מטריצות של משך זמן ומרחק, אסור לציין את arrival_location.
arrival_waypoint

Waypoint

נקודת הדרך שבה הרכב מגיע כשמבצעים את ה-VisitRequest הזה. אם למודל המשלוח יש מטריצות של משך זמן ומרחק, אסור לציין את arrival_waypoint.
departure_location

LatLng

המיקום הגיאוגרפי שבו הרכב יוצא לאחר השלמת הVisitRequest הזה. אפשר להשמיט אותו אם הוא זהה ל-arrival_location. אם למודל המשלוח יש מטריצות של משך זמן ומרחק, אסור לציין את departure_location.
departure_waypoint

Waypoint

נקודת הציון שממנה הרכב יוצא אחרי השלמת VisitRequest הזה. אפשר להשמיט אותו אם הוא זהה ל-arrival_waypoint. אם למודל המשלוח יש מטריצות של משך זמן ומרחק, אסור לציין את departure_waypoint.
tags[]

string

מציין את התגים שמצורפים לבקשת הביקור. אסור להשתמש במחרוזות ריקות או כפולות.
time_windows[]

TimeWindow

חלונות זמן שמגבילים את זמן ההגעה לביקור. לתשומת ליבכם, כלי רכב עשוי לצאת מחוץ לחלון הזמן של שעת ההגעה, כלומר שעת ההגעה + משך הנסיעה לא חייבים להיות בתוך חלון זמן. אם הרכב יגיע לפני TimeWindow.start_time, יכול להיות שתצטרכו להמתין.

אם השדה TimeWindow לא מופיע, המשמעות היא שהרכב יכול לבצע את הביקור הזה בכל שלב.

חלונות הזמן חייבים להיות נפרדים, כלומר חלון זמן אחד לא יכול לחופף לחלון זמן אחר או להיות צמוד אליו, והם חייבים להיות בסדר עולה.

אפשר להגדיר את cost_per_hour_after_soft_end_time ו-soft_end_time רק אם יש חלון זמן אחד.
duration

Duration

משך הביקור, כלומר הזמן שחלף מהגעת הרכב עד ליציאה שלו (צריך להוסיף את זמן ההמתנה האפשרי, ראו time_windows).
cost

double

העלות של טיפול בבקשה הזו לביקור במסלול של כלי רכב. אפשר להשתמש באפשרות הזו כדי לשלם עלויות שונות לכל אחת מהאפשרויות החלופיות לאיסוף או למשלוח של משלוח. העלות הזו צריכה להיות באותה יחידה כמו Shipment.penalty_cost, והיא לא יכולה להיות שלילית.
load_demands

map<string, Load>

דרישות העומס של בקשת הביקור הזו. השדה הזה דומה לשדה Shipment.load_demands, אבל הוא חל רק על VisitRequest הזה במקום על כל Shipment. הדרישות שמפורטות כאן מתווספות לדרישות שמפורטות בקובץ Shipment.load_demands.
visit_types[]

string

מציין את סוגי הביקורים. אפשר להשתמש בנתון הזה כדי להקצות זמן נוסף שנדרש לרכב כדי להשלים את הביקור הזה (ראו Vehicle.extra_visit_duration_for_visit_type).

סוג יכול להופיע רק פעם אחת.
label

string

תווית של VisitRequest. התווית הזו מדווחת בתגובה כ-visit_label ב-ShipmentRoute.Visit התואם.

ShipmentModel

מודל משלוח מכיל קבוצה של משלוחים שצריך לבצע באמצעות קבוצה של כלי רכב, תוך צמצום העלות הכוללת, שהיא הסכום של:

  • העלות של ניתוב כלי הרכב (סכום העלות לכל משך זמן, העלות לכל זמן נסיעה והעלות הקבועה בכל כלי הרכב).
  • את הקנסות על משלוחים שלא בוצעו.
  • העלות של משך הזמן הכולל של המשלוחים
שדות
shipments[]

Shipment

קבוצת משלוחים שצריך לבצע במודל.
vehicles[]

Vehicle

קבוצה של כלי רכב שאפשר להשתמש בהם לביצוע ביקורים.
global_start_time

Timestamp

שעת ההתחלה ושעת הסיום הגלובלית של המודל: לא ניתן להתייחס לשעות מחוץ לטווח הזה כחוקיות.

טווח הזמן של המודל צריך להיות פחות משנה, כלומר הערכים של global_end_time ו-global_start_time צריכים להיות במרחק של 31,536,000 שניות זה מזה.

כשמשתמשים בשדות cost_per_*hour, מומלץ להגדיר את החלון הזה למרווח זמן קטן יותר כדי לשפר את הביצועים (לדוגמה, אם יוצרים מודל ליום אחד, צריך להגדיר את מגבלות הזמן הגלובליות לאותו יום). אם לא מגדירים את השדה, המערכת תשתמש בערך ברירת המחדל 00:00:00 UTC, 1 בינואר 1970 (כלומר, שניות: 0, ננו-שניות: 0).
global_end_time

Timestamp

אם לא מגדירים ערך, המערכת משתמשת בערך ברירת המחדל 00:00:00 UTC, 1 בינואר 1971 (כלומר, שניות: 31536000, ננו-שניות: 0).
global_duration_cost_per_hour

double

'משך הזמן הגלובלי' של התוכנית הכוללת הוא ההפרש בין שעת ההתחלה היעילה המוקדמת ביותר לשעת הסיום היעילה האחרונה של כל הרכבים. המשתמשים יכולים להקצות עלות לשעה לכמות הזו כדי לנסות לבצע אופטימיזציה להשגת השלמת המשימה המהירה ביותר, לדוגמה. העלות הזו צריכה להיות באותה יחידה כמו Shipment.penalty_cost.
duration_distance_matrices[]

DurationDistanceMatrix

מציין את מטריצות משך הזמן והמרחקים שמשמשות במודל. אם השדה הזה ריק, המערכת תשתמש במקום זאת במפות Google או במרחקים גיאודזיים, בהתאם לערך של השדה use_geodesic_distances. אם הוא לא ריק, הערך של use_geodesic_distances לא יכול להיות True, וגם הערך של duration_distance_matrix_src_tags וגם הערך של duration_distance_matrix_dst_tags לא יכולים להיות ריקים.

דוגמאות לשימוש:

  • יש שני מיקומים: locA ו-locB.
  • רכב אחד שמתחיל את המסלול ב-locA ומסתיים ב-locA.
  • בקשה אחת לאיסוף ב-locB.
model {
  vehicles { start_tags: "locA"  end_tags: "locA" }
  shipments { pickups { tags: "locB" } }
  duration_distance_matrix_src_tags: "locA"
  duration_distance_matrix_src_tags: "locB"
  duration_distance_matrix_dst_tags: "locA"
  duration_distance_matrix_dst_tags: "locB"
  duration_distance_matrices {
    rows {  # from: locA
      durations { seconds: 0 }   meters: 0    # to: locA
      durations { seconds: 100 } meters: 1000 # to: locB
    }
    rows {  # from: locB
      durations { seconds: 102 } meters: 990 # to: locA
      durations { seconds: 0 }   meters: 0   # to: locB
    }
  }
}
  • יש שלושה מיקומים: locA, ‏ locB ו-locC.
  • כלי רכב אחד שמתחיל את המסלול ב-locA ומסתיים ב-locB, באמצעות המטריצה 'מהיר'.
  • רכב אחד שמתחיל את המסלול ב-locB ומסתיים ב-locB, באמצעות המטריצה 'איטי'.
  • רכב אחד שמתחיל את המסלול ב-locB ומסתיים ב-locB, באמצעות המטריצה 'מהיר'.
  • בקשה אחת לאיסוף עצמי ב-locC.
model {
  vehicles { start_tags: "locA" end_tags: "locB" start_tags: "fast" }
  vehicles { start_tags: "locB" end_tags: "locB" start_tags: "slow" }
  vehicles { start_tags: "locB" end_tags: "locB" start_tags: "fast" }
  shipments { pickups { tags: "locC" } }
  duration_distance_matrix_src_tags: "locA"
  duration_distance_matrix_src_tags: "locB"
  duration_distance_matrix_src_tags: "locC"
  duration_distance_matrix_dst_tags: "locB"
  duration_distance_matrix_dst_tags: "locC"
  duration_distance_matrices {
    vehicle_start_tag: "fast"
    rows {  # from: locA
      durations { seconds: 1000 } meters: 2000 # to: locB
      durations { seconds: 600 }  meters: 1000 # to: locC
    }
    rows {  # from: locB
      durations { seconds: 0 }   meters: 0    # to: locB
      durations { seconds: 700 } meters: 1200 # to: locC
    }
    rows {  # from: locC
      durations { seconds: 702 } meters: 1190 # to: locB
      durations { seconds: 0 }   meters: 0    # to: locC
    }
  }
  duration_distance_matrices {
    vehicle_start_tag: "slow"
    rows {  # from: locA
      durations { seconds: 1800 } meters: 2001 # to: locB
      durations { seconds: 900 }  meters: 1002 # to: locC
    }
    rows {  # from: locB
      durations { seconds: 0 }    meters: 0    # to: locB
      durations { seconds: 1000 } meters: 1202 # to: locC
    }
    rows {  # from: locC
      durations { seconds: 1001 } meters: 1195 # to: locB
      durations { seconds: 0 }    meters: 0    # to: locC
    }
  }
}
duration_distance_matrix_src_tags[]

string

תגים שמגדירים את המקורות של מטריצות המרחק והמשך הזמן. הערך duration_distance_matrices(i).rows(j) מגדיר את משכי הזמן והמרחקים מביקורים עם התג duration_distance_matrix_src_tags(j) לביקורים אחרים במטריצה i.

התגים תואמים ל-VisitRequest.tags או ל-Vehicle.start_tags. VisitRequest או Vehicle נתון חייב להתאים לתג אחד בלבד בשדה הזה. שימו לב: ייתכן שתג המקור, תג היעד ותג המטריצה של Vehicle יהיו זהים. באופן דומה, ייתכן שתג המקור ותג היעד של VisitRequest יהיו זהים. כל התגים חייבים להיות שונים ולא יכולים להיות מחרוזות ריקות. אם השדה הזה לא ריק, השדה duration_distance_matrices לא יכול להיות ריק.
duration_distance_matrix_dst_tags[]

string

תגים שמגדירים את היעדים של מטריצות משך הזמן והמרחק. duration_distance_matrices(i).rows(j).durations(k) (resp. duration_distance_matrices(i).rows(j).meters(k)) מגדיר את משך הנסיעה (או המרחק) מביקורים עם התג duration_distance_matrix_src_tags(j) לביקורים עם התג duration_distance_matrix_dst_tags(k) במטריצה i.

התגים תואמים ל-VisitRequest.tags או ל-Vehicle.start_tags. VisitRequest או Vehicle נתון חייב להתאים לתג אחד בלבד בשדה הזה. שימו לב: ייתכן שתג המקור, תג היעד ותג המטריצה של Vehicle יהיו זהים. באופן דומה, ייתכן שתג המקור ותג היעד של VisitRequest יהיו זהים. כל התגים חייבים להיות שונים ולא יכולים להיות מחרוזות ריקות. אם השדה הזה לא ריק, השדה duration_distance_matrices לא יכול להיות ריק.
transition_attributes[]

TransitionAttributes

מאפייני המעבר נוספו למודל.
shipment_type_incompatibilities[]

ShipmentTypeIncompatibility

קבוצות של shipment_types לא תואמים (ראו ShipmentTypeIncompatibility).
shipment_type_requirements[]

ShipmentTypeRequirement

קבוצות של דרישות shipment_type (ראו ShipmentTypeRequirement).
precedence_rules[]

PrecedenceRule

קבוצת כללי עדיפות שצריך לאכוף במודל.
max_active_vehicles

int32

מגביל את המספר המקסימלי של כלי רכב פעילים. רכב נחשב לפעיל אם בוצעה בו לפחות משלוח אחד במסלול שלו. אפשר להשתמש באפשרות הזו כדי להגביל את מספר המסלולים במקרה שיש פחות נהגים מכלי רכב, וכי צי הרכבים הוא הטרוגני. לאחר מכן, המערכת תבצע אופטימיזציה כדי לבחור את קבוצת המשנה הטובה ביותר של כלי הרכב לשימוש. חייב להיות חיובי באופן מוחלט.

DurationDistanceMatrix

מציין מטריצה של משך זמן ומרחק מנקודת ההתחלה של הביקור והרכב ועד לנקודת הסיום של הביקור והרכב.

שדות
rows[]

Row

מציין את השורות של מטריצות משך הזמן והמרחק. הוא חייב להכיל את אותו מספר רכיבים כמו ShipmentModel.duration_distance_matrix_src_tags.
vehicle_start_tag

string

תג שמגדיר לאילו כלי רכב חלה מטריצת משך הזמן והמרחק הזו. אם השדה ריק, הוא חל על כל כלי הרכב, וניתן להשתמש רק במטריצה אחת.

כל התחלה של כלי רכב חייבת להתאים למטריצה אחת בלבד, כלומר אחד מהשדות start_tags שלה חייב להתאים ל-vehicle_start_tag של מטריצה (ולמטריצה הזו בלבד).

לכל המטריצות צריך להיות vehicle_start_tag שונה.

שורה

מציין שורה במטריצה של משך הזמן והמרחק.

שדות
durations[]

Duration

ערכי משך הזמן בשורה נתונה. הוא חייב להכיל את אותו מספר רכיבים כמו ShipmentModel.duration_distance_matrix_dst_tags.
meters[]

double

ערכי המרחק בשורה נתונה. אם אין עלויות או אילוצים שמפנים למרחקים במודל, אפשר להשאיר את השדה הזה ריק. אחרת, צריך לכלול בו כמה אלמנטים כמו durations.

PrecedenceRule

כלל עדיפות בין שני אירועים (כל אירוע הוא איסוף או מסירה של משלוח): האירוע 'שני' צריך להתחיל לפחות offset_duration אחרי שהאירוע 'ראשון' התחיל.

כמה סדרי עדיפויות יכולים להתייחס לאותו אירוע (או לאירועים קשורים), למשל: "האיסוף של B מתרחש אחרי המסירה של A" ו "האיסוף של C מתרחש אחרי האיסוף של B".

בנוסף, העדיפויות חלות רק כששתי ההעברות מתבצעות, אחרת הן מתעלמות.

שדות
first_is_delivery

bool

מציין אם האירוע 'ראשון' הוא העברה.
second_is_delivery

bool

מציין אם האירוע 'שני' הוא מסירה.
offset_duration

Duration

ההיסט בין האירוע 'ראשון' לבין האירוע 'שני'. הערך יכול להיות שלילי.
first_index

int32

אינדקס המשלוח של האירוע 'ראשון'. חובה לציין את השדה הזה.
second_index

int32

אינדקס המשלוח של האירוע 'שני'. חובה לציין את השדה הזה.

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

חשוב לדעת שיש הבדל בין:

  • 'אירועים מדויקים', כמו תחילת הנסיעה וסיום הנסיעה ותחילת הביקור וסיום הביקור (כלומר הגעה ויציאה). הם מתרחשים בשנייה נתונה.
  • 'מרווחי זמן', כמו הביקורים עצמם והמעבר בין הביקורים. לפעמים מרווחי הזמן יכולים להיות באורך אפס, כלומר להתחיל ולהסתיים באותה שנייה, אבל לרוב הם באורך חיובי.

Invariants:

  • אם יש 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

לסיום, כך אפשר לסדר את האירועים 'נסיעה', 'הפסקות', 'עיכוב' ו'המתנה' במהלך מעבר.

  • הן לא חופפות.
  • הערך של DELAY הוא ייחודי וחייב להיות תקופה רציפה של זמן ממש לפני הביקור הבא (או סיום הנסיעה ברכב). לכן, מספיק לדעת את משך העיכוב כדי לדעת את שעת ההתחלה והסיום שלו.
  • ההפסקות הן תקופות זמן רצופות ולא חופפות. התגובה מציינת את שעת ההתחלה ואת משך הזמן של כל הפסקה.
  • האירועים 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     |       |           |         |         ||
  ||     |       |           |       |           |         |         ||
--++-----------------------------------------------------------------++-->
שדות
vehicle_index

int32

הרכב שמבצע את המסלול, שמזוהה לפי האינדקס שלו במקור ShipmentModel.
vehicle_label

string

התווית של הרכב שמבצע את המסלול הזה, שווה ל-ShipmentModel.vehicles(vehicle_index).label, אם צוין.
vehicle_start_time

Timestamp

השעה שבה הרכב מתחיל את המסלול.
vehicle_end_time

Timestamp

השעה שבה הרכב מסיים את המסלול.
visits[]

Visit

רצף מסודר של ביקורים שמייצג מסלול. visits[i] הוא הביקור ה-i במסלול. אם השדה הזה ריק, הרכב נחשב ללא בשימוש.
transitions[]

Transition

רשימה מסודרת של מעברים במסלול.
has_traffic_infeasibilities

bool

כשהערך של OptimizeToursRequest.consider_road_traffic מוגדר כ-true, השדה הזה מציין שחוסר עקביות בזמני המסלולים משוער באמצעות אומדני משך הנסיעה שמבוססים על תנועה. יכול להיות שלא יהיה מספיק זמן להשלים את הנסיעה, ההשהיות וההפסקות בין הביקורים, בהתאם לתנועה, לפני הביקור הראשון או אחרי הביקור האחרון, ועדיין לעמוד בחלונות הזמנים של הביקור והרכב. לדוגמה,

  start_time(previous_visit) + duration(previous_visit) +
  travel_duration(previous_visit, next_visit) > start_time(next_visit)

סביר להניח שהגעה ל-next_visit תתרחש מאוחר יותר מחלון הזמן הנוכחי שלה בגלל האומדן המוגדל של זמן הנסיעה travel_duration(previous_visit, next_visit) עקב תנועה. בנוסף, יכול להיות שההפסקה תחפוף לביקור בגלל עלייה באומדני זמני הנסיעה והגבלות על חלון הזמן של הביקור או ההפסקה.
route_polyline

EncodedPolyline

ייצוג הפוליגון המקודד של המסלול. השדה הזה מאוכלס רק אם השדה OptimizeToursRequest.populate_polylines מוגדר כ-true.
breaks[]

Break

ההפסקות שתוזמנו לרכב שמבצע את המסלול הזה. הרצף breaks מייצג מרווחי זמן, שכל אחד מהם מתחיל ב-start_time התואם ונמשך duration שניות.
metrics

AggregatedMetrics

מדדי משך הזמן, המרחק והעומס במסלול הזה. השדות של AggregatedMetrics מסכמים את כל ShipmentRoute.transitions או ShipmentRoute.visits, בהתאם להקשר.
route_costs

map<string, double>

העלות של המסלול, לפי פירוט בשדות הבקשה שקשורים לעלויות. המפתחות הם נתיבים של פרוטו, ביחס לקלט OptimizeToursRequest, למשל 'model.shipments.pickups.cost', והערכים הם העלות הכוללת שנוצרה על ידי שדה העלות התואם, שנצברה לאורך המסלול כולו. במילים אחרות, costs["model.shipments.pickups.cost"] הוא הסכום של כל עלויות האיסוף במסלול. כל העלויות שמוגדרות במודל מדווחות כאן בפירוט, למעט עלויות שקשורות ל-TransitionAttributes שמדווחות רק באופן מצטבר החל מינואר 2022.
route_total_cost

double

העלות הכוללת של המסלול. הסכום של כל העלויות במפת העלויות.

הפסקה

נתונים שמייצגים את הביצוע של הפסקה.

שדות
start_time

Timestamp

שעת ההתחלה של ההפסקה.
duration

Duration

משך ההפסקה.

EncodedPolyline

הייצוג המקודד של קו מרובה. מידע נוסף על קידוד קווים פוליגונים זמין כאן: https://developers.google.com/maps/documentation/utilities/polylinealgorithm https://developers.google.com/maps/documentation/javascript/reference/geometry#encoding.

שדות
points

string

מחרוזת שמייצגת נקודות מקודדות של הקו המורכב.

מעבר

מעבר בין שני אירועים במסלול. אפשר לעיין בתיאור של ShipmentRoute.

אם לרכב אין start_location ו/או end_location, מדדי הנסיעה התואמים יהיו 0.

שדות
travel_duration

Duration

משך הנסיעה במהלך המעבר.
travel_distance_meters

double

המרחק שעברתם במהלך המעבר.
traffic_info_unavailable

bool

כשמבקשים מידע על תנועה דרך OptimizeToursRequest.consider_road_traffic ולא ניתן לאחזר את פרטי התנועה של Transition, הערך של המשתנה הבוליאני הזה מוגדר כ-true. יכול להיות שהבעיה זמנית (תקלה נדירה בשרתי התנועה בזמן אמת) או קבועה (אין נתונים לגבי המיקום הזה).
delay_duration

Duration

סכום משך הזמן של העיכובים שחלים על המעבר הזה. אם יש עיכוב, הוא מתחיל בדיוק delay_duration שניות לפני האירוע הבא (ביקור או סיום נסיעה). TransitionAttributes.delay.
break_duration

Duration

סכום משך ההפסקות שהתרחשו במהלך המעבר הזה, אם היו כאלה. פרטים על שעת ההתחלה והמשך של כל הפסקה נשמרים ב-ShipmentRoute.breaks.
wait_duration

Duration

משך הזמן שהמתנתם במהלך המעבר. משך ההמתנה תואם לזמן ההמתנה ללא פעילות, ולא כולל את זמן ההפסקה. חשוב גם לזכור שזמן ההמתנה הזה עשוי להתחלק למספר מקטעים לא רציפים.
total_duration

Duration

משך המעבר הכולל, לצורך נוחות. הוא שווה ל-:

  • הביקור הבא start_time (או vehicle_end_time אם זהו המעבר האחרון) – start_time של המעבר הזה.
  • אם הערך של ShipmentRoute.has_traffic_infeasibilities הוא false, נוסחה נוספת תקפה: ‎total_duration = travel_duration + delay_duration
  • break_duration + wait_duration`.
start_time

Timestamp

שעת ההתחלה של המעבר הזה.
route_polyline

EncodedPolyline

ייצוג הקוד של הקו הפוליגוני של המסלול שבו נעשה שימוש במהלך המעבר. השדה הזה מאוכלס רק אם השדה populate_transition_polylines מוגדר כ-true.
route_token

string

פלט בלבד. אסימון אטום שאפשר להעביר ל-Navigation SDK כדי לשחזר את המסלול במהלך הניווט, ובמקרה של שינוי מסלול, לשמור על הכוונה המקורית שלכם כשיצרתם את המסלול. מתייחסים לאסימון הזה כאל blob אטום. אין להשוות את הערך שלו בין בקשות שונות, כי הערך עשוי להשתנות גם אם השירות מחזיר את אותו מסלול בדיוק. השדה הזה מאוכלס רק אם השדה populate_transition_polylines מוגדר כ-true.
vehicle_loads

map<string, VehicleLoad>

עומסי הרכב במהלך המעבר הזה, לכל סוג שמופיע ב-Vehicle.load_limits של הרכב הזה, או שיש לו Shipment.load_demands שאינו אפס בשליחה כלשהי שבוצעה במסלול הזה.

העומסים במהלך המעבר הראשון הם העומסים ההתחלתיים של מסלול הרכב. לאחר מכן, אחרי כל ביקור, הערכים של load_demands של הביקור מתווספים או מוחרגים כדי לקבל את העומסים של המעבר הבא, בהתאם לכך אם הביקור היה איסוף או משלוח.

VehicleLoad

דיווח על העומס בפועל של הרכב בשלב כלשהו במסלול, לסוג נתון (ראו Transition.vehicle_loads).

שדות
amount

int64

עומס הרכב, לפי הסוג הנתון. בדרך כלל, סוג היחידה של העומס מצוין. Transition.vehicle_loads.

כניסה

ביקור שבוצע במהלך מסלול. הביקור הזה תואם לאיסוף או למשלוח של Shipment.

שדות
shipment_index

int32

אינדקס השדה shipments במקור ShipmentModel.
is_pickup

bool

אם הערך הוא True, הביקור תואם לאיסוף של Shipment. אחרת, הוא תואם למשלוח.
visit_request_index

int32

האינדקס של VisitRequest בשדה של האיסוף או המשלוח ב-Shipment (ראו is_pickup).
start_time

Timestamp

השעה שבה מתחיל הביקור. חשוב לדעת שהרכב עשוי להגיע למיקום הביקור לפני המועד הזה. השעות תואמות לShipmentModel.
load_demands

map<string, Load>

הביקוש הכולל לטעינת ביקורים כסכום של המשלוח ובקשת הביקור load_demands. הערכים יהיו שליליים אם הביקור הוא מסירה. הבקשות מדווחות באותו סוג כמו השדה Transition.loads (ראו את השדה הזה).
detour

Duration

זמן עיקוף נוסף עקב המשלוח שנבדק במסלול לפני הביקור ועקב זמן ההמתנה הפוטנציאלי שנגרם בגלל חלונות הזמן. אם הביקור הוא מסירה, הסטייה מחושבת מהביקור התואם לאיסוף והיא שווה ל:

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

אחרת, הוא מחושב מהרכב start_location והוא שווה ל:

start_time - vehicle_start_time - travel duration from
the vehicle's `start_location` to the visit.
shipment_label

string

עותק של Shipment.label התואם, אם הוא צוין ב-Shipment.
visit_label

string

עותק של VisitRequest.label התואם, אם הוא צוין ב-VisitRequest.

ShipmentTypeIncompatibility

מציין אי-תאימות בין משלוחים בהתאם ל-shipment_type שלהם. הצגת משלוחים לא תואמים באותו מסלול מוגבלת על סמך מצב אי-התאימות.

שדות
types[]

string

רשימה של סוגים לא תואמים. שתי משלוחים עם shipment_types שונה מאלה שרשומים הם 'לא תואמים'.
incompatibility_mode

IncompatibilityMode

המצב שחלה על חוסר התאימות.

IncompatibilityMode

מצבים שמגדירים את האופן שבו מוצגות משלוחים לא תואמים באותו מסלול.

טיפוסים בני מנייה (enum)
INCOMPATIBILITY_MODE_UNSPECIFIED מצב אי-תאימות לא מוגדר. אין להשתמש בערך הזה אף פעם.
NOT_PERFORMED_BY_SAME_VEHICLE במצב הזה, אף פעם לא ניתן לשתף את אותו רכב בין שתי משלוחים עם סוגים לא תואמים.
NOT_IN_SAME_VEHICLE_SIMULTANEOUSLY

בשתי משלוחים עם סוגים לא תואמים במצב אי-תאימות NOT_IN_SAME_VEHICLE_SIMULTANEOUSLY:

  • אם שני העסקים הם רק לאיסוף (ללא משלוחים) או רק למשלוחים (ללא איסופים), אי אפשר לשתף ביניהם את אותו רכב בכלל.
  • אם אחת מהמשלוחים היא מסוג 'איסוף' והשני הוא מסוג 'העברה', שתי המשלוחים יכולים להשתמש באותו רכב רק אם המשלוח הראשון יועבר לפני שהמשלוח השני ייאסף.

ShipmentTypeRequirement

מציין את הדרישות בין משלוחים על סמך shipment_type שלהם. הפרטים הספציפיים של הדרישה מוגדרים לפי מצב הדרישה.

שדות
required_shipment_type_alternatives[]

string

רשימה של סוגי משלוחים חלופיים הנדרשים על ידי dependent_shipment_types.
dependent_shipment_types[]

string

בכל המשלוחים עם סוג בשדה dependent_shipment_types, צריך לבקר לפחות במשלוח אחד מסוג required_shipment_type_alternatives באותו מסלול.

הערה: אסור ליצור שרשראות של דרישות שבהן shipment_type תלויה בעצמה.
requirement_mode

RequirementMode

המצב שחלה על הדרישה.

RequirementMode

מצבים שמגדירים את המראה של משלוחים תלויים במסלול.

טיפוסים בני מנייה (enum)
REQUIREMENT_MODE_UNSPECIFIED מצב דרישה לא מוגדר. אין להשתמש בערך הזה אף פעם.
PERFORMED_BY_SAME_VEHICLE במצב הזה, כל המשלוחים 'התלויים' חייבים לשתף את אותו רכב עם לפחות אחד מהמשלוחים 'החובה' שלהם.
IN_SAME_VEHICLE_AT_PICKUP_TIME

במצב IN_SAME_VEHICLE_AT_PICKUP_TIME, בכל משלוח 'תלוי' צריך להיות לפחות משלוח 'נדרש' אחד ברכב בזמן האיסוף.

לכן, לאיסוף משלוח 'תלוי' צריך להיות:

  • משלוח 'נדרש' למשלוח בלבד שנמסר במסלול אחרי, או
  • משלוח 'נדרש' שנאסף במסלול לפניו, ואם למשלוח 'נדרש' יש מסירה, המסירה הזו חייבת להתבצע אחרי האיסוף של המשלוח 'התלוי'.
IN_SAME_VEHICLE_AT_DELIVERY_TIME זהה לקודם, מלבד העובדה שבמשלוחים 'תלויים' צריך להיות משלוח 'נדרש' ברכב בזמן המסירה.

SkippedShipment

פרטים על משלוחים שלא בוצעו בפתרון. במקרים טריוויאליים ו/או אם אנחנו מצליחים לזהות את הסיבה לדילוג, אנחנו מדווחים על הסיבה כאן.

שדות
index

int32

האינדקס תואם לאינדקס של המשלוח במקור ShipmentModel.
label

string

עותק של Shipment.label התואם, אם הוא צוין ב-Shipment.
reasons[]

Reason

רשימה של סיבות שמסבירות למה המשלוח נדחה. עיינו בתגובה שלמעלה של Reason. אם לא נוכל להבין למה משלוח עבר על פני סטטוס מסוים, לא נגדיר סיבות.

סיבה

אם נוכל להסביר למה ההזמנה לא נשלחה, הסיבות יופיעו כאן. אם הסיבה לא זהה לכל כלי הרכב, ל-reason יהיה יותר מרכיב אחד. לא ניתן לציין סיבות כפולות למשלוח שעבר דילוג, כלומר, אם כל השדות זהים מלבד השדה example_vehicle_index. דוגמה:

reasons {
  code: DEMAND_EXCEEDS_VEHICLE_CAPACITY
  example_vehicle_index: 1
  example_exceeded_capacity_type: "Apples"
}
reasons {
  code: DEMAND_EXCEEDS_VEHICLE_CAPACITY
  example_vehicle_index: 3
  example_exceeded_capacity_type: "Pears"
}
reasons {
  code: CANNOT_BE_PERFORMED_WITHIN_VEHICLE_DISTANCE_LIMIT
  example_vehicle_index: 1
}

המשלוח שהושמט לא תואם לכל הרכבים. הסיבות עשויות להיות שונות בכל רכב, אבל תהיה חריגה ממכסת ה'תפוזים' לפחות ברכב אחד (כולל רכב 1), תהיה חריגה ממכסת ה'אגסים' לפחות ברכב אחד (כולל רכב 3) ותהיה חריגה ממגבלת המרחק לפחות ברכב אחד (כולל רכב 1).

שדות
code

Code

אפשר לעיין בהערות של Code.
example_exceeded_capacity_type

string

אם קוד הסיבה הוא DEMAND_EXCEEDS_VEHICLE_CAPACITY, המסמך מתעד סוג אחד של קיבולת שחורגת מהמכסה.
example_vehicle_index

int32

אם הסיבה קשורה לכך שהרכב לא מתאים לשליחה, בשדה הזה יצוין המדד של רכב רלוונטי אחד.

קוד

קוד שמזהה את סוג הסיבה. הסדר כאן לא רלוונטי. באופן ספציפי, הוא לא מציין אם סיבה מסוימת תופיע לפני סיבה אחרת בפתרון, אם שתיהן רלוונטיות.

טיפוסים בני מנייה (enum)
CODE_UNSPECIFIED אין להשתמש באפשרות הזו אף פעם.
NO_VEHICLE אין כלי רכב במודל, ולכן אי אפשר לבצע את כל המשלוחים.
DEMAND_EXCEEDS_VEHICLE_CAPACITY הביקוש להובלה חורג מהקיבולת של הרכב בחלק מסוגי הקיבולת, אחד מהם הוא example_exceeded_capacity_type.
CANNOT_BE_PERFORMED_WITHIN_VEHICLE_DISTANCE_LIMIT

המרחק המינימלי הנדרש לביצוע המשלוח הזה, כלומר מה-start_location של הרכב למיקומי האיסוף ו/או המסירה של המשלוח ולמיקום הסופי של הרכב, חורג מ-route_distance_limit של הרכב.

שימו לב שבחישוב הזה אנחנו משתמשים במרחקים הגיאודזיים.
CANNOT_BE_PERFORMED_WITHIN_VEHICLE_DURATION_LIMIT

הזמן המינימלי הנדרש לביצוע המשלוח הזה, כולל זמן הנסיעה, זמן ההמתנה וזמן הטיפול, חורג מ-route_duration_limit של הרכב.

הערה: זמן הנסיעה מחושב לפי התרחיש הטוב ביותר, כלומר המרחק הגיאודטי x 36 מ' לשנייה (כ-130 קמ' לשעה).
CANNOT_BE_PERFORMED_WITHIN_VEHICLE_TRAVEL_DURATION_LIMIT כמו למעלה, אבל אנחנו משווים רק את זמן הנסיעה המינימלי ל-travel_duration_limit של הרכב.
CANNOT_BE_PERFORMED_WITHIN_VEHICLE_TIME_WINDOWS הרכב לא יכול לבצע את המשלוח הזה בתרחיש הטוב ביותר (לחישוב הזמן, אפשר לעיין בקטע CANNOT_BE_PERFORMED_WITHIN_VEHICLE_DURATION_LIMIT) אם הוא יתחיל בשעת ההתחלה המוקדמת ביותר שלו: הזמן הכולל יגרום לרכב לסיים את המסירה אחרי שעת הסיום המאוחרת ביותר שלו.
VEHICLE_NOT_ALLOWED השדה allowed_vehicle_indices של המשלוח לא ריק והרכב הזה לא שייך אליו.

TimeWindow

חלונות זמן מגבילים את הזמן של אירוע, כמו שעת ההגעה לביקור או שעת ההתחלה והסיום של כלי רכב.

גבולות קשיחים של חלון הזמן, start_time ו-end_time, אוכפים את השעה המוקדמת ביותר ואת השעה המאוחרת ביותר של האירוע, כך ש-start_time <= event_time <= end_time. הערך התחתון של חלון הזמן הרך, soft_start_time, מבטא העדפה שהאירוע יתרחש ב-soft_start_time או אחריו, על ידי חיוב בעלות שפרופורציונלית לזמן שחולף לפני soft_start_time עד שהאירוע מתרחש. כדי להביע עדיפות שהאירוע יתרחש ב-soft_end_time או לפני כן, המערכת מחייבת עלות שפרופורציונלית לזמן שחולף אחרי soft_end_time עד שהאירוע מתרחש. הגבול העליון של חלון הזמן הרך, soft_end_time, הוא הערך הזה. הערכים של start_time, ‏ end_time, ‏ soft_start_time ו-soft_end_time צריכים לעמוד במגבלות הזמן הגלובליות (ראו ShipmentModel.global_start_time ו-ShipmentModel.global_end_time) ולעמוד בדרישות הבאות:

  0 <= `start_time` <= `end_time` and
  0 <= `start_time` <= `soft_start_time` and
  0 <= `soft_end_time` <= `end_time`.
שדות
start_time

Timestamp

שעת ההתחלה של חלון הזמן הקבוע. אם לא צוין ערך, הוא יוגדר כ-ShipmentModel.global_start_time.
end_time

Timestamp

שעת הסיום של חלון הזמנים הקפדני. אם לא צוין ערך, הוא יוגדר כ-ShipmentModel.global_end_time.
soft_start_time

Timestamp

שעת ההתחלה הרכה של חלון הזמן.
soft_end_time

Timestamp

שעת הסיום המשוערת של חלון הזמן.
cost_per_hour_before_soft_start_time

double

עלות לשעה שנוספת לעלויות אחרות במודל אם האירוע מתרחש לפני soft_start_time, מחושבת לפי הנוסחה הבאה:

   max(0, soft_start_time - t.seconds)
                          * cost_per_hour_before_soft_start_time / 3600,
t being the time of the event.

העלות הזו חייבת להיות חיובית, וניתן להגדיר את השדה רק אם מוגדר soft_start_time.
cost_per_hour_after_soft_end_time

double

עלות לשעה שנוספת לעלויות אחרות במודל אם האירוע מתרחש אחרי soft_end_time, מחושבת לפי הנוסחה הבאה:

   max(0, t.seconds - soft_end_time.seconds)
                    * cost_per_hour_after_soft_end_time / 3600,
t being the time of the event.

העלות הזו חייבת להיות חיובית, וניתן להגדיר את השדה רק אם soft_end_time הוגדר.

TransitionAttributes

מציין מאפיינים של מעברים בין שני ביקורים רצופים במסלול. יכול להיות שיהיו כמה TransitionAttributes שחלים על אותו מעבר: במקרה כזה, כל העלויות הנוספות מצטברות והגבלה או האילוץ המחמירים ביותר חלים (בהתאם לסמנטיקה הטבעית של 'וגם').

שדות
src_tag

string

תגים שמגדירים את קבוצת המעברים (src->dst) שהמאפיינים האלה חלים עליהם.

ביקור במקור או התחלת נסיעה ברכב תואמים אם השדה VisitRequest.tags או Vehicle.start_tags מכיל את הערך src_tag או לא מכיל את הערך excluded_src_tag (בהתאם לשדה מבין שני השדות האלה שהוא לא ריק).
excluded_src_tag

string

src_tag. בדיוק אחד מהשדות src_tag ו-excluded_src_tag חייב להיות לא ריק.
dst_tag

string

ביקור ביעד או סיום נסיעה תואמים אם השדה VisitRequest.tags או Vehicle.end_tags מכיל את הערך dst_tag או לא מכיל את הערך excluded_dst_tag (בהתאם לשדה מבין שני השדות האלה שהוא לא ריק).
excluded_dst_tag

string

dst_tag. בדיוק אחד מהשדות dst_tag ו-excluded_dst_tag חייב להיות לא ריק.
cost

double

העלויות של ביצוע המעבר הזה. הערך הזה הוא באותה יחידה כמו כל שאר העלויות במודל, אסור שהוא יהיה שלילי. הוא מחויב בנוסף לכל העלויות הקיימות האחרות.
cost_per_kilometer

double

קובע עלות לקילומטר שחלה על המרחק שנסע במהלך המעבר הזה. הוא מצטבר לכל Vehicle.cost_per_kilometer שצוין ברכב.
distance_limit

DistanceLimit

מציין מגבלה על המרחק שנסע במהלך המעבר הזה.

החל מיוני 2021, יש תמיכה רק במגבלות רכות.
delay

Duration

השדה הזה מציין את העיכוב שנוצר במהלך ביצוע המעבר הזה.

העיכוב הזה מתרחש תמיד אחרי סיום הביקור במקור ולפני תחילת הביקור ביעד.

כלי רכב

מודל של רכב בבעיה במשלוח. פתרון בעיה בשליחה יוצר מסלול עבור הרכב הזה שמתחיל ב-start_location ומסתיים ב-end_location. מסלול הוא רצף של ביקורים (מידע נוסף זמין במאמר ShipmentRoute).

שדות
display_name

string

השם המוצג של הרכב שהוגדר על ידי המשתמש. השם יכול להכיל עד 63 תווים, וניתן להשתמש בתווים של UTF-8.
travel_mode

TravelMode

מצב הנסיעה שמשפיע על הכבישים שבהם הרכב יכול לנסוע ועל המהירות שלו. מידע נוסף זמין במאמר travel_duration_multiple.
route_modifiers

RouteModifiers

קבוצת תנאים שצריך לעמוד בהם, שמשפיעה על האופן שבו מחושבים המסלולים לרכב הנתון.
start_location

LatLng

המיקום הגיאוגרפי שבו הרכב מתחיל לפני שהוא אוסף משלוחים. אם לא יצוין אחרת, הרכב יתחיל לפעול בנסיעה הראשונה. אם למודל המשלוח יש מטריצות של משך זמן ומרחק, אסור לציין את start_location.
start_waypoint

Waypoint

נקודת ציון שמייצגת מיקום גיאוגרפי שבו הרכב מתחיל לפני שהוא אוסף משלוחים. אם לא צוין start_waypoint או start_location, הרכב יופעל בנסיעה הראשונה. אם למודל המשלוח יש מטריצות של משך זמן ומרחק, אסור לציין את start_waypoint.
end_location

LatLng

המיקום הגיאוגרפי שבו הרכב מסתיים אחרי שהוא מסיים את VisitRequest האחרון. אם לא מציינים את הערך, ShipmentRoute של הרכב מסתיים מיד אחרי השלמת VisitRequest האחרון. אם למודל המשלוח יש מטריצות של משך זמן ומרחק, אסור לציין את end_location.
end_waypoint

Waypoint

נקודת ציון שמייצגת מיקום גיאוגרפי שבו הרכב מסתיים אחרי שהוא משלים את VisitRequest האחרון. אם לא מציינים את end_waypoint או את end_location, ShipmentRoute של הרכב מסתיים מיד אחרי השלמת VisitRequest האחרון. אם למודל המשלוח יש מטריצות של משך זמן ומרחק, אסור לציין את end_waypoint.
start_tags[]

string

מציין תגים שמצורפים לתחילת המסלול של הרכב.

אסור להשתמש במחרוזות ריקות או כפולות.
end_tags[]

string

ציון תגים שמצורפים לסוף המסלול של הרכב.

אסור להשתמש במחרוזות ריקות או כפולות.
start_time_windows[]

TimeWindow

חלונות זמן שבהם הרכב עשוי לצאת ממיקום ההתחלה. הם צריכים להיות בתוך מגבלות הזמן הגלובליות (ראו שדות ShipmentModel.global_*). אם לא צוין אחרת, אין הגבלה מלבד מגבלות הזמן הגלובליות האלה.

חלונות זמן ששייכים לאותו שדה חוזר חייבים להיות נפרדים, כלומר אף חלון זמן לא יכול להיות חופף לחלון זמן אחר או להיות צמוד אליו, והם חייבים להיות בסדר כרונולוגי.

אפשר להגדיר את cost_per_hour_after_soft_end_time ו-soft_end_time רק אם יש חלון זמן אחד.
end_time_windows[]

TimeWindow

חלונות זמן שבהם הרכב עשוי להגיע ליעד הסופי. הם צריכים להיות בתוך מגבלות הזמן הגלובליות (ראו שדות ShipmentModel.global_*). אם לא צוין אחרת, אין הגבלה מלבד מגבלות הזמן הגלובליות האלה.

חלונות זמן ששייכים לאותו שדה חוזר חייבים להיות נפרדים, כלומר אף חלון זמן לא יכול להיות חופף לחלון זמן אחר או להיות צמוד אליו, והם חייבים להיות בסדר כרונולוגי.

אפשר להגדיר את cost_per_hour_after_soft_end_time ו-soft_end_time רק אם יש חלון זמן אחד.
unloading_policy

UnloadingPolicy

מדיניות פריקה שחלה על הרכב.
load_limits

map<string, LoadLimit>

הקיבולת של הרכב (משקל, נפח, מספר פלטפורמות, לדוגמה). המפתחות במפה הם המזהים של סוג העומס, בהתאם למפתחות של השדה Shipment.load_demands. אם מפתח מסוים חסר במפה הזו, הקיבולת התואמת נחשבת כבלתי מוגבלת.
cost_per_hour

double

עלויות הרכב: כל העלויות צריכות להתווסף זו לזו, והן חייבות להיות באותה יחידה כמו Shipment.penalty_cost.

העלות לשעה של מסלול הרכב. העלות הזו חלה על משך הזמן הכולל של המסלול, כולל זמן הנסיעה, זמן ההמתנה וזמן הביקור. שימוש ב-cost_per_hour במקום ב-cost_per_traveled_hour בלבד עלול להוביל לזמן אחזור ארוך יותר.
cost_per_traveled_hour

double

העלות לשעת נסיעה במסלול הרכב. העלות הזו חלה רק על זמן הנסיעה במסלול (כלומר, הזמן שמדווח ב-ShipmentRoute.transitions), ולא כוללת את זמן ההמתנה ואת זמן הביקור.
cost_per_kilometer

double

העלות לקילומטר במסלול הרכב. העלות הזו חלה על המרחק שמדווח ב-ShipmentRoute.transitions, ולא חלה על כל מרחק שעבר באופן משתמע מ-arrival_location ל-departure_location של VisitRequest יחיד.
fixed_cost

double

עלות קבועה שחלה אם הרכב הזה משמש לטיפול במשלוח.
used_if_route_is_empty

bool

השדה הזה רלוונטי רק לכלי רכב כשהמסלול שלהם לא משמש למשלוח חבילות. השדה הזה מציין אם הרכב צריך להיחשב כמשומש או לא במקרה הזה.

אם הערך הוא true, הרכב עובר ממיקום ההתחלה למיקום הסיום גם אם הוא לא משמש למשלוח חבילות, והעלויות של הזמן והמרחק שנובעות מהנסיעה מהתחלה לסיום נלקחות בחשבון.

אחרת, הרכב לא נוסע ממיקום ההתחלה למיקום הסיום, ולא מתוזמנים לו break_rule או עיכוב (מ-TransitionAttributes). במקרה כזה, השדה ShipmentRoute של הרכב לא מכיל מידע מלבד המדד והתווית של הרכב.
route_duration_limit

DurationLimit

המגבלה חלה על משך הנסיעה הכולל של הרכב. ב-OptimizeToursResponse נתון, משך המסלול של רכב הוא ההפרש בין vehicle_end_time לבין vehicle_start_time.
travel_duration_limit

DurationLimit

הגבלה שחלה על משך הנסיעה במסלול של הרכב. ב-OptimizeToursResponse נתון, משך הנסיעה במסלול הוא הסכום של כל הערכים של transitions.travel_duration.
route_distance_limit

DistanceLimit

המגבלה חלה על המרחק הכולל של מסלול הרכב. ב-OptimizeToursResponse נתון, מרחק המסלול הוא הסכום של כל transitions.travel_distance_meters שלו.
extra_visit_duration_for_visit_type

map<string, Duration>

מציין מפה ממחרוזות של visit_types למשכי זמן. משך הזמן הוא הזמן שנוסף ל-VisitRequest.duration שצריך להוסיף לביקורים עם visit_types שצוין. משך הביקור הנוסף הזה מוסיף עלות אם מציינים את הערך cost_per_hour. מפתחות (למשל visit_types) לא יכולים להיות מחרוזות ריקות.

אם לבקשת הביקור יש כמה סוגים, לכל סוג יתווסף משך זמן במפה.
break_rule

BreakRule

תיאור לוח הזמנים של ההפסקות שייאכף ברכב הזה. אם השדה הזה ריק, לא יתוזמנו הפסקות ברכב הזה.
label

string

תווית לרכב. התווית הזו מדווחת בתגובה כ-vehicle_label של ShipmentRoute התואם.
ignore

bool

אם הערך הוא true, הערך של used_if_route_is_empty חייב להיות false, והרכב הזה לא ישמש לשימוש.

אם המשלוח מתבצע על ידי רכב שנדחה ב-injected_first_solution_routes, הוא יידלג בפתרון הראשון, אבל ניתן לבצע אותו בתגובה.

אם משלוח מתבצע על ידי רכב שנדחה ב-injected_solution_constraint, וכל איסוף או מסירה קשורים מוגבלים להישאר ברכב (כלומר, לא הושהו לרמה RELAX_ALL_AFTER_THRESHOLD), הם יושמטו בתגובה. אם לשדה allowed_vehicle_indices של משלוח מסוים יש ערך לא ריק, והמערכת מתעלמת מכל הרכבים המותרים, המשלוח יידלג בתגובה.
travel_duration_multiple

double

גורם מכפיל שאפשר להשתמש בו כדי להגדיל או להקטין את זמני הנסיעה של הרכב הזה. לדוגמה, אם ההגדרה הזו תהיה 2.0, המשמעות היא שהרכב הזה איטי יותר ומשך הנסיעה שלו הוא פי שניים מזה של כלי רכב רגילים. המכפיל הזה לא משפיע על משכי הביקורים. אם מציינים את cost_per_hour או את cost_per_traveled_hour, יש לכך השפעה על העלות. הערך חייב להיות בטווח [0.001, 1000.0]. אם לא מגדירים את הערך, הרכב נחשב לרכב רגיל והמכפיל הזה נחשב ל-1.0.

אזהרה: זמני הנסיעה יעוגלו לשנייה הקרובה ביותר אחרי החלת הכפולה הזו, אבל לפני ביצוע פעולות מספריות כלשהן. לכן, כפולה קטנה עלולה לגרום לאובדן דיוק.

מידע נוסף זמין בקטע extra_visit_duration_for_visit_type בהמשך.

DurationLimit

מגבלה שמגדירה את משך הזמן המקסימלי של מסלול הרכב. הוא יכול להיות קשה או רך.

כשמגדירים שדה של מגבלה רכה, צריך להגדיר יחד גם את סף המגבלה הרכה וגם את העלות המשויכת אליה.

שדות
max_duration

Duration

מגבלה קשיחה שמגבילה את משך הזמן ל-max_duration לכל היותר.
soft_max_duration

Duration

מגבלה רכה שלא אוכפת מגבלת משך זמן מקסימלי, אבל אם היא מופרת, נצברת עלות במסלול. העלות הזו מצטברת לעלות של רכיבים אחרים שמוגדרים במודל, באותה יחידה.

אם soft_max_duration מוגדר, הערך שלו חייב להיות לא שלילי. אם גם max_duration מוגדר, הערך של soft_max_duration חייב להיות קטן מ-max_duration.
quadratic_soft_max_duration

Duration

מגבלה רכה שלא אוכפת מגבלת משך זמן מקסימלי, אבל אם היא מופרת, היא גורמת לחיוב על המסלול, כתוצאה מהמשך הזמן הכפול של ההפרה. העלות הזו מצטברת לעלות של רכיבים אחרים שמוגדרים במודל, באותה יחידה.

אם quadratic_soft_max_duration מוגדר, הערך שלו חייב להיות לא שלילי. אם גם max_duration מוגדר, הערך של quadratic_soft_max_duration חייב להיות קטן מ-max_duration וההפרש חייב להיות לכל היותר יום אחד:

max_duration - quadratic_soft_max_duration <= 86400 seconds
cost_per_hour_after_soft_max

double

העלות לשעה שנצברת אם מגיעים לסף soft_max_duration. העלות הנוספת היא 0 אם משך הזמן נמוך מהסף. אחרת, העלות תלויה במשך הזמן באופן הבא:

  cost_per_hour_after_soft_max * (duration - soft_max_duration)

העלות חייבת להיות לא שלילית.
cost_per_square_hour_after_quadratic_soft_max

double

העלות לשעה רבועה שנצברת אם מפר את הסף quadratic_soft_max_duration.

העלות הנוספת היא 0 אם משך הזמן נמוך מהסף. אחרת, העלות תלויה במשך הזמן באופן הבא:

  cost_per_square_hour_after_quadratic_soft_max *
  (duration - quadratic_soft_max_duration)^2

העלות חייבת להיות לא שלילית.

LoadLimit

הגדרת מגבלת עומס שחלה על רכב, למשל: "המשאית הזו יכולה לשאת עד 3,500 ק"ג". load_limits.

שדות
soft_max_load

int64

מגבלה רכה של העומס. cost_per_unit_above_soft_max.
cost_per_unit_above_soft_max

double

אם העומס יהיה גבוה מ-soft_max_load לאורך המסלול של הרכב הזה, תחול עליו הפסד העלות הבא (רק פעם אחת לכל רכב): (עומס – soft_max_load) * cost_per_unit_above_soft_max. כל העלויות צריכות להתווסף, והן חייבות להיות באותה יחידה כמו Shipment.penalty_cost.
start_load_interval

Interval

מרווח הזמן המקובל לטעינה של הרכב בתחילת המסלול.
end_load_interval

Interval

מרווח הטעינה המקובל של הרכב בסוף המסלול.
max_load

int64

עומס מקסימלי מקובל.

מרווח

מרווח בין סכומי העומסים הקבילים.

שדות
min

int64

עומס מינימלי מקובל. הערך חייב להיות ≥ 0. אם מציינים את שניהם, הערך של min חייב להיות ≤ max.
max

int64

עומס מקסימלי מקובל. הערך חייב להיות ≥ 0. אם לא צוין ערך, העומס המקסימלי לא מוגבל על ידי ההודעה הזו. אם מציינים את שניהם, הערך של min חייב להיות ≤ max.

TravelMode

אמצעי הגעה שאפשר להשתמש בהם ברכב.

אלה צריכים להיות קבוצת משנה של שיטות הנסיעה המועדפות ב-API של Routes בפלטפורמה של מפות Google. אפשר לקרוא על כך במאמר: https://developers.google.com/maps/documentation/routes_preferred/reference/rest/Shared.Types/RouteTravelMode.

טיפוסים בני מנייה (enum)
TRAVEL_MODE_UNSPECIFIED מצב נסיעה לא מוגדר, שווה ל-DRIVING.
DRIVING אמצעי התחבורה שמתאים למסלול נסיעה (רכב, ...).
WALKING מצב נסיעה שתואם למסלול הליכה.

UnloadingPolicy

המדיניות בנושא אופן פריקה של רכב. האפשרות הזו רלוונטית רק לשליחויות עם איסוף ומשלוח.

משלוחים אחרים יכולים להתרחש בכל מקום במסלול, ללא קשר ל-unloading_policy.

טיפוסים בני מנייה (enum)
UNLOADING_POLICY_UNSPECIFIED מדיניות פריקה לא צוינה. המשלוח חייב להתבצע רק אחרי האיסוף המתאים.
LAST_IN_FIRST_OUT המשלוחים צריכים להתבצע בסדר הפוך לאיסופים
FIRST_IN_FIRST_OUT המשלוחים חייבים להתבצע באותו סדר שבו בוצעו האיסופים

נקודת ציון

עטיפה של ציון דרך. נקודות ציון מסמנות את מיקומי הגעתו והיציאה של בקשות ביקור, ואת מיקומי ההתחלה והסיום של כלי רכב.

שדות
side_of_road

bool

זה שינוי אופציונלי. מציין שהמיקום של נקודת הציון הזו מיועד להעדפה של כלי הרכב לעצור בצד מסוים של הכביש. כשמגדירים את הערך הזה, המסלול עובר דרך המיקום כדי שהרכב יוכל לעצור בצד הכביש שאליו המיקום מוטה ממרכז הכביש. האפשרות הזו לא פועלת במצב 'הליכה'.
שדה האיחוד location_type. דרכים שונות לייצוג מיקום. הערך של location_type יכול להיות רק אחת מהאפשרויות הבאות:
location

Location

נקודה שצוינה באמצעות קואורדינטות גיאוגרפיות, כולל כותרת אופציונלית.
place_id

string

מזהה המקום של נקודת העניין שמשויך לנקודת הציון.