本文說明如何使用實際情境，向 Route Optimization API 發出第一個要求。
為求簡單，本範例使用 HTTP 和 JSON 示範 REST API。不過，就實際工作環境而言，建議您使用 gRPC，因為效能較佳。不過，gRPC 需要安裝一些項目。詳情請參閱 Route Optimization API 用戶端程式庫。
情境
你在舊金山經營狗狗托育服務，時間為上午 7 點至下午 7 點。今天早上，您需要在市區的不同地點接送兩隻狗。兩位狗主人的取貨時間都是上午 7:30 到 9:30。
你有一輛廂型車，並以每小時 27 美元的價格聘請司機。司機和廂型車會在早上 7:00 從幼兒園出發，並在中午 12:00 前完成上午的接送行程，以便休息吃午餐。
今天是 2024 年 2 月 13 日，駕駛員有下列工作：
- 在科伊特塔附近撿起伯恩山犬。
- 在 South Sunset Playground Park 領取吉娃娃。
- 將兩隻狗都送到 Mission Dolores Park 的狗狗托育中心。
您需要規劃路線，盡量縮短狗狗待在車上的時間，同時符合接送規定。
事前準備
如要在這個範例情境中執行程式碼，請先完成「設定 Route Optimization API」中的操作說明。
1. 選擇路線最佳化做法
視最佳化問題的複雜程度而定，路徑最佳化 API 提供多種方法供您選擇。
由於這個狗狗托兒所情境是簡單的小型要求，因此請使用 optimizeTours 等封鎖方法，快速傳回小型要求的結果。如要進一步瞭解 Route Optimization API 方法，請參閱同步和非同步端點。
使用下列網址，對 optimizeTours 方法發出 HTTP POST 要求：
https://routeoptimization.googleapis.com/v1/projects/PROJECT_OR_ID:optimizeTours
此外，您也需要將逾時和截止期限設定為較短的時間，以減少不必要的等待時間。在這個狗狗托兒所情境中，最佳化工具不需要花費大量時間回應要求，因此請使用下列設定：
- 將
timeout參數設為 2 秒。 - 將期限設定保留為預設值，也就是 REST 要求的 60 秒。
2. 建構要求訊息內文
選擇封鎖 optimizeTours 方法並定義逾時和期限設定後，下一步是建構要求訊息的主體。
在這個情境中，要求是 REST API 中以 JSON 編碼的 OptimizeToursRequest 訊息。
如要建構要求訊息，請按照下列步驟操作：
請先從基本要求結構著手，如下所示：
{ "timeout": ..., "model": { "shipments": [...], "vehicles": [...], "globalStartTime": "...", "globalEndTime": "..." } }如要進一步瞭解結構，請參閱基本結構 (ShipmentModel、Shipment 和 Vehicle) 的重要概念指南。
定義出貨商品。在
shipments欄位中，為每隻需要早上接送的狗新增Shipment訊息。您可以在這裡定義每位狗主人的偏好接送地點和時間，以及將狗狗送往托兒中心的接送地點和時間。為每隻狗建立一個取貨和一個送貨的
VisitRequest，在本情境中，送貨是指將狗送到托兒所。在取貨行程中，將
arrivalWaypoint設為狗狗的取貨地點 (伯恩山犬為科伊特塔，吉娃娃為南日落遊樂場公園)，並將timeWindows設為主人要求的取貨時間 (上午 7:30 至上午 9:30)。在送貨行程中，將
arrivalWaypoint設為幼兒園，並將timeWindows設為必要送達時間 (上午 9:30 至 11:30)。
如要進一步瞭解時間範圍，請參閱「時間範圍」。
你可以使用
label欄位為每批貨件新增 ID，例如「伯恩山犬」和「吉娃娃」。這有助於您在回覆中找出貨運資訊。
如要進一步瞭解如何定義出貨，請參閱「出貨」一文。
定義車輛。在
vehicles欄位中，為你的單一廂型車新增Vehicle訊息，並以托兒中心做為起點和終點、司機薪資成本，以及廂型車的營運時間。設定全域時間區間。全球時間範圍代表廂型車可能在一天內接送幼兒園學童的時間範圍。在這個情境中，請將 2024 年 2 月 13 日的
globalStartTime設為上午 7:00，globalEndTime設為下午 7:00，代表狗狗托育中心的營業時間。
3. 傳送要求
以下是根據狗狗托兒所情境的簡單 curl 要求，並使用封鎖 optimizeTours 方法。
傳送要求前，請先將範例程式碼中的 PROJECT_NUMBER_OR_ID 替換為您的 Google Cloud 專案 ID。
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-13T07:30:00Z",
"endTime": "2024-02-13T09:30:00Z"
}
]
}
],
"deliveries": [
{
"arrivalWaypoint": {
"location": {
"latLng": {
"latitude": 37.760202,
"longitude": -122.426796
}
}
},
"timeWindow": [
{
"startTime": "2024-02-13T09:30:00Z",
"endTime": "2024-02-13T11:30:00Z"
}
]
}
],
"label": "Bernese mountain dog"
},
{
"pickups": [
{
"arrivalWaypoint": {
"location": {
"latLng": {
"latitude": 37.738067,
"longitude": -122.498593
}
}
},
"timeWindows": [
{
"startTime": "2024-02-13T07:30:00Z",
"endTime": "2024-02-13T09:30:00Z"
}
]
}
],
"deliveries": [
{
"arrivalWaypoint": {
"location": {
"latLng": {
"latitude": 37.760202,
"longitude": -122.426796
}
}
},
"timeWindow": [
{
"startTime": "2024-02-13T09:30:00Z",
"endTime": "2024-02-13T11:30:00Z"
}
]
}
],
"label": "Chihuahua"
}
],
"vehicles": [
{
"startWaypoint": {
"location": {
"latLng": {
"latitude": 37.760202,
"longitude": -122.426796
}
}
},
"endWaypoint": {
"location": {
"latLng": {
"latitude": 37.760202,
"longitude": -122.426796
}
}
},
"costPerHour": 27,
"startTimeWindows": [
{
"startTime": "2024-02-13T07:00:00Z",
"endTime": "2024-02-13T07:15:00Z"
}
],
"endTimeWindows": [
{
"startTime": "2024-02-13T11:45:00Z",
"endTime": "2024-02-13T12:00:00Z"
}
]
}
],
"globalStartTime": "2024-02-13T07:00:00Z",
"globalEndTime": "2024-02-13T19:00:00Z"
}
}
EOM
要求中使用的要求參數
下表說明範例情境要求內容中使用的要求參數。您可以依父項或文字搜尋篩選內容。
| 父項 | 參數 | 資源類型 | 說明 |
|---|---|---|---|
OptimizeToursRequest |
model |
object (ShipmentModel) |
這是要求的核心內容。您可以在單一物件中定義整個問題，包括需要接送的所有狗狗 (shipments) 和車隊中的廂型車 (vehicles)。您可以將其視為需要最佳化問題的完整藍圖。 |
timeout |
時間長度 | 這個參數指定伺服器處理要求並傳回回應的時間上限。使用這個參數可縮短等待時間。如果是小型快速要求 (例如這個狗狗托育中心情境)，請將這個值設為 2 秒。 | |
ShipmentModel |
shipments[] |
物件陣列 (Shipment) |
這是物件陣列，每個物件代表需要接送的狗。 |
vehicles[] |
物件陣列 (Vehicle) |
這是物件陣列，每個物件都會定義車隊中的車輛。您可以在這裡說明資源，例如負責取貨和送貨的貨車。您必須定義至少一輛車輛，才能取得最佳化路線。 | |
globalStartTime |
時間戳記 | 這是整個模型中任何事件可能發生的最早時間。這個參數可縮短最佳化問題的時間，這對準確計算流量和路線至關重要。以這間狗狗托兒所為例，請將這個時間設為司機當天最早可駕駛廂型車的時間，也就是 2024 年 2 月 13 日的上午 7:00。 | |
globalEndTime |
時間戳記 | 這是整個模型中任何事件可能發生的最晚時間。以這間狗狗安親班為例，請將此時間設為廂型車預計結束營運的時間，也就是 2024 年 2 月 13 日下午 7 點。 | |
Shipment |
pickups[] |
物件陣列 (VisitRequest) |
這份清單列出貨件的所有可能取貨選項。最佳化工具會選擇最適合的選項來解決問題。以這間狗狗托兒所為例，請列出每位狗主人為每隻狗狗提供的接送地點和時間範圍。 |
deliveries[] |
物件陣列 (VisitRequest) |
這份清單列出所有可能的貨件交貨選項。最佳化工具會選擇最適合的選項來解決問題。在這個狗狗托兒所情境中，請列出狗狗托兒所設施的位置，以及司機必須返回為每隻狗提供午餐的時間範圍。 | |
label |
字串 | 這是要求中特定貨件的 ID。 您可以在要求中指定標籤，讓回覆內容更容易閱讀。以這間狗狗安親班為例，請使用「吉娃娃」、「伯恩山犬」或狗狗的名字等描述性字串，在收到 API 回應時，將解決方案與輸入內容相符。 | |
VisitRequest |
arrivalWaypoint[] |
object (Waypoint) |
這是路線上特定拜訪行程的位置。您可以使用經緯度座標、地點 ID 或方位定義這個位置。在這個狗狗托兒所情境中，請將此值設為擁有者提供的 pickups 位置，並設為托兒所地址的 deliveries。 |
timeWindows[] |
物件陣列 (TimeWindow) |
這是物件陣列，用於定義取貨或送貨的時間限制。在這個情境中，請使用這項功能為每隻狗定義取貨時間，以及將狗送到托兒中心的合適時間。 | |
Vehicle |
startWaypoint[] |
object (Waypoint) |
這是車輛路線的起點，以經緯度座標或地點 ID 定義。這項參數會告知最佳化工具車輛必須從何處開始路線。如果未定義這個中途點，最佳化工具會選擇其中一個取貨或送貨地點做為起點。在這個狗狗托兒所情境中，由於司機從托兒所開始一天的工作，因此請使用 Mission Dolores Park 的座標。 |
endWaypoint[] |
object (Waypoint) |
這是車輛路線的最終目的地，以經緯度座標或地點 ID 定義。這項參數會告知最佳化工具車輛必須結束路線的位置。如未定義這個路線控點，最佳化工具會選擇其中一個取貨或送貨地點做為路線終點。在這個狗狗托兒所情境中，由於司機必須在托兒所結束一天的工作，因此請使用 Mission Dolores Park 的座標。 | |
costPerHour |
數字 | 無論車輛是否正在行駛或停放，只要使用車輛，每小時都會產生這筆費用。在本狗狗托兒所情境中，請使用這項功能模擬司機的時薪。 | |
startTimeWindows[] |
物件陣列 (TimeWindow) |
這是司機可接受的時間範圍，他們可以在這段時間內開始駕駛廂型車，進行上午的狗狗接送行程。 | |
endTimeWindows[] |
物件陣列 (TimeWindow) |
這是司機完成駕駛廂型車並返回狗狗托育中心的合理時間範圍。 |