Method: projects.locations.optimizeTours

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

מודל ShipmentModel מורכב בעיקר מאובייקטים של Shipment שצריך לבצע ו-Vehicles שאפשר להשתמש בהם כדי להעביר את אובייקטי 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.
  • אם מגדירים את avoidUTurns כ-true, צריך להגדיר את injectedSolutionLocationToken לביקורים רלוונטיים

אם הפתרון שהוזן לא מתאים, לא בהכרח תוחזר שגיאת אימות. יכול להיות שתוחזר שגיאה שמציינת את חוסר ההתאמה.
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 (תגובה Shipment.label) מזהה באופן ייחודי ישות של רכב (או משלוח) שמופיעה בשתי הבקשות הרלוונטיות: הבקשה הקודמת שהניבה את OptimizeToursResponse ששימש בפתרון שהוזן, והבקשה הנוכחית שכוללת את הפתרון שהוזן. בדיקות הייחודיות המתוארות למעלה לא מספיקות כדי להבטיח את העמידה בדרישה הזו.
considerRoadTraffic

boolean

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

boolean

אם הערך הוא True, הקווים הפוליטיים יאוכלסו בתשובה ShipmentRoutes.
populateTransitionPolylines

boolean

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

boolean

אם היא מוגדרת, ייתכן שתאריך היעד של הבקשה יהיה עד 60 דקות (מידע נוסף זמין בכתובת https://grpc.io/blog/deadlines). אחרת, מועד ההגשה האחרון הוא 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.