本文档将通过一个实际用例场景，向您展示如何向路线优化 API 发出第一个请求。
为简单起见，此示例使用 HTTP 和 JSON 来演示 REST API。不过，对于生产环境，我们建议使用 gRPC，因为它可以提升性能。不过，gRPC 需要进行一些安装。如需了解详情，请参阅 Route Optimization API 客户端库。
场景
您在旧金山经营一家狗狗日托服务机构，营业时间为上午 7:00 至晚上 7:00。今天早上，您需要从城市中的不同地点接两只狗。两位狗主人都为您提供了上午 7:30 至上午 9:30 的接送时间段。
您有一辆货车用于这项工作，并按每小时 27 美元的标准向司机支付费用。司机和面包车早上 7:00 在您的托儿中心开始工作，需要在中午 12:00 之前完成上午的接送任务，以便休息午餐。
今天是 2024 年 2 月 13 日，该司机有以下任务：
- 在科伊特塔附近拾取伯恩山犬。
- 在南日落游乐场公园接回吉娃娃。
- 将两只狗狗送到多勒瑞斯公园的狗狗日托中心。
您需要规划一条路线，在满足上车和下车要求的同时，尽可能缩短狗狗在面包车中的时间。
准备工作
如需运行此示例场景中的代码，您必须先完成设置路线优化 API 中的说明。
1. 选择路线优化方法
路线优化 API 提供了多种方法供您选择，具体取决于优化问题的复杂程度。
由于此狗狗日托服务场景是一个简单的小型请求，因此请使用阻塞方法（例如 optimizeTours），该方法可快速交付小型请求的结果。如需详细了解 Route Optimization API 方法，请参阅同步和异步端点。
使用以下网址向 optimizeTours 方法发出 HTTP POST 请求：
https://routeoptimization.googleapis.com/v1/projects/PROJECT_OR_ID:optimizeTours
您还需要将超时和截止时间设置得较短，以减少不必要的等待时间。对于此狗狗日托服务场景，优化器不需要花费太多时间来响应您的请求，因此请使用以下设置：
- 将
timeout参数设置为 2 秒。 - 将截止期限设置保留为默认值，即 REST 请求的截止期限为 60 秒。
2. 构建请求消息正文
选择阻塞 optimizeTours 方法并定义超时和截止时间设置后，下一步是构建请求消息的正文。
在此场景中，请求是 REST API 中编码为 JSON 的 OptimizeToursRequest 消息。
如需构建请求消息，请按以下步骤操作：
首先，我们从基本请求结构开始，如下所示：
{ "timeout": ..., "model": { "shipments": [...], "vehicles": [...], "globalStartTime": "...", "globalEndTime": "..." } }如需详细了解此结构，请参阅基本结构（ShipmentModel、Shipment 和 Vehicle）的关键概念指南。
定义货件。在
shipments字段中，为需要在早上接送的每只狗添加一条Shipment消息。您可以在此处定义每位狗主人的首选接送地点和时间，以及日托中心的地点和送狗时间。为每只狗创建一个用于接送的
VisitRequest，并为送达再创建一个，在此场景中，送达是指日托接送。在接送服务中，将
arrivalWaypoint设置为狗狗的接送地点（伯恩山犬为科伊特塔，吉娃娃为南日落游乐场公园），并将timeWindows设置为主人要求的接送时间（上午 7:30 至上午 9:30）。在送货中，将
arrivalWaypoint设置为托儿中心，并将timeWindows设置为所需的送达时间（上午 9:30 至上午 11:30）。
如需详细了解时间窗口，请参阅时间窗口。
您可以使用
label字段为每批货物添加标识符，例如“伯恩山犬”和“吉娃娃”。这有助于您在回答中识别相应货件。
如需详细了解如何定义货件，请参阅货件。
定义车辆。在
vehicles字段中，为您的面包车添加Vehicle消息，其中包含以下信息：面包车的起点和终点（托儿中心）、司机的工资成本以及面包车的运营时间。为面包车设置
startWaypoint和endWaypoint，分别对应于当天的起点和终点位置，即 Mission Dolores Park 附近的一家托儿中心。为了最大限度地降低运营成本，您必须定义业务的成本限制。将费用形参
costPerHour设置为 27，这是您为驾驶狗狗日托服务面包车的司机支付的费用。如需详细了解费用参数，请参阅费用模型。为确保优化器在面包车的运营时间内创建路线，请将
startTimeWindows定义为司机可以开始驾驶面包车的可接受范围，并将endTimeWindows定义为司机必须返回托儿所的可接受范围。如需详细了解时间窗口，请参阅时间窗口。
如需详细了解如何定义车辆，请参阅车辆。
设置全局时间窗口。全局时间范围表示面包车在整个白天可为您的托儿所提供接送服务的时段。在此方案中，请将
globalStartTime设置为 2024 年 2 月 13 日上午 7:00，并将globalEndTime设置为 2024 年 2 月 13 日下午 7:00，这两个时间分别表示狗狗日托服务的营业时间。
3. 发送请求
以下是一个简单的 curl 请求，基于狗狗日托服务场景，并使用阻塞式 optimizeTours 方法。
在发送请求之前，请将示例代码中的 PROJECT_NUMBER_OR_ID 替换为您的 Google Cloud 项目 ID。
curl -X POST 'https://routeoptimization.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID:optimizeTours' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
--data @- << EOM
{
"timeout": 2s,
"model": {
"shipments": [
{
"pickups": [
{
"arrivalWaypoint": {
"location": {
"latLng": {
"latitude": 37.802395,
"longitude": -122.405822
}
}
},
"timeWindows": [
{
"startTime": "2024-02-13T07:30:00Z",
"endTime": "2024-02-13T09:30:00Z"
}
]
}
],
"deliveries": [
{
"arrivalWaypoint": {
"location": {
"latLng": {
"latitude": 37.760202,
"longitude": -122.426796
}
}
},
"timeWindow": [
{
"startTime": "2024-02-13T09:30:00Z",
"endTime": "2024-02-13T11:30:00Z"
}
]
}
],
"label": "Bernese mountain dog"
},
{
"pickups": [
{
"arrivalWaypoint": {
"location": {
"latLng": {
"latitude": 37.738067,
"longitude": -122.498593
}
}
},
"timeWindows": [
{
"startTime": "2024-02-13T07:30:00Z",
"endTime": "2024-02-13T09:30:00Z"
}
]
}
],
"deliveries": [
{
"arrivalWaypoint": {
"location": {
"latLng": {
"latitude": 37.760202,
"longitude": -122.426796
}
}
},
"timeWindow": [
{
"startTime": "2024-02-13T09:30:00Z",
"endTime": "2024-02-13T11:30:00Z"
}
]
}
],
"label": "Chihuahua"
}
],
"vehicles": [
{
"startWaypoint": {
"location": {
"latLng": {
"latitude": 37.760202,
"longitude": -122.426796
}
}
},
"endWaypoint": {
"location": {
"latLng": {
"latitude": 37.760202,
"longitude": -122.426796
}
}
},
"costPerHour": 27,
"startTimeWindows": [
{
"startTime": "2024-02-13T07:00:00Z",
"endTime": "2024-02-13T07:15:00Z"
}
],
"endTimeWindows": [
{
"startTime": "2024-02-13T11:45:00Z",
"endTime": "2024-02-13T12:00:00Z"
}
]
}
],
"globalStartTime": "2024-02-13T07:00:00Z",
"globalEndTime": "2024-02-13T19:00:00Z"
}
}
EOM
请求中使用的请求参数
下表介绍了示例场景的请求正文中使用的请求参数。您可以按父级或通过文字搜索过滤内容。
| 有子女 | 参数 | 物业类型 | 说明 |
|---|---|---|---|
OptimizeToursRequest |
model |
object (ShipmentModel) |
这是您请求的核心内容。这是一个单一对象，您可以在其中定义整个问题，包括需要接送的所有狗 (shipments) 和车队中的厢式货车 (vehicles)。您可以将其视为需要优化的问题的完整蓝图。 |
timeout |
时长 | 此参数用于指定服务器在返回响应之前处理请求的最长时间。使用此参数可缩短等待时间。对于小型快速请求（例如此狗狗日托服务场景），请将此值设置为 2 秒。 | |
ShipmentModel |
shipments[] |
对象数组 (Shipment) |
这是一个对象数组，其中每个对象都表示需要接送的狗。 |
vehicles[] |
对象数组 (Vehicle) |
这是一个对象数组，其中每个对象都定义了您车队中的一辆车。您可以在此处描述自己的资源，例如执行取送服务的面包车。您必须至少定义一辆车辆才能获得优化路线。 | |
globalStartTime |
时间戳 | 这是整个模型中任何事件可能发生的最早时间。此形参可在时间上缩小优化问题的范围，这对于准确计算流量和路线至关重要。对于此狗狗日托服务方案，请将此值设置为司机当天可以驾驶面包车的最早时间，即 2024 年 2 月 13 日的上午 7:00。 | |
globalEndTime |
时间戳 | 这是整个模型中任何事件可能发生的最晚时间。对于此狗狗日托服务场景，请将此值设置为面包车预计结束运营的时间，即 2024 年 2 月 13 日下午 7:00。 | |
Shipment |
pickups[] |
对象数组 (VisitRequest) |
这是相应货件的所有可能取件选项的列表。优化器会选择最适合的方案来解决您的问题。对于此狗狗日托场景，请列出每位主人为每只狗狗提供的接送地点和时间范围。 |
deliveries[] |
对象数组 (VisitRequest) |
这是相应货件的所有可能送达选项的列表。优化器会选择最适合的方案来解决您的问题。对于此狗狗日托场景，请列出狗狗日托设施的位置，以及司机需要返回为每只狗狗送午餐的时间窗口。 | |
label |
字符串 | 这是您请求中特定配送的标识符。 您可以在请求中指定标签，以便更轻松地解读响应。对于此狗狗日托服务场景，请使用“吉娃娃”“伯恩山犬”或狗狗的名字等描述性字符串，以便在收到 API 响应时将解决方案与您的输入相匹配。 | |
VisitRequest |
arrivalWaypoint[] |
object (Waypoint) |
这是路线中特定拜访的地点。您可以使用纬度和经度坐标、地点 ID 或航向来定义此参数。在此狗狗日托服务场景中，对于 pickups，请将此属性设置为主人提供的地点；对于 deliveries，请将此属性设置为日托中心的地址。 |
timeWindows[] |
对象数组 (TimeWindow) |
这是一个对象数组，用于定义取货或送货的时间限制。在此场景中，您可以使用此参数为每只狗定义取货时间窗口，以及将狗送到日托中心的接受时间窗口。 | |
Vehicle |
startWaypoint[] |
object (Waypoint) |
这是车辆路线的起点，使用纬度和经度坐标或地点 ID 定义。此参数用于告知优化器车辆必须从何处开始路线。如果您未定义此途经点，优化器会选择其中一个取货点或送货点作为起始位置。在此狗狗日托场景中，由于司机从日托机构开始一天的行程，因此请使用 Mission Dolores Park 的坐标。 |
endWaypoint[] |
object (Waypoint) |
这是车辆路线的最终目的地，使用纬度和经度坐标或地点 ID 定义。此参数用于告知优化器车辆必须在何处结束路线。如果您未定义此航点，优化器会选择其中一个取货点或送货点作为路线的终点。对于此狗狗日托场景，由于司机必须在日托机构结束一天的工作，因此请使用 Mission Dolores Park 的坐标。 | |
costPerHour |
数值 | 这是车辆每使用一小时所产生的费用，无论车辆是在行驶还是停止。对于此狗狗日托场景，请使用此函数来模拟司机的时薪。 | |
startTimeWindows[] |
对象数组 (TimeWindow) |
这是司机开始驾驶面包车接送狗狗的早上时间窗口。 | |
endTimeWindows[] |
对象数组 (TimeWindow) |
这是司机完成面包车驾驶并返回宠物日托中心的合理时间范围。 |