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

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

本文將以實際情境為例，說明如何向 Route Optimization API 提出第一個要求。

為求簡單，本範例使用 HTTP 和 JSON 示範 REST API。不過，對於正式環境，整體建議是使用 gRPC，因為效能較佳。不過，gRPC 需要安裝一些項目。詳情請參閱「Route Optimization API 用戶端程式庫」。

情境

舊金山地圖，其中標示了科伊特塔、多洛雷斯公園和南日落遊樂場公園

您在舊金山經營狗狗托育服務，營業時間為上午 7 點至晚上 7 點。今天早上，您需要從市內兩個不同地點接兩隻狗。兩位飼主都希望你在上午 7:30 到 9:30 之間接走狗狗。

你有一輛廂型車，每小時支付司機 27 美元。司機和廂型車會在早上 7 點從幼兒園出發，並在中午 12 點前完成上午的接送行程，以便休息午餐。

今天是 2024 年 2 月 13 日，司機有以下工作：

  • 在柯伊特塔附近接伯恩山犬。
  • 在 South Sunset Playground 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 設為狗狗的取貨地點 (伯恩山犬為科伊特塔，吉娃娃為南日落遊樂場公園)，並將 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. 傳送要求

以下是根據狗狗托育情境，使用封鎖 optimizeTours 方法的簡單 curl 要求。

傳送要求前，請將程式碼範例中的 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:00。
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 定義。這個參數會告知最佳化工具車輛必須從何處開始路線。如未定義這個路線控點，最佳化工具會選擇其中一個取貨或送貨地點做為起始位置。在這個狗狗托育情境中，司機一早會從托育中心出發，因此請使用多洛雷斯公園的座標。
endWaypoint[] 物件 (Waypoint) 車輛路線的最終目的地，以經緯度座標或地點 ID 定義。這項參數會告知最佳化工具車輛必須在哪裡結束路線。如未定義這個路線控點，最佳化工具會選擇其中一個取貨或送貨地點做為路線終點。在這個狗狗托兒所情境中，由於司機必須在托兒所結束一天的工作，因此請使用 Mission Dolores Park 的座標。
costPerHour 數字 這是車輛每小時的使用費用，無論車輛是否行駛或停止，都會產生這筆費用。在這個狗狗托育情境中，請使用這個項目建立司機時薪的模型。
startTimeWindows[] 物件陣列 (TimeWindow) 這是司機早上開車接狗的合理時間範圍。
endTimeWindows[] 物件陣列 (TimeWindow) 這段時間是司機完成駕駛廂型車，並將車輛停回狗狗托兒中心的合理時間。

繼續

解讀回覆