時間範圍

時間範圍會指定路線上事件的時間。這些事件可能包括駕駛人路線的起點和終點、排定的取貨和運送時間，或是整條路線的持續時間。

時間範圍可支援以下目標：

• 優先在指定時間範圍內完成取貨和送貨。
• 規劃路線，在整體營業時間內營運。
• 確保車輛在指定時間範圍內開始和結束路線。

結構

如圖所示，時間範圍的結構如下：

• globalStartTime 和 globalEndTime 是 ShipmentModel 的屬性
• timeWindows 是下列項目的屬性：
  • Shipment 內的 pickups。
  • Shipment 內的 deliveries。
• startTimeWindows 和 endTimeWindows 是 Vehicle 的屬性。

基本檢查清單

以下檢查清單說明基本知識，可避免與時間範圍相關的潛在錯誤。這份清單可協助您驗證要求，並排解回應問題。

所有出貨和車輛時間範圍都必須落在 globalStartTime 和 globalEndTime 時間範圍內。

貨件和車輛時間範圍必須使用 TimeWindow 訊息類型。

globalStartTime 和 globalEndTime 的值是時間戳記，與其他使用 TimeWindow 訊息類型的時間範圍不同。

單一貨運和車輛可以有多個 TimeWindow 物件。

Vehicle 有兩種時間範圍屬性：startTimeWindows 和 endTimeWindows，分別定義車輛應開始和結束路線的時間間隔。

如果是運送工作，timeWindows 僅適用於取貨或送貨的開始時間。造訪時間長度可以超出時間範圍，但必須在車輛的營業時間和全域時間範圍內。

屬性

下表說明全域時間範圍屬性。

屬性	格式	說明
globalStartTime	Timestamp	任何事件的最早時間。
globalEndTime	Timestamp	任何事件的最晚時間。

下表說明貨運和車輛的時間範圍屬性。

父項	屬性	格式	說明
Shipment。pickups	timeWindows	TimeWindow 訊息類型的陣列。	指定取貨時間間隔。
Shipment。deliveries	timeWindows		指定貨件的運送時間間隔。
Vehicle	startTimeWindows		指定車輛營運時間表的開始時間。
	endTimeWindows		指定車輛營運時間表的結束時間。

注意： 車輛時間表也可能受到 BreakRule 的影響，這項設定定義了車輛操作員可以休息的時間。詳情請參閱 BreakRule 參考文件。

下表說明 TimeWindow 訊息類型的屬性。

屬性	格式	說明
startTime	字串 (RFC3339 UTC「Zulu」格式)	時間範圍的開始時間。
endTime	字串 (RFC3339 UTC「Zulu」格式)	時間範圍的結束時間。

範例

本節涵蓋三種範例：

• 程式碼範例：說明時間範圍的結構。
• 情境示例：說明如何使用時間範圍達成業務目標。
• 要求範例，其中包含範例情境中設定的值。

程式碼範例

以下各節提供不同類型時間範圍的程式碼範例。

全球時間範圍

以下程式碼範例顯示全域時間範圍的結構：

{
  "model": {
    "globalStartTime": "YYYY-MM-DDTHH:MM:SSZ",
    "globalEndTime": "YYYY-MM-DDTHH:MM:SSZ",
    "shipments": [ ... ],
    "vehicles": [ ... ]
  }
}

取貨和運送時間範圍

下列程式碼範例顯示貨件取貨和送貨的時間範圍結構：

{
  "model": {
    "shipments": [
      {
        "pickups": [
          {
            "timeWindows": [
              {
                "startTime": "YYYY-MM-DDTHH:MM:SSZ",
                "endTime": "YYYY-MM-DDTHH:MM:SSZ"
              }
            ]
          }
        ],
        "deliveries": [
          {
            "timeWindows": [
              {
                "startTime": "YYYY-MM-DDTHH:MM:SSZ",
                "endTime": "YYYY-MM-DDTHH:MM:SSZ"
              }
            ]
          }
        ]
      }
    ],
    "vehicles": [ ... ]
  }
}

車輛時間範圍

以下程式碼範例顯示車輛時間範圍的結構：

{
  "model": {
    "shipments": [ ... ],
    "vehicles": [
      {
        "startTimeWindows": [
          {
            "startTime": "YYYY-MM-DDTHH:MM:SSZ",
            "endTime": "YYYY-MM-DDTHH:MM:SSZ"
          }
        ],
        "endTimeWindows": [
          {
            "startTime": "YYYY-MM-DDTHH:MM:SSZ",
            "endTime": "YYYY-MM-DDTHH:MM:SSZ"
          }
        ]
      }
    ]
  }
}

範例情境

本節以狗狗托兒所的業務情境為例。這個範例會最佳化路線，從兩個不同的住家接送狗狗，且飼主有相同的接送時間範圍。最佳化工具應遵守托兒所的營業時間、顧客的特定接送時間，以及司機的工作時間。

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

父項	屬性	值	情境
ShipmentModel	globalStartTime	2023-01-13T07:00:00Z	代表狗狗托育中心的營業時間。在此時間之前，不得取貨或送貨。
ShipmentModel	globalEndTime	2023-01-13T19:00:00Z	代表寵物日托中心的關門時間。所有取貨和送貨作業都必須在這個時間前完成。
Shipment.pickups	timeWindows	startTime: 2023-01-13T07:30:00Z	定義從顧客家中接狗的可接受時間範圍。在這個例子中，你告知兩位顧客在上午 7:30 到 9:00 之間取貨。
		endTime: 2023-01-13T09:00:00Z
Shipment.deliveries	timeWindows	startTime: 2023-01-13T17:00:00Z	定義將狗送回顧客住家的可接受時間範圍。在這個例子中，你告訴兩位顧客，他們的狗會在下午 5:00 到 6:30 之間送達。
		endTime: 2023-01-13T18:30:00Z
Vehicle	startTimeWindows	startTime： 2023-01-13T07:00:00Z endTime： 2023-01-13T07:15:00Z	定義車輛可開始 (上午 7:00 至上午 7:15) 和結束 (下午 5:00 至下午 5:15) 的時間範圍。
	endTimeWindows	startTime： 2023-01-13T18:45:00Z endTime： 2023-01-13T19:00:00Z

下圖說明影響這條路線的時間範圍。

在這個情境中，時間範圍的運作方式如下 (如圖所示)：

• 全域時間範圍代表狗狗托育中心的營業時間，所有其他時間範圍都必須落在這個時間範圍內。
• 取貨和送貨作業在一天開始和結束時，分別有自己的 timeWindows。
• 車輛的startTimeWindows會提供時間範圍，車輛作業人員必須在該範圍內開始工作，endTimeWindows也會提供另一個時間範圍，作業人員必須在該範圍內結束當天的工作。
• 第一班 startTimeWindow 的開始時間和最後一班 endTimeWindow 的結束時間，定義了車輛的營業時間，在本例中，這與全球時間範圍相同。

要求範例

以下範例顯示 optimizeTours 要求的結構，其中包含範例情境的時間範圍值。

{
  "model": {
    "globalStartTime": "2023-01-13T07:00:00Z",
    "globalEndTime": "2023-01-13T19:00:00Z",
    "shipments": [
      {
        "pickups": [
          {
            "arrivalLocation": {
              "latitude": 37.8024,
              "longitude": -122.4058
            },
            "timeWindows": [
              {
                "startTime": "2023-01-13T07:30:00Z",
                "endTime": "2023-01-13T09:00:00Z"
              }
            ]
          }
        ],
        "deliveries": [
          {
            "arrivalLocation": {
              "latitude": 37.759773,
              "longitude": -122.427063
            },
            "timeWindows": [
              {
                "startTime": "2023-01-13T17:00:00Z",
                "endTime": "2023-01-13T18:30:00Z"
              }
            ]
          }
        ]
      },
      {
        "pickups": [
          {
            "arrivalLocation": {
              "latitude": 37.7359,
              "longitude": -122.5011
            },
            "timeWindows": [
              {
                "startTime": "2023-01-13T07:30:00Z",
                "endTime": "2023-01-13T09:00:00Z"
              }
            ]
          }
        ],
        "deliveries": [
          {
            "arrivalLocation": {
              "latitude": 37.759773,
              "longitude": -122.427063
            },
            "timeWindows": [
              {
                "startTime": "2023-01-13T17:00:00Z",
                "endTime": "2023-01-13T18:30:00Z"
              }
            ]
          }
        ]
      }
    ],
    "vehicles": [
      {
        "startLocation": {
          "latitude": 37.759773,
          "longitude": -122.427063
        },
        "endLocation": {
          "latitude": 37.759773,
          "longitude": -122.427063
        },
        "costPerHour": 27,
        "startTimeWindows": [
          {
            "startTime": "2023-01-13T07:00:00Z",
            "endTime": "2023-01-13T07:15:00Z"
          }
        ],
        "endTimeWindows": [
          {
            "startTime": "2023-01-13T18:45:00Z",
            "endTime": "2023-01-13T19:00:00Z"
          }
        ]
      }
    ]
  }
}

軟性時間範圍

您可以透過在 TimeWindow 訊息類型中定義 softStartTime 和 softEndTime，將時間範圍做為軟性限制。這樣一來，最佳化工具就能以指定成本偏離指定時間範圍，在有益的情況下，優先考量整體最佳化，而非嚴格遵守時間範圍。

彈性時間範圍有下列使用限制：

• 由於 globalStartTime 和 globalEndTime 未使用 TimeWindow 訊息類型，因此無法套用。
• 只有在清單中只有一個 TimeWindow 時，才適用這些屬性。

屬性

下表說明時間範圍的軟限制屬性。

屬性名稱	格式	房源說明
softStartTime	時間戳記	指定彈性時間範圍的開始時間。如果事件發生在指定時間之前，則會產生費用。
softEndTime	時間戳記	指定軟性時間範圍的結束時間。如果在此時間後發生事件，就會產生費用。
costPerHourBeforeSoftStartTime	數字	活動在 softStartTime前開始時，每小時產生的費用。使用 softStartTime 時，必須提供這個屬性。如要進一步瞭解如何實作費用，請參閱「費用模式」重要概念。
costPerHourAfterSoftEndTime	數字	如果活動在 softEndTime 之後結束，則會產生每小時費用。使用 softEndTime 時，必須提供這項屬性。如要進一步瞭解如何實作費用，請參閱「費用模式」重要概念。

程式碼範例

以下範例說明 TimeWindow 訊息類型的軟限制屬性結構：

    {
      "softStartTime": "SOFT_START_TIME",
      "softEndTime": "SOFT_END_TIME",
      "costPerHourBeforeSoftStartTime": COST_BEFORE_START_TIME,
      "costPerHourAfterSoftEndTime": COST_AFTER_END_TIME
    }