時間範圍

時間範圍會指定路線上事件的時間。這些事件包括司機路線的起點和終點、排定的取貨和送達時間，或是整條路線的時長。

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

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

結構

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

• globalStartTime 和 globalEndTime 是 ShipmentModel 的屬性
• timeWindows 是下列項目的屬性：
  • pickups 內。Shipment
  • deliveries 內。Shipment
• 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 世界標準時間「Zulu」格式)	時間範圍的開始時間。
endTime	字串 (RFC3339 世界標準時間「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
    }