Method: projects.optimizeTours

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

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

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

בקשת HTTP

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

בכתובת ה-URL נעשה שימוש בתחביר המרת קידוד של 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 (תגובה 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

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

גוף התשובה

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

היקפי הרשאה

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

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

הרשאות IAM

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

  • routeoptimization.locations.use

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