В этом документе показано, как сделать первый запрос к Route Optimization API на примере реального сценария использования.
В примере для простоты используется HTTP и JSON, чтобы продемонстрировать REST API. Однако для рабочей среды рекомендуется использовать gRPC, поскольку он обеспечивает более высокую производительность. Однако для использования gRPC требуется установка. Подробнее о клиентских библиотеках Route Optimization API…
Сценарий
Вы предоставляете услуги дневного ухода за собаками с 7:00 до 19:00 в Сан-Франциско. Сегодня утром вам нужно забрать двух собак из разных мест в городе. Оба владельца собак указали, что забрать питомцев нужно в период с 7:30 до 9:30.
У вас есть один фургон, и вы платите водителю 27 долларов в час. Водитель и микроавтобус начинают день в вашем детском саду в 7:00 и должны вернуться после утренних поездок к 12:00, чтобы сделать перерыв на обед.
Сегодня 13 февраля 2024 года, и у водителя есть следующие задачи:
- Заберите бернскую горную собаку рядом с башней Койт.
- Заберите чихуахуа в парке South Sunset Playground.
- Оставьте обеих собак в центре дневного ухода за собаками в парке Мишн Долорес.
Вам нужно составить маршрут так, чтобы собаки провели в фургоне как можно меньше времени, но при этом были соблюдены требования к посадке и высадке.
Подготовка
Чтобы запустить код из этого примера, сначала выполните инструкции в разделе Настройка API оптимизации маршрутов.
1. Выберите подход к оптимизации маршрутов
В Route Optimization API есть несколько методов, которые можно использовать в зависимости от сложности задачи оптимизации.
Поскольку запрос в этом примере небольшой и простой, используйте блокирующий метод, например optimizeTours, который быстро возвращает результаты для небольших запросов. Подробнее о синхронных и асинхронных конечных точках…
Чтобы отправить HTTP-запрос POST к методу optimizeTours, используйте следующий URL:
https://routeoptimization.googleapis.com/v1/projects/PROJECT_OR_ID:optimizeTours
Также необходимо задать короткое время ожидания и срок, чтобы сократить ненужное время ожидания. Для сценария с передержкой собак оптимизатору не нужно много времени, чтобы ответить на запрос, поэтому используйте следующие настройки:
- Задайте для параметра
timeoutзначение "2 секунды". - Оставьте настройки крайнего срока по умолчанию (60 секунд для запросов REST).
2. Как составить тело запроса
После выбора блокирующего метода optimizeTours и определения настроек тайм-аута и крайнего срока следующим шагом будет создание тела сообщения запроса.
В этом сценарии запрос представляет собой сообщение OptimizeToursRequest, закодированное в формате JSON в REST API.
Чтобы создать сообщение запроса, выполните следующие действия:
Начните с базовой структуры запроса, которая выглядит следующим образом:
{ "timeout": ..., "model": { "shipments": [...], "vehicles": [...], "globalStartTime": "...", "globalEndTime": "..." } }Подробнее о базовой структуре (ShipmentModel, Shipment и Vehicle)…
Определите отправления. В поле
shipmentsдобавьте сообщениеShipmentдля каждой собаки, которую нужно забрать и отвезти утром. Здесь вы определяете предпочтительные места и время, когда владельцы собак могут забрать своих питомцев, а также места и время, когда центр дневного ухода может вернуть собак.Для каждой собаки создайте по одному объекту
VisitRequestдля забора и доставки (в данном случае – в детский сад).В поле
arrivalWaypointукажите место, где нужно забрать собаку (Coit Tower для бернского зенненхунда или South Sunset Playground Park для чихуахуа), а в полеtimeWindows– время, указанное владельцем (с 7:30 до 9:30).В настройках доставки укажите
arrivalWaypointв качестве детского сада иtimeWindowsв качестве времени доставки (с 9:30 до 11:30).
Подробнее о временных окнах…
Вы можете использовать поле
label, чтобы добавить идентификатор для каждой доставки, например "Бернский зенненхунд" и "Чихуахуа". Это поможет вам идентифицировать отправления в ответе.
Подробнее об определении отправлений…
Определите транспортные средства. В поле
vehiclesдобавьтеVehicleсообщение для одного микроавтобуса с детским садом в качестве начальной и конечной точек, стоимостью заработной платы водителя и часами работы микроавтобуса.Задайте для фургона значения
startWaypointиendWaypoint, соответствующие начальной и конечной точкам маршрута на день – детскому саду рядом с парком Мишн Долорес.Чтобы минимизировать операционные расходы, необходимо определить ограничения стоимости для вашего бизнеса. Установите для параметра стоимости
costPerHourзначение 27, которое соответствует сумме, которую вы платите водителю за перевозку собак. Подробнее о модели расходов…Чтобы оптимизатор создал маршрут в пределах рабочего времени водителя, задайте для параметра
startTimeWindowsдопустимый диапазон времени, когда водитель может начать работу, а для параметраendTimeWindows– допустимый диапазон времени, когда водитель должен вернуться в детский сад. Подробнее о временных окнах…
Подробнее о том, как задавать транспортные средства…
Задайте глобальный период времени. Глобальное временное окно – это период, в течение которого фургон может забирать и высаживать детей. В этом случае установите для параметра
globalStartTimeзначение 7:00, а для параметраglobalEndTime– 19:00 на 13 февраля 2024 г. Это часы работы вашего центра.
3. Отправка запроса
Ниже приведен простой запрос curl, основанный на сценарии с детским садом для собак, в котором используется блокирующий метод optimizeTours.
Прежде чем отправлять запрос, замените PROJECT_NUMBER_OR_ID в примере кода на идентификатор проекта Google Cloud.
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
Параметры, использованные в запросе.
В таблице ниже описаны параметры запроса, используемые в теле запроса в примере сценария. Вы можете отфильтровать содержимое по родительскому элементу или с помощью текстового поиска.
| Родитель | Параметр | Тип ресурса | Описание |
|---|---|---|---|
OptimizeToursRequest |
model |
объект (ShipmentModel) |
Это основная часть вашего запроса. Это единый объект, в котором вы определяете всю задачу, включая всех собак, которых нужно забрать и высадить (shipments), и фургон в вашем автопарке (vehicles). Думайте об этом как о полном плане задачи, которую вам нужно оптимизировать. |
timeout |
Продолжительность | Этот параметр задает максимальное время, в течение которого сервер обрабатывает запрос, прежде чем вернуть ответ. Используйте этот параметр, чтобы сократить время ожидания. Для небольших и быстрых запросов, таких как в этом сценарии с передержкой собак, установите значение 2s. | |
ShipmentModel |
shipments[] |
Массив объектов (Shipment) |
Это массив объектов, каждый из которых представляет собаку, которую нужно забрать или высадить. |
vehicles[] |
Массив объектов (Vehicle) |
Это массив объектов, каждый из которых определяет транспортное средство в вашем автопарке. Здесь вы описываете свои ресурсы, например фургон, который забирает и доставляет грузы. Чтобы получить оптимизированный маршрут, необходимо определить хотя бы одно транспортное средство. | |
globalStartTime |
Временная метка | Это самое раннее возможное время для любого события во всей вашей модели. Этот параметр ограничивает задачу оптимизации по времени, что важно для точного расчета трафика и маршрутов. В нашем сценарии с передержкой собак укажите самое раннее время, когда водитель может начать работу, – 7:00 13 февраля 2024 года. | |
globalEndTime |
Временная метка | Это самое позднее возможное время для любого события во всей модели. В нашем сценарии с детским садом для собак укажите время, когда фургон должен закончить работу, то есть 19:00 13 февраля 2024 года. | |
Shipment |
pickups[] |
Массив объектов (VisitRequest) |
Это список всех возможных вариантов самовывоза для отправления. Оптимизатор выбирает лучший из них для решения вашей задачи. В этом сценарии с собачьим детским садом перечислите места и временные интервалы, которые каждый владелец указал для своей собаки. |
deliveries[] |
Массив объектов (VisitRequest) |
Это список всех возможных вариантов передачи отправления. Оптимизатор выбирает лучший из них для решения вашей задачи. Для этого сценария укажите местоположение детского сада для собак и временной интервал, когда водитель должен вернуться на обед для каждой собаки. | |
label |
string | Идентификатор конкретной доставки в запросе. Вы можете указать ярлыки в запросе, чтобы ответ было легче читать. В примере с собачьим детским садом используйте описательную строку, например "Чихуахуа", "Бернский зенненхунд" или имя собаки, чтобы сопоставить решение с входными данными при получении ответа API. | |
VisitRequest |
arrivalWaypoint[] |
Объект (Waypoint) |
Это местоположение конкретного посещения на маршруте. Его можно задать с помощью координат широты и долготы, идентификатора места или направления. В нашем примере с передержкой собак укажите в свойстве pickups адрес, предоставленный владельцем, а в свойстве deliveries – адрес центра передержки. |
timeWindows[] |
Массив объектов (TimeWindow) |
Это массив объектов, которые определяют временные ограничения для самовывоза или доставки. В нашем сценарии это временные окна, в которые нужно забрать каждую собаку, и приемлемое окно для доставки собак в центр дневного ухода. | |
Vehicle |
startWaypoint[] |
объект (Waypoint) |
Начальная точка маршрута транспортного средства, заданная координатами широты и долготы или идентификатором места. Этот параметр указывает оптимизатору, где транспортное средство должно начать маршрут. Если вы не укажете эту путевую точку, оптимизатор выберет в качестве начального местоположения одну из точек получения или доставки. В этом примере водитель начинает день в центре дневного ухода за собаками, поэтому используйте координаты парка Миссия Долорес. |
endWaypoint[] |
Объект (Waypoint) |
Конечный пункт назначения маршрута транспортного средства, заданный координатами широты и долготы или идентификатором места. Этот параметр указывает оптимизатору, где транспортное средство должно завершить маршрут. Если вы не укажете эту путевую точку, оптимизатор выберет в качестве конца маршрута одну из точек получения или доставки. В этом примере водитель должен закончить день в детском саду для собак, поэтому используйте координаты парка Миссия-Долорес. | |
costPerHour |
число | Это стоимость использования автомобиля в час, независимо от того, движется он или нет. В нашем примере с передержкой собак используйте этот параметр, чтобы смоделировать почасовую оплату водителя. | |
startTimeWindows[] |
Массив объектов (TimeWindow) |
Это допустимый интервал времени, в течение которого водитель может начать поездку, чтобы забрать собак утром. | |
endTimeWindows[] |
Массив объектов (TimeWindow) |
Это допустимый интервал времени, в течение которого водитель должен закончить поездку и припарковать фургон у центра передержки. |