时间窗口

时间窗口存在于 `ShipmentModel` 中、取货和送货对象中的 `Shipment` 中以及 `Vehicle` 中。

时间窗口用于指定路线中事件的时间。这些事件可以包括驾驶员路线的开始和结束时间、计划的取货和送货时间，或整个路线的时长。

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

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

结构

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

要点核对清单

以下核对清单介绍了防止与时间窗口相关的潜在错误的必要知识。此清单可帮助您验证请求并排查响应问题。

属性

下表介绍了全局时间窗口属性。

属性 格式 说明
globalStartTime Timestamp 任何事件的最早时间。
globalEndTime Timestamp 任何事件的最晚时间。

下表介绍了货件和车辆中的时间窗口属性。

父级 属性 格式 说明
Shipment.pickups timeWindows TimeWindow 消息类型的数组。 指定货件取货的时间间隔。
Shipment.deliveries timeWindows 指定货件送货的时间间隔。
Vehicle startTimeWindows 指定车辆运营时间表的开始时间。
endTimeWindows 指定车辆运营时间表的结束时间。

下表介绍了 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，将时间窗口用作软约束。这样，优化工具就可以以指定的费用偏离指定的时间窗口，并在有利的情况下优先考虑整体优化，而不是严格遵守时间范围。

软时间窗口具有以下使用限制：

属性

下表介绍了时间窗口的软约束属性。

属性名称 格式 属性说明
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
    }