Method: projects.locations.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/*/locations/*}:optimizeTours

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

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

פרמטרים
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)

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

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

משך הזמן בשניות, עם עד תשע ספרות עשרוניות, שמסתיימים ב-'s'. דוגמה: "3.5s".
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)

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

נכון ל-11 בנובמבר 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 (resp. 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

חיתוך מספר שגיאות האימות שמוחזרות. בדרך כלל השגיאות האלה מצורפות לעומס הנתונים של שגיאת 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.