基本结构（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"
  }
}