Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

发出您的首个路线优化请求

欧洲经济区 (EEA) 开发者

本文档将向您展示如何使用实际应用场景向 Route Optimization 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 日，司机有以下任务：

在科伊特塔附近接一只伯恩山犬。
在南日落游乐场公园接一只吉娃娃。
将两只狗送到 Mission Dolores 公园的狗狗日托中心。

您需要一条路线，以最大限度地缩短狗狗在面包车中的时间，同时满足接送要求。

准备工作

如需运行此示例场景中的代码，您必须先完成设置 Route Optimization API 中的说明。

1. 选择路线优化方法

Route Optimization 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 消息。您可以在此处定义每位狗主人偏好的接送地点和时间，以及日托中心送狗的地点和时间。
1. 对于每只狗，创建一个 VisitRequest 用于接送，另一个用于送达，在此场景中，送达是指日托送达。
  - 在接送中，将 arrivalWaypoint 设置为狗狗的接送地点（伯恩山犬为科伊特塔，吉娃娃为南日落游乐场公园），并将 timeWindows 设置为主人要求的上车时间（上午 7:30 至上午 9:30）。
  - 在送达中，将 arrivalWaypoint 设置为日托中心，并将 timeWindows 设置为要求的送达时间（上午 9:30 至上午 11:30）。
  如需详细了解时间窗口，请参阅时间窗口。
2. 您可以使用 label 字段为每批货物添加标识符，例如“伯恩山犬”和“吉娃娃”。这有助于您在响应中识别发货。
如需详细了解如何定义发货，请参阅发货。
定义车辆。在 vehicles 字段中，为您的面包车添加一条 Vehicle 消息，其中包含日托中心作为起点和终点、司机的工资成本以及面包车的营业时间。
1. 将面包车的 startWaypoint 和 endWaypoint 设置为当天的起点和终点，即 Mission Dolores 公园附近的日托中心。
2. 为了最大限度地降低运营成本，您必须定义业务的成本限制。将成本参数 costPerHour 设置为 27，即您支付给司机驾驶狗狗日托面包车的费用。如需详细了解成本参数，请参阅成本模型。
  
  重要提示：成本对于优化器找到最佳路线至关重要。如果没有成本，优化器会将所有解决方案视为相等。
3. 为确保优化器在面包车的运营时间内创建路线，请将 startTimeWindows 定义为司机开始运营面包车的可接受范围，并将 endTimeWindows 定义为司机必须返回日托中心的可接受范围。如需详细了解时间窗口，请参阅时间窗口。
如需详细了解如何定义车辆，请参阅车辆。
设置全局时间窗口。全局时间窗口表示面包车在一天中可以为您的日托中心执行接送的时段。在此场景中，将 globalStartTime 设置为上午 7:00，并将 globalEndTime 设置为晚上 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
                }
              }
            },
            "timeWindows": [
              {
                "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
                }
              }
            },
            "timeWindows": [
              {
                "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

请求中使用的请求参数

下表介绍了示例场景的请求正文中使用的请求参数。您可以按父级或按文本搜索过滤内容。

Parent	参数	物业类型	说明
`OptimizeToursRequest`	`model`	对象 (`ShipmentModel`)	这是请求的核心。这是一个对象，您可以在其中定义整个问题，包括需要接送的所有狗 (`shipments`) 和车队中的面包车 (`vehicles`)。您可以将其视为需要优化的问题的完整蓝图。
`OptimizeToursRequest`	`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[]`	对象 (`Waypoint`)	这是路线中特定访问的地点。您可以使用纬度和经度坐标、地点 ID 或航向来定义此项。在此狗狗日托场景中，请将其设置为主人为`pickups`提供的地点，并设置为日托中心的地址（针对`deliveries`）。
`VisitRequest`	`timeWindows[]`	对象数组 (`TimeWindow`)	这是一个对象数组，用于定义接送或送货的时间限制。在此场景中，请使用此项为每只狗定义接送时间窗口，以及在日托中心送狗的可接受时间窗口。
`Vehicle`	`startWaypoint[]`	对象 (`Waypoint`)	这是车辆路线的起点，使用纬度和经度坐标或地点 ID 定义。此参数会告知优化器车辆必须从何处开始路线。如果您未定义此航点，优化器会选择其中一个接送作为起点。对于此狗狗日托场景，由于司机从日托设施开始一天的工作，因此请使用 Mission Dolores 公园的坐标。
	`endWaypoint[]`	对象 (`Waypoint`)	这是车辆路线的最终目的地，使用纬度和经度坐标或地点 ID 定义。此参数会告知优化器车辆必须在何处结束路线。如果您未定义此航点，优化器会选择其中一个接送作为路线的终点。对于此狗狗日托场景，由于司机必须在日托设施结束一天的工作，因此请使用 Mission Dolores 公园的坐标。
	`costPerHour`	数值	这是车辆每使用一小时所产生的费用，无论车辆是在行驶还是停止。对于此狗狗日托场景，请使用此项来模拟司机的时薪。
	`startTimeWindows[]`	对象数组 (`TimeWindow`)	这是司机开始驾驶面包车进行上午狗狗接送的可接受时间窗口。
	`endTimeWindows[]`	对象数组 (`TimeWindow`)	这是司机完成驾驶面包车并停回狗狗日托中心的可接受时间窗口。

下一步

解读响应