基本结构（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` 对象中

如图所示：

A Shipment 消息需要 至少一个 pickups 或 deliveries 对象。 这些对象的定义如下：

下表介绍了基于配置 的不同场景，这些配置位于 pickups 和 deliveries 中，位于 Shipment 消息中。

场景 说明
仅 pickups 假设您仅收取货件 。
仅 deliveries 假设您已预先装载货件 或提供服务 。
pickups 和 deliveries 分配的车辆必须先完成收货，然后再送货 。只有执行收货的车辆才能执行送货。
多个 pickups 或 deliveries 如果货件列出了多个 pickups 或 deliveries 的可能性，优化器会选择一个收货选项和一个送货选项 ，以最大限度地降低费用并满足约束条件。

如需查看 Shipment中属性的完整列表，请参阅参考文档。

Shipment 示例

在此示例中，您提供狗狗日托服务，您从狗狗家中接狗狗，然后将它们送到您的日托中心。您想设置两只狗狗的收货地点，并将它们的送货地点设置为您的商家：

  • 第一只狗狗的家 位于旧金山的科伊特塔。此地点的坐标为纬度 37.8024 和经度 -122.4058。
  • 第二只狗狗的家 位于旧金山的南日落游乐场公园。 此地点的坐标为纬度 37.7359 和经度 -122.5011。
  • 您的狗狗日托中心 位于旧金山的 Mission Dolores 公园。此地点的坐标为纬度 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 示例

在此示例中，您提供狗狗日托服务，并且想要定义车辆在一天开始和结束时的位置以及车辆消耗的汽油量。您无需指定车辆的工作时间，因为它们与您在 globalStartTime 和 globalEndTime 属性 中的 ShipmentModel 对象中定义的时间相匹配。

对于此示例，请求中的 Vehicle 属性值如下所示：

属性 值 说明
startLocation latitude: 37.759773，longitude: -122.427063 车辆路线的起始坐标。这些坐标与您的狗狗日托中心的位置相匹配，该中心位于旧金山的 Mission Dolores 公园。
endLocation latitude: 37.759773，longitude: -122.427063 车辆路线的结束坐标。这些坐标与您的狗狗日托中心的位置相匹配，该中心位于旧金山的 Mission Dolores 公园。
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"
  }
}