时间窗口

时间窗口用于指定路线中事件的时间。这些事件可能包括司机路线的开始和结束、预定的接送和送货时长，或整条路线的持续时间。

时间窗口可支持以下目标：

• 优先在指定时间范围内完成取件和送件。
• 规划路线，以便在整体营业时间内运营。
• 确保车辆在指定的时间范围内开始和结束路线。

结构

如图所示，时间窗口的结构如下：

• 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] [即“祖鲁时”] 格式）	时间窗口的开始时间。
endTime	字符串（RFC3339 世界协调时间 [UTC] [即“祖鲁时”] 格式）	时间窗口的结束时间。

示例

本部分涵盖三种类型的示例：

• 代码示例，用于说明时间窗口的结构。
• 示例场景，展示了如何使用时间窗口来实现业务目标。
• 请求示例，其中包含示例场景中设置的值。

代码示例

以下部分展示了不同类型的时间窗口的代码示例。

全局时间窗口

以下代码示例展示了全局时间窗口的结构：

{
  "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
    }