基本結構 (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。
  • 你的狗狗安親班位於舊金山都勒公園，這個位置的座標為緯度 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 車輛路線的起始座標。這些座標與位於舊金山都勒公園的狗狗托兒所位置相符。
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"
  }
}