Method: projects.locations.optimizeTours

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

מודל 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 משתמשת בתחביר של 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.

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

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

גוף התשובה

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

היקפי ההרשאות

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

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

הרשאות IAM

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

  • routeoptimization.locations.use

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