基本結構 (ShipmentModel、Shipment 和 Vehicle)

ShipmentModel 有一個 `shipments` 物件 (訊息類型為 `Shipment`) 和一個 `vehicles` 物件 (訊息類型為 `Vehicle`)。

Route Optimization API 的目標是為車隊規劃路線，以便前往一組地點。OptimizeToursRequest 物件會說明這些車輛和地點的屬性，也是每個端點要求主體的主要結構。

OptimizeToursRequest 物件的基本結構如下：

本文說明下列訊息類型：

  • ShipmentModel：保留運送清單、可用車輛，以及描述其關係的其他物件。
  • Shipment：說明車輛要造訪的地點。這些點可代表待取貨和送達的實際包裹，或是車輛駕駛人提供服務的地點。
  • Vehicle：說明貨物在運送地點之間的運輸方式。每輛車都對應實際車輛或步行移動的人。

ShipmentModel

ShipmentModel 包含路線最佳化問題的元素。其中包含一組可由一組車輛執行的運送作業，同時考量限制並盡可能降低整體成本。

下表說明 ShipmentModel 的一些相關屬性：

屬性 說明
shipments和vehicles 必要物件，包含一或多個運送和車輛的詳細資料。
globalStartTime和globalEndTime 指出所有車輛必須完成所有運送作業的時間範圍起訖時間。雖然這些屬性並非必要，但建議您加入，因為遵守時間限制時，最佳化工具的運作效果最好。

如需 ShipmentModel 中的完整屬性清單，請參閱參考文件。

ShipmentModel 範例

在這個範例中，您提供狗狗托育服務，並開始建立要求。你稍後會定義貨運和車輛，但想先設定營業時間和每小時的營運成本。

在本範例中，要求中的 ShipmentModel 屬性值如下：

屬性 值 說明
globalStartTime 2024-02-13T00:00:00.000Z 營業時間的開始日期和時間。
globalEndTime 2024-02-14T06:00:00.000Z 營業時間的結束日期和時間。

以下是 ShipmentModel 訊息的程式碼範例，其中包含範例情境值。

{
  "model": {
    "shipments": [
      ...
    ],
    "vehicles": [
      ...
    ],
   "globalStartTime": "2024-02-13T00:00:00.000Z",
   "globalEndTime": "2024-02-14T06:00:00.000Z"
  }
}

Shipment

Shipment 訊息類型會定義可運送的貨件或可在路線上執行的服務的屬性結構。

實際運送作業等同於一則「Shipment」訊息，包含在「shipments」物件中

如圖表所示：

Shipment 訊息需要至少一個 pickups 或 deliveries 物件。 這些物件的定義如下：

下表說明 Shipment 訊息中 pickups 和 deliveries 的設定，以及不同情境。

情境 說明
僅觀看pickups 系統會假設你只會收取貨件。
僅觀看deliveries 系統會假設您已預先載入運送作業或提供服務。
pickups 和 deliveries 指派的車輛必須先完成取貨，再完成送貨。只有執行取件作業的車輛才能執行送件作業。
多個 pickups 或 deliveries 如果運送作業列出多個 pickups 或 deliveries 的可能選項，最佳化工具會根據成本最低和符合限制條件的原則，選擇一個取貨選項和一個送貨選項。

如需 Shipment 中的完整屬性清單，請參閱參考文件。

Shipment 範例

在這個例子中，您提供狗狗托育服務，會到府接送狗狗。您想設定兩隻狗的上車地點，並將下車地點設為您的商家：

  • 第一隻狗的家位於舊金山柯伊特塔。這個地點的座標是緯度 37.8024 和經度 -122.4058。
  • 第二隻狗的家位於舊金山的南日落遊樂場公園。 這個地點的座標是緯度 37.7359，經度 -122.5011。
  • 你的狗狗安親班位於舊金山 Mission Dolores Park，這個地點的座標為緯度 37.759773 和經度 -122.427063。

以下是 Shipment 訊息的程式碼範例，其中 shipments 物件包含兩個 Shipment 訊息類型，並附有範例座標。

{
  "model": {
    "shipments": [
      {
        "pickups": [
          {
            "arrivalLocation": {
              "latitude": 37.8024,
              "longitude": -122.4058
            }
          }
        ],
        "deliveries": [
          {
            "arrivalLocation": {
              "latitude": 37.759773,
              "longitude": -122.427063
            }
          }
        ]
      },
      {
        "pickups": [
          {
            "arrivalLocation": {
              "latitude": 37.7359,
              "longitude": -122.5011
            }
          }
        ],
        "deliveries": [
          {
            "arrivalLocation": {
              "latitude": 37.759773,
              "longitude": -122.427063
            }
          }
        ]
      }
    ],
    "vehicles": [
    ...
    ]
  }
}

Vehicle

Vehicle 訊息類型定義了可在路線中執行運送作業的車輛屬性結構。

一輛實際車輛等於一則「Vehicle」訊息，包含在「vehicles」物件中

如圖所示：

下表說明 Vehicle 的部分相關屬性。

屬性 說明
startLocation和endLocation 車輛的起點和終點位置，這是最終最佳化路線的一部分。如未定義，則預設為第一個貨件取件地點和最後一個貨件送達地點。
costPerHour、costPerKilometer、costPerTraveledHour 車輛專屬費用參數。建議您在要求中至少加入一個費用參數，讓 API 傳回最佳化路線。如要進一步瞭解費用，請參閱「費用模式」主要概念。
startTimeWindows和endTimeWindows 定義車輛可在路線上營運的時間範圍。這些時間必須落在 ShipmentModel 中設定的 globalStartTime 和 globalEndTime 時間範圍內。雖然這項屬性並非必要，但建議您加入，因為遵守時間限制時，最佳化工具的運作效果最好。

Vehicle 範例

在這個範例中，您提供狗狗托育服務，並想定義車輛在一天開始和結束時的位置，以及耗油量。你不需要指定車輛的工作時間，因為這些時間與 ShipmentModel 物件中 globalStartTime 和 globalEndTime 屬性定義的時間相符。

在本範例中，要求中的 Vehicle 屬性值如下：

屬性 值 說明
startLocation latitude：37.759773，longitude：-122.427063 車輛路線的起始座標。這些座標與位於舊金山 Mission Dolores Park 的狗狗托兒所位置相符。
endLocation latitude：37.759773，longitude：-122.427063 車輛路線的終點座標。這些字詞與您在舊金山多洛雷斯公園的狗狗托育中心位置相符。
costPerHour 27 支付給狗狗托育車司機的費用。你每小時支付司機 27 美元。

以下是 Vehicle 訊息的程式碼範例，其中包含範例情境值。

{
  "model": {
    "shipments": [
    ...
    ],
    "vehicles": [
      {
        "startLocation": {
          "latitude": 37.759773,
          "longitude": -122.427063
        },
        "endLocation": {
          "latitude": 37.759773,
          "longitude": -122.427063
        },
        "costPerHour": 27
      }
    ]
  }
}

如需 Vehicle 中屬性的完整清單，請參閱參考文件。

完整要求範例

下列程式碼範例提供完整的請求範例，結合了本文中顯示的 ShipmentModel、Shipment 和 Vehicle 範例。

{
  "model": {
    "shipments": [
      {
        "pickups": [
          {
            "arrivalLocation": {
              "latitude": 37.8024,
              "longitude": -122.4058
            }
          }
        ],
        "deliveries": [
          {
            "arrivalLocation": {
              "latitude": 37.759773,
              "longitude": -122.427063
            }
          }
        ]
      },
      {
        "pickups": [
          {
            "arrivalLocation": {
              "latitude": 37.7359,
              "longitude": -122.5011
            }
          }
        ],
        "deliveries": [
          {
            "arrivalLocation": {
              "latitude": 37.759773,
              "longitude": -122.427063
            }
          }
        ]
      }
    ],
    "vehicles": [
      {
        "startLocation": {
          "latitude": 37.759773,
          "longitude": -122.427063
        },
        "endLocation": {
          "latitude": 37.759773,
          "longitude": -122.427063
        },
        "costPerHour": 27
      }
    ],
    "globalStartTime": "2024-02-13T00:00:00.000Z",
    "globalEndTime": "2024-02-14T06:00:00.000Z"
  }
}