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

במאמר הזה נסביר איך לשלוח את הבקשה הראשונה ל-Route Optimization API באמצעות תרחיש לדוגמה מהעולם האמיתי.

כדי לפשט את הדוגמה, היא משתמשת ב-HTTP וב-JSON כדי להדגים את ה-API בארכיטקטורת REST. עם זאת, בסביבת הייצור מומלץ להשתמש ב-gRPC בגלל יתרונות הביצועים שלו. עם זאת, צריך להתקין את gRPC. מידע נוסף זמין במאמר ספריות הלקוח של Route Optimization API.

תרחיש

אתם מנהלים מעון יום לכלבים בתל אביב, שפועל בין השעות 7:00 ל-19:00. הבוקר אתם רוצים לאסוף שלושה כלבים ממיקומים שונים בעיר ולהביא אותם למעון שלכם.

הכלב מגזע בובייה דה ברן והצ'יוואווה הם לקוחות קבועים שקבעו את התורים שלהם בשבוע שעבר. הרועה הגרמני הוא בקשה חדשה של הרגע האחרון. אתם רוצים לקבל את הרועה הגרמני אם אפשר, אבל לא על חשבון הלקוחות הקבועים שלכם.

יש לכם מסחרית אחת לעבודה, ואתם משלמים לנהג 27 $לשעה. הנהג והרכב מתחילים את היום במעון בשעה 7:00, וצריכים לחזור מהאיסופים של הבוקר עד הצהריים להפסקת צהריים.

היום הוא 13 בפברואר 2024. כל השעות בתרחיש הזה הן לפי השעון המקומי בסן פרנסיסקו, שהוא שעון החוף המערבי בארה"ב (UTC-8) בפברואר. אלה המשימות של הנהג:

• אוספים את כלב ההרים השווייצרי ליד מגדל קויט. הבעלים ביקש חלון זמן קצר לאיסוף, בין 8:00 ל-8:20.
• אוספים את הצ'יוואווה בפארק South Sunset Playground. הבעלים הציע חלון זמנים גמיש יותר לאיסוף, בין 7:30 ל-9:30.
• לאסוף את הרועה הגרמני ב-Land's End. הבעלים גם ביקש חלון זמן קצר לאיסוף, בין 8:00 ל-8:20.
• להוריד את הכלבים במעון בפארק מיסיון דולורס. במעון הילדים צריך להוריד את הילדים בין 9:30 ל-11:30.

כל ביקור לאיסוף או להורדה נמשך 5 דקות כדי להעלות או להוריד את הכלב.

מכיוון ש-Land's End רחוק מ-Coit Tower וחלונות הזמן לאיסוף מתנגשים, הנהג לא יכול לבצע את כל שלושת האיסופים. האופטימייזר צריך לבחור על איזה כלב לדלג כדי לצמצם את העלות הכוללת (שכר הנהג וקנסות על דילוג).

לפני שמתחילים

כדי להריץ את הקוד בתרחיש לדוגמה הזה, קודם צריך לבצע את ההוראות במאמר הגדרת Route Optimization API.

1. בחירת הגישה לאופטימיזציה של מסלולים

ב-Route Optimization API יש כמה שיטות שאפשר לבחור מביניהן, בהתאם למורכבות של בעיית האופטימיזציה.

התרחיש של מעון היום לכלבים הוא בקשה קטנה ופשוטה, לכן כדאי להשתמש בשיטת חסימה כמו optimizeTours, שמספקת תוצאות במהירות לבקשות קטנות. למידע נוסף על נקודות הקצה של Route Optimization API, ראו בחירת נקודת קצה.

כדי לשלוח בקשת POST ל-method ‏optimizeTours, משתמשים בכתובת ה-URL הבאה:

https://routeoptimization.googleapis.com/v1/projects/PROJECT_OR_ID:optimizeTours

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

• מגדירים את הפרמטר timeout ל-2 שניות.
• משאירים את הגדרות המועד האחרון כברירת מחדל, שהיא 60 שניות לבקשות REST.

2. יצירת גוף ההודעה של הבקשה

אחרי שבוחרים את שיטת החסימה optimizeTours ומגדירים את הזמן הקצוב לתפוגה ואת המועד האחרון, השלב הבא הוא ליצור את גוף הודעת הבקשה.

בתרחיש הזה, הבקשה היא הודעת OptimizeToursRequest שמקודדת כ-JSON ב-API בארכיטקטורת REST.

כדי ליצור את הודעת הבקשה, פועלים לפי השלבים הבאים:

1. מתחילים עם מבנה הבקשה הבסיסי, שנראה כך:

   {
     "timeout": ...,
     "model": {
       "shipments": [...],
       "vehicles": [...],
       "globalStartTime": "...",
       "globalEndTime": "..."
     }
   }
   

   למידע נוסף על המבנה, עיינו במדריך למושגי מפתח בנושא מבנה בסיסי (ShipmentModel,‏ Shipment ו-Vehicle).

2. מגדירים משלוחים. בשדה shipments, מוסיפים הודעת Shipment לכל כלב שצריך לאסוף ולהחזיר בבוקר. כאן מגדירים את המיקום והשעות המועדפים לאיסוף של כל אחד מבעלי הכלבים, ואת המיקום והשעות של מעון היום להורדת הכלבים.

   1. לכל כלב, יוצרים VisitRequest לאיסוף ו נוסף ל משלוח, שבמקרה הזה הוא הורדה במעון.

      • באיסופים, מגדירים את arrivalWaypoint למיקום האיסוף של הכלב (מגדל קויט לכלב ההרים הברנזי, פארק מגרש המשחקים סאות' סאנסט לצ'יוואווה או לאנדס אנד לרועה הגרמני). מגדירים את timeWindows לשעת האיסוף שביקש הבעלים (8:00 עד 8:20 לכלב ההרים השוויצרי ולרועה הגרמני, ו-7:30 עד 9:30 לצ'יוואווה).

      • במשלוחים, מגדירים את arrivalWaypoint למעון היום ואת timeWindows לשעת המסירה הנדרשת (9:30 עד 11:30).

      • בכל האיסופים והמשלוחים, מגדירים את duration ל-5 דקות (300s) כדי להביא בחשבון את העלאת הכלבים לרכב והורדתם ממנו.

      מידע נוסף על חלונות זמן זמין במאמר חלונות זמן.

   2. כדי לתת עדיפות ללקוחות קבועים, אתם מגדירים את penaltyCost ל-1000 לכלב הרים שוויצרי ולצ'יוואווה, ול-100 לרועה גרמני. כשהעלויות של הקנסות מוגדרות, האופטימיזציה יכולה לדלג על כל אחד מהכלבים, אבל היא תביא בחשבון קודם את הדילוג על הרועה הגרמני (שהקנס עליו נמוך יותר) אם האילוצים לא מאפשרים לבצע את כל האיסופים.

   3. אתם יכולים להשתמש בשדה label כדי להוסיף מזהה לכל משלוח, כמו "כלב הרים שוויצרי", "צ'יוואווה" ו"רועה גרמני". כך תוכלו לזהות את המשלוחים בתגובה.

   מידע נוסף על הגדרת משלוחים זמין במאמר משלוח.

3. הגדרת כלי רכב. בשדה vehicles, מוסיפים הודעה ב-Vehicle לגבי המסחרית האחת עם מעון היום כנקודת ההתחלה והסיום, עלות השכר של הנהג ושעות הפעילות של המסחרית.

   1. מגדירים את startWaypoint ואת endWaypoint של הרכב למיקומי ההתחלה והסיום של היום, שהם מעון היום ליד פארק מיסיון דולורס.

   2. כדי להוזיל את עלויות התפעול, צריך להגדיר את מגבלות העלות של העסק. מגדירים את פרמטר העלות costPerHour לערך 27, שהוא הסכום שאתם משלמים לנהג על נהיגה ברכב של מעון היום לכלבים. מידע נוסף על פרמטרים של עלויות מופיע במאמר מודל עלות.

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

      • אם מגדירים את startTime ב-startTimeWindows לשעה 07:00, הנהג יכול להתחיל את המשמרת שלו כבר בשעה 07:00. הוא יכול גם להתחיל מאוחר יותר אם אין איסופים מוקדם בבוקר.

      • אם מגדירים את endTime ב-endTimeWindows לשעת הצהריים, הנהג חייב לסיים את המשמרת עד הצהריים. הם גם יכולים לסיים את המשמרת ברגע שהם מסיימים את המשלוח האחרון.

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

   מידע נוסף על הגדרת כלי רכב זמין במאמר כלי רכב.

4. הגדרת חלון זמן גלובלי. חלון הזמן הגלובלי מייצג את מסגרת הזמן שבה הרכב יכול לבצע איסופים והורדות של ילדים במעון במהלך היום. בתרחיש הזה, מגדירים את globalStartTime ל-7:00 ואת globalEndTime ל-19:00 ב-13 בפברואר 2024, שעות הפעילות של המעון לכלבים.

‫3. שליחת הבקשה

הדוגמה הבאה היא בקשה פשוטה של curl שמבוססת על התרחיש של מעון הכלבים, ומשתמשת בשיטה החוסמת optimizeTours.

לפני ששולחים את הבקשה, מחליפים את PROJECT_NUMBER_OR_ID בקוד לדוגמה במזהה הפרויקט ב-Google Cloud.

curl -X POST 'https://routeoptimization.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID:optimizeTours' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
--data @- << EOM
{
  "timeout": "2s",
  "model": {
    "shipments": [
      {
        "pickups": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.802395,
                  "longitude": -122.405822
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T08:00:00-08:00",
                "endTime": "2024-02-13T08:20:00-08:00"
              }
            ],
            "duration": "300s"
          }
        ],
        "deliveries": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.759719,
                  "longitude": -122.42798
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T09:30:00-08:00",
                "endTime": "2024-02-13T11:30:00-08:00"
              }
            ],
            "duration": "300s"
          }
        ],
        "label": "Bernese mountain dog",
        "penaltyCost": 1000
      },
      {
        "pickups": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.738067,
                  "longitude": -122.498593
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T07:30:00-08:00",
                "endTime": "2024-02-13T09:30:00-08:00"
              }
            ],
            "duration": "300s"
          }
        ],
        "deliveries": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.759719,
                  "longitude": -122.42798
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T09:30:00-08:00",
                "endTime": "2024-02-13T11:30:00-08:00"
              }
            ],
            "duration": "300s"
          }
        ],
        "label": "Chihuahua",
        "penaltyCost": 1000
      },
      {
        "pickups": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.78018,
                  "longitude": -122.51194
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T08:00:00-08:00",
                "endTime": "2024-02-13T08:20:00-08:00"
              }
            ],
            "duration": "300s"
          }
        ],
        "deliveries": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.759719,
                  "longitude": -122.42798
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T09:30:00-08:00",
                "endTime": "2024-02-13T11:30:00-08:00"
              }
            ],
            "duration": "300s"
          }
        ],
        "label": "German shepherd",
        "penaltyCost": 100
      }
    ],
    "vehicles": [
      {
        "startWaypoint": {
          "location": {
            "latLng": {
              "latitude": 37.759719,
              "longitude": -122.42798
            }
          }
        },
        "endWaypoint": {
          "location": {
            "latLng": {
              "latitude": 37.759719,
              "longitude": -122.42798
            }
          }
        },
        "costPerHour": 27,
        "startTimeWindows": [
          {
            "startTime": "2024-02-13T07:00:00-08:00"
          }
        ],
        "endTimeWindows": [
          {
            "endTime": "2024-02-13T12:00:00-08:00"
          }
        ]
      }
    ],
    "globalStartTime": "2024-02-13T07:00:00-08:00",
    "globalEndTime": "2024-02-13T19:00:00-08:00"
  }
}
EOM

הפרמטרים שנעשה בהם שימוש בבקשה

בטבלה הבאה מתוארים הפרמטרים של הבקשה שמשמשים בגוף הבקשה בתרחיש לדוגמה. אפשר לסנן את התוכן לפי הורה או לפי חיפוש טקסט.

הבא

פירוש התשובהarrow_forward