發出您的第一個路線最佳化要求

歐洲經濟區 (EEA) 開發人員

本文將說明如何使用實際情境，向 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. 選擇路線最佳化做法

Route Optimization 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 訊息。

如要建構要求訊息，請按照下列步驟操作：

  1. 請先從基本要求結構著手，如下所示：

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

    如要進一步瞭解結構，請參閱「基本結構 (ShipmentModel、Shipment 和 Vehicle)」一文中的重要概念指南。

  2. 定義出貨商品。在 shipments 欄位中，為每隻需要早上接送的狗新增 Shipment 訊息。您可以在這裡定義每位狗主人的偏好接送地點和時間，以及日托中心的接送地點和時間。

    1. 為每隻狗建立一個VisitRequest，分別用於取貨和送貨 (在本情境中，送貨是指將狗送到托兒所)。

      • 在取貨行程中，將arrivalWaypoint設為狗狗的上車地點 (伯恩山犬為 Coit Tower，吉娃娃為 South Sunset Playground Park)，並將timeWindows設為飼主要求的上車時間 (上午 7:30 至 9:30)。

      • 在送貨設定中，將 arrivalWaypoint 設為托兒中心，並將 timeWindows 設為必要送達時間 (上午 9:30 至 11:30)。

      如要進一步瞭解時間範圍，請參閱「時間範圍」。

    2. 你可以使用 label 欄位為每批貨件新增 ID，例如「伯恩山犬」和「吉娃娃」。這有助於您在回覆中找出貨運資訊。

    如要進一步瞭解如何定義出貨，請參閱「出貨」。

  3. 定義車輛。在 vehicles 欄位中，為一輛廂型車新增Vehicle訊息，並以托兒中心為起點和終點，以及司機薪資和廂型車的營運時間。

    1. 將 startWaypoint 和 endWaypoint 設為當天廂型車的起點和終點，也就是 Mission Dolores Park 附近的幼兒園。

    2. 如要盡量降低營運成本，請務必定義業務的成本限制。將費用參數 costPerHour 設為 27，也就是你支付給司機的費用，用來駕駛狗狗托兒所的廂型車。如要進一步瞭解費用參數，請參閱「費用模式」。

    3. 為確保最佳化工具在廂型車的營運時間內建立路線，請將 startTimeWindows 定義為司機可開始駕駛廂型車的時間範圍，並將 endTimeWindows 定義為司機必須返回托兒所的時間範圍。如要進一步瞭解時間範圍，請參閱「時間範圍」。

    如要進一步瞭解如何定義車輛，請參閱「車輛」。

  4. 設定全域時間範圍。全球時間範圍代表廂型車可能在一天內接送幼兒園學童的時間範圍。在這種情況下，請將 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
                }
              }
            },
            "timeWindows": [
              {
                "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
                }
              }
            },
            "timeWindows": [
              {
                "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 物件 (ShipmentModel) 這是要求的核心內容。這個物件會定義整個問題，包括需要接送的所有狗狗 (shipments) 和車隊中的廂型車 (vehicles)。您可以將這個物件視為需要最佳化問題的完整藍圖。
timeout 時間長度 這個參數會指定伺服器處理要求並傳回回應的時間上限。使用這個參數可縮短等待時間。如果是小型快速要求 (例如這個狗狗托兒所情境)，請將這個值設為 2 秒。
ShipmentModel shipments[] 物件陣列 (Shipment) 這是物件陣列，每個物件代表需要接送的狗。
vehicles[] 物件陣列 (Vehicle) 這是物件陣列，每個物件都會定義車隊中的車輛。您可以在這裡描述資源，例如負責取貨和送貨的貨車。您必須定義至少一輛車輛，才能取得最佳化路線。
globalStartTime 時間戳記 這是整個模型中任何事件可能發生的最早時間。這個參數會縮小最佳化問題的時間範圍，這對準確計算流量和路徑至關重要。以這間狗狗托兒所為例，請將這個值設為司機當天最早可駕駛廂型車的時間，也就是 2024 年 2 月 13 日的上午 7 點。
globalEndTime 時間戳記 這是整個模型中任何事件可能發生的最晚時間。以這項狗狗托兒所情境為例，請將此值設為廂型車預計結束作業的時間，也就是 2024 年 2 月 13 日下午 7 點。
Shipment pickups[] 物件陣列 (VisitRequest) 這是這批貨件的所有可能取貨選項清單。最佳化工具會選擇最適合的選項來解決問題。以這間狗狗托兒所為例，請列出每位主人為每隻狗狗提供的接送地點和時間範圍。
deliveries[] 物件陣列 (VisitRequest) 這份清單列出所有可能的貨件卸貨選項。最佳化工具會選擇最適合的選項來解決問題。以這間狗狗托兒所為例，請列出狗狗托兒所的位置，以及司機必須返回為每隻狗準備午餐的時間範圍。
label 字串 這是要求中特定貨件的 ID。 您可以在要求中指定標籤，方便閱讀回覆內容。以這間狗狗安親班為例，請使用「吉娃娃」、「伯恩山犬」或狗狗的名字等描述性字串，在收到 API 回應時，將解決方案與輸入內容相符。
VisitRequest arrivalWaypoint[] 物件 (Waypoint) 這是路線上特定拜訪的所在位置。您可以透過經緯度座標、地點 ID 或方位定義這個位置。在這個狗狗托兒所情境中，請將此值設為擁有者提供的 pickups 位置，以及托兒所的 deliveries 地址。
timeWindows[] 物件陣列 (TimeWindow) 這是物件陣列，用於定義取貨或送貨的時間限制。在這個情境中，請使用這項功能為每隻狗定義取貨時間，以及將狗送到托兒中心的合適時間。
Vehicle startWaypoint[] 物件 (Waypoint) 這是車輛路線的起點，以經緯度座標或地點 ID 定義。這項參數會告知最佳化工具車輛必須從何處開始路線。如果未定義這個路線控點，最佳化工具會選擇其中一個取貨或送貨地點做為起點。在這個狗狗托兒所情境中，由於司機從托兒所開始一天的工作，因此請使用 Mission Dolores Park 的座標。
endWaypoint[] 物件 (Waypoint) 這是車輛路線的最終目的地，以經緯度座標或地點 ID 定義。這項參數會告知最佳化工具車輛必須結束路線的位置。如未定義這個路線控點，最佳化工具會選擇其中一個取貨或送貨地點做為路線終點。在這個狗狗托兒所情境中，由於司機必須在托兒所結束一天的工作，因此請使用 Mission Dolores Park 的座標。
costPerHour 數字 這是車輛每小時的使用費用，無論車輛是否行駛或停止，都會產生這筆費用。在這個狗狗托兒所情境中，請使用這項功能建立司機時薪模型。
startTimeWindows[] 物件陣列 (TimeWindow) 這是司機可接受的時間範圍，他們必須在這個時間內開始駕駛廂型車，在上午接送狗狗。
endTimeWindows[] 物件陣列 (TimeWindow) 這段時間是司機完成駕駛廂型車，並將車輛停回狗狗托兒中心的合理時間。

繼續

解讀回覆