Method: projects.locations.optimizeTours

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

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

המטרה היא להקצות ShipmentRoutes ל-Vehicles באופן שממזער את העלות הכוללת, כאשר העלות מורכבת מרכיבים רבים שמוגדרים ב-ShipmentModel.

בקשת HTTP

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

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

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

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

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

החל מ-2020/11, המערכת מאכלסת רק את הקווים המקוטעים של מסלולים לא ריקים, ונדרש שהערך של 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, כשמגדירים את השדה ShipmentRoute.has_traffic_infeasibilities וכשמחשבים את השדה OptimizeToursResponse.total_cost.vehicleEndTime
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), אלא אם הערך של 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.