基本结构（ShipmentModel、Shipment 和 Vehicle）

ShipmentModel 包含一个具有“Shipment”消息类型的“shipments”对象和一个具有“Vehicle”消息类型的“vehicles”对象。

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