Method: projects.optimizeTours

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

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

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

בקשת HTTP

POST https://routeoptimization.googleapis.com/v1/{parent=projects/*}:optimizeTours

כתובת ה-URL כתובה בתחביר של gRPC Transcoding.

פרמטרים של הנתיב

פרמטרים
parent

string

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

פורמט:

  • projects/{project-id}
  • projects/{project-id}/locations/-

ערכי {location-id} אזוריים לא נתמכים.

גוף הבקשה

גוף הבקשה מכיל נתונים במבנה הבא:

ייצוג ב-JSON 
{
  "timeout": string,
  "model": {
    object (ShipmentModel)
  },
  "solvingMode": enum (SolvingMode),
  "searchMode": enum (SearchMode),
  "injectedFirstSolutionRoutes": [
    {
      object (ShipmentRoute)
    }
  ],
  "injectedSolutionConstraint": {
    object (InjectedSolutionConstraint)
  },
  "refreshDetailsRoutes": [
    {
      object (ShipmentRoute)
    }
  ],
  "interpretInjectedSolutionsUsingLabels": boolean,
  "considerRoadTraffic": boolean,
  "populatePolylines": boolean,
  "populateTransitionPolylines": boolean,
  "allowLargeDeadlineDespiteInterruptionRisk": boolean,
  "useGeodesicDistances": boolean,
  "label": string,
  "geodesicMetersPerSecond": number,
  "maxValidationErrors": integer
}
שדות
timeout

string (Duration format)

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

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

object (ShipmentModel)

מודל המשלוח שצריך לפתור.
solvingMode

enum (SolvingMode)

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

enum (SearchMode)

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

object (ShipmentRoute)

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

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

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

  • בכל המסלולים, הערך של vehicleIndex חייב להיות בטווח ולא להיות כפול.
  • בכל הביקורים, הערכים של shipmentIndex ו-visitRequestIndex חייבים להיות בטווח.
  • אפשר להפנות למשלוח רק במסלול אחד.
  • האיסוף של משלוח מסוג איסוף-מסירה חייב להתבצע לפני המסירה.
  • מותר לבצע רק חלופה אחת של איסוף או חלופה אחת של מסירה של משלוח.
  • בכל המסלולים, הזמנים עולים (כלומר, vehicleStartTime <= visits[0].start_time <= visits[1].start_time ... <= vehicleEndTime).
  • אפשר לבצע משלוח רק ברכב שמותר להשתמש בו. כלי רכב מותר אם Shipment.allowed_vehicle_indices ריק או אם vehicleIndex שלו כלול ב-Shipment.allowed_vehicle_indices.

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

object (InjectedSolutionConstraint)

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

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

object (ShipmentRoute)

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

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

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

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

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

boolean

אם הערך הוא True:

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

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

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

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

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

boolean

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

boolean

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

boolean

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

boolean

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

boolean

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

string

תווית שאפשר להשתמש בה כדי לזהות את הבקשה הזו, שדווחה ב-OptimizeToursResponse.request_label.
geodesicMetersPerSecond

number

כשהערך של useGeodesicDistances הוא True, צריך להגדיר את השדה הזה, והוא מגדיר את המהירות שמשמשת לחישוב זמני ההגעה. הערך חייב להיות לפחות 1.0 מטרים לשנייה.
maxValidationErrors

integer

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

גוף התשובה

אם הפעולה בוצעה ללא שגיאות, גוף התגובה יכיל מופע של OptimizeToursResponse.

היקפי הרשאות

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

  • https://www.googleapis.com/auth/cloud-platform

הרשאות IAM

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

  • routeoptimization.locations.use

מידע נוסף מופיע במאמרי העזרה בנושא IAM.