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.

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

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

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

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

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

boolean

אם הערך הוא נכון:

הפרשנות הזו חלה על השדות 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), אלא אם כן resolveMode=LEGALATE_ONLY: יש לעיין בשדה OptimizeToursResponse.validation_errors. ערך ברירת המחדל הוא 100, והוא מוגבל ל-10,000.

גוף התשובה

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

היקפי הרשאות

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

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