דף זה תורגם על ידי Cloud Translation API.

Method: projects.optimizeTours

בקשת HTTP
פרמטרים של נתיב
גוף הבקשה
- ייצוג JSON
גוף התשובה
היקפי ההרשאות

הפונקציה שולחת 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/*}:optimizeTours

בכתובת ה-URL נעשה שימוש בתחביר המרת קידוד של gRPC.

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

פרמטרים

פרמטרים
`parent`	`string` חובה. צריך לטרגט את הפרויקט או את המיקום כדי להתקשר. פורמט: * `projects/{project-id}` * `projects/{project-id}/locations/{location-id}` אם לא תציינו מיקום, ייבחר אזור באופן אוטומטי.

parent

string

חובה. צריך לטרגט את הפרויקט או את המיקום כדי להתקשר.

פורמט: * projects/{project-id} * projects/{project-id}/locations/{location-id}

אם לא תציינו מיקום, ייבחר אזור באופן אוטומטי.

גוף הבקשה

גוף הבקשה מכיל נתונים במבנה הבא:

ייצוג JSON

ייצוג 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,
  "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: נעשה שימוש ב-`ShipmentRoute.vehicle_label` במקום ב-`vehicleIndex` כדי להתאים מסלולים בתמיסה מוחדרת לרכבים בבקשה; נעשה שימוש חוזר במיפוי של `ShipmentRoute.vehicle_index` המקורי ל-`ShipmentRoute.vehicle_index` חדש כדי לעדכן את `ConstraintRelaxation.vehicle_indices` אם השדה לא ריק, אבל המיפוי חייב להיות חד-משמעי (כלומר, מספר `ShipmentRoute`s לא יכול להיות משותף עם אותו `vehicleIndex` מקורי). משתמשת ב-`ShipmentRoute.Visit.shipment_label` במקום ב-`shipmentIndex` כדי להתאים ביקורים בתמיסה מוחדרת עם משלוחים בבקשה; משתמשת ב-`SkippedShipment.label` במקום ב-`SkippedShipment.index` כדי להתאים בין משלוחים שעליהם דילגת בפתרון שהוחדר לבין בקשות למשלוחים. הפרשנות הזו חלה על השדות `injectedFirstSolutionRoutes`, `injectedSolutionConstraint` ו-`refreshDetailsRoutes`. אפשר להשתמש בה אם מפתחי המשלוח או הרכבים שצוינו בבקשה השתנו מאז שהפתרון נוצר, אולי כי משלוחים או כלי רכב הוסרו מהבקשה או נוספו אליה. אם True, התוויות בקטגוריות הבאות חייבות להופיע פעם אחת לכל היותר בקטגוריה שלהן: `Vehicle.label` בבקשה; `Shipment.label` בבקשה; `ShipmentRoute.vehicle_label` בתמיסה ההזרקת; `SkippedShipment.label` ו-`ShipmentRoute.Visit.shipment_label` בפתרון שהוחדר (למעט צמדים של איסוף/מסירה וביקור, שהפרמטר `shipmentLabel` שלהם חייב להופיע פעמיים). אם `vehicleLabel` בפתרון שהוחדר לא מתאים לרכב בקשה, המסלול המתאים יוסר מהפתרון יחד עם הביקורים שלו. אם `shipmentLabel` בפתרון שהוחדר לא מתאים לבקשת משלוח, הביקור המתאים יוסר מהפתרון. אם `SkippedShipment.label` בפתרון שהוחדר לא מתאים לבקשה למשלוח, `SkippedShipment` יוסר מהתמיסה. הסרה של ביקורים במסלול או מסלולים שלמים מפתרון שהוחדר יכולה להיות השפעה על המגבלות המשתמעות. כתוצאה מכך, עשויים להיות שינויים בפתרון, בשגיאות אימות או בחוסר היתכנות. הערה: המתקשר חייב לוודא שכל `Vehicle.label` (תגובה `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