基本结构（ShipmentModel、Shipment 和 Vehicle）

ShipmentModel 有一个“shipments”对象（消息类型为“Shipment”）和一个“vehicles”对象（消息类型为“Vehicle”）。

Route Optimization API 的目标是为车队规划路线，以便车队前往一组地点。OptimizeToursRequest 对象描述了这些车辆和地点的属性，并且是每个端点的请求正文的主要结构。

OptimizeToursRequest 对象的基本结构 如下所示：

model 字段包含一个 ShipmentModel 消息，其中包含两个关键字段：
- 一个 shipments 字段，其中包含一个或多个 Shipment 消息。
- 一个 vehicles 字段，其中包含一个或多个 Vehicle 消息。

本文档介绍了以下消息类型：

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 消息包含现实生活中的货件或服务的所有信息。
所有 Shipment 消息都在 shipments 字段中指定。
The shipments 字段包含一个或多个 Shipment 消息。

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

pickups 定义了货件的收货地点。
deliveries 定义了货件的送货地点。
pickups 和 deliveries 都包含一个 VisitRequest 消息类型，用于定义地点和其他详细信息。

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

场景	说明
仅 `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` 对象中

如图所示：

A Vehicle 消息包含现实生活中的车辆的所有信息。
所有 Vehicle 消息都在 vehicles 字段中指定。
The vehicles 字段包含多个 Vehicle 消息。

下表介绍了 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"
  }
}

基本结构（ShipmentModel、Shipment 和 Vehicle） 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

ShipmentModel

ShipmentModel 示例

Shipment

Shipment 示例

Vehicle

Vehicle 示例