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 נעשה שימוש בתחביר המרת קידוד של 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) משמש לזיהוי ייחודי של ישות של רכב (משלוח resp) שנעשה בה שימוש בשתי הבקשות הרלוונטיות: הבקשה הקודמת שממנה נוצר התמיסה 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

אם היא מוגדרת, ייתכן שתאריך היעד של הבקשה יהיה עד 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.