Сделайте свой первый запрос на оптимизацию маршрута

Разработчики из Европейской экономической зоны (ЕЭЗ)

В этом документе показано, как отправить первый запрос к API оптимизации маршрутов, используя реальный пример из практики.

Для простоты в примере для демонстрации REST API используются HTTP и JSON. Однако для вашей производственной среды рекомендуется использовать gRPC из-за его преимуществ в производительности. Тем не менее, для работы с gRPC требуется некоторая установка. Для получения дополнительной информации см. клиентские библиотеки API оптимизации маршрутизации .

Сценарий

Карта Сан-Франциско с отметками на башне Койт, парке Мишн Долорес и парке Саут Сансет.

Вы управляете службой дневного ухода за собаками в Сан-Франциско с 7:00 до 19:00. Сегодня утром вам нужно забрать двух собак из разных мест города. Оба владельца собак указали вам временной интервал для забора животных с 7:30 до 9:30 утра.

У вас есть один фургон для этой работы, и вы платите водителю 27 долларов в час. Водитель и фургон начинают день в вашем детском саду в 7:00 утра и должны вернуться с утреннего забора детей к 12:00 дня, чтобы успеть на обеденный перерыв.

Сегодня 13 февраля 2024 года, и у водителя следующие задачи:

  • Заберите бернского зенненхунда возле башни Койт.
  • Забрать чихуахуа можно в парке South Sunset Playground Park.
  • Отведите обеих собак в центр дневного ухода за собаками в парке Мишн Долорес.

Вам нужен маршрут, который минимизирует время, проводимое собаками в фургоне, и при этом соответствует требованиям по посадке и высадке.

Прежде чем начать

Для запуска кода в этом примере необходимо сначала выполнить инструкции в разделе «Настройка API оптимизации маршрутов» .

1. Выберите подход к оптимизации маршрута.

API оптимизации маршрутов предлагает несколько методов на выбор в зависимости от сложности вашей задачи оптимизации.

Поскольку этот сценарий с собачьим присмотром представляет собой небольшой и простой запрос, используйте блокирующий метод, например optimizeTours , который быстро выдает результаты для небольших запросов. Для получения дополнительной информации о методах API оптимизации маршрутов см. раздел «Синхронные и асинхронные конечные точки» .

Для отправки HTTP POST-запроса к методу optimizeTours используйте следующий URL:

https://routeoptimization.googleapis.com/v1/projects/PROJECT_OR_ID:optimizeTours

Также необходимо установить короткие значения тайм-аута и крайнего срока, чтобы сократить ненужное время ожидания. В данном случае, для собачьего детского сада, оптимизатору не требуется много времени для ответа на ваш запрос, поэтому используйте следующие настройки:

  • Установите параметр timeout на 2 секунды.
  • Оставьте настройки крайнего срока по умолчанию, который составляет 60 секунд для REST-запросов.

2. Составьте тело запроса.

После выбора блокирующего метода optimizeTours и определения параметров тайм-аута и крайнего срока, следующим шагом будет формирование тела запроса.

В данном случае запрос представляет собой сообщение OptimizeToursRequest , закодированное в формате JSON в REST API.

Для формирования запроса выполните следующие шаги:

  1. Начнём с базовой структуры запроса , которая выглядит следующим образом:

    {
  "timeout": ...,
  "model": {
    "shipments": [...],
    "vehicles": [...],
    "globalStartTime": "...",
    "globalEndTime": "..."
  }
}

    Для получения более подробной информации о структуре см. руководство по ключевым концепциям базовой структуры (модель отгрузки, отгрузка и транспортное средство) .

  2. Определите порядок доставки. В поле shipments добавьте Shipment для каждой собаки, которую необходимо забрать и отвезти утром. Здесь вы указываете предпочтительное место и время забора собаки владельцем, а также место и время доставки собак в детский сад.

    1. Для каждой собаки создайте запрос VisitRequest для забора животных и еще один для доставки, который в данном случае называется "прием в детский сад".

      • В настройках приема собак установите arrivalWaypoint на место, где будет забрана собака (башня Койт для бернского зенненхунда или парк South Sunset Playground Park для чихуахуа), а timeWindows — на запрошенное владельцем время приема (с 7:30 до 9:30).

      • При оформлении доставок установите в поле arrivalWaypoint адрес детского сада, а в поле timeWindows — необходимое время высадки (с 9:30 до 11:30).

      Для получения более подробной информации о временных окнах см. раздел «Временные окна» .

    2. В поле label можно добавить идентификатор для каждой партии товара, например, «бернский зенненхунд» и «чихуахуа». Это поможет идентифицировать отправления в ответе.

    Для получения дополнительной информации об определении отгрузок см. раздел «Отгрузка» .

  3. Определите транспортные средства. В поле vehicles добавьте сообщение Vehicle для вашего фургона, указав в качестве начальной и конечной точек детский сад, стоимость заработной платы водителя и часы работы фургона.

    1. Установите startWaypoint и endWaypoint для микроавтобуса в соответствии с местоположением начала и конца дня, а именно — детский сад рядом с парком Мишн Долорес.

    2. Чтобы минимизировать операционные расходы, необходимо определить ограничения по затратам для вашего бизнеса. Установите параметр стоимости costPerHour равным 27, что соответствует сумме, которую вы платите водителю за управление фургоном для присмотра за собаками. Дополнительную информацию о параметрах стоимости см. в разделе «Модель затрат» .

    3. Чтобы оптимизатор создавал маршрут в пределах рабочего времени фургона, задайте startTimeWindows в допустимом диапазоне для начала работы водителя и endTimeWindows в допустимом диапазоне для возвращения водителя в детский сад. Дополнительную информацию о временных окнах см. в разделе «Временные окна» .

    Для получения более подробной информации об определении транспортных средств см. раздел «Транспортное средство» .

  4. Установите глобальное временное окно. Глобальное временное окно определяет временной промежуток, в течение которого фургон может забирать и привозить собак в ваш собачий детский сад в течение дня. В этом случае установите 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 Продолжительность Этот параметр определяет максимальное время, в течение которого сервер обрабатывает запрос перед возвратом ответа. Используйте этот параметр, чтобы сократить время ожидания. Для небольших и быстрых запросов, таких как этот сценарий с собачьим присмотром, установите это значение равным 2 секундам.
ShipmentModel shipments[] массив объектов ( Shipment ) Это массив объектов, где каждый объект представляет собой собаку, которую нужно забрать или отвезти.
vehicles[] массив объектов ( Vehicle ) Это массив объектов, где каждый объект определяет транспортное средство в вашем автопарке. Здесь вы описываете свои ресурсы, например, фургон, который осуществляет погрузку и разгрузку. Для получения оптимизированного маршрута необходимо определить как минимум одно транспортное средство.
globalStartTime Отметка времени Это самое раннее возможное время для любого события во всей вашей модели. Этот параметр сужает временную область задачи оптимизации, что крайне важно для точных расчетов трафика и маршрутизации. Для сценария с собачьим детским садом установите это значение на самое раннее время, когда водитель сможет управлять фургоном в течение дня, а именно 7:00 утра 13 февраля 2024 года.
globalEndTime Отметка времени Это самое позднее возможное время для любого события во всей вашей модели. Для сценария с собачьим дневным уходом установите это значение на предполагаемое время окончания работы фургона, а именно 19:00 13 февраля 2024 года.
Shipment pickups[] массив объектов ( VisitRequest ) Это список всех возможных вариантов получения груза. Оптимизатор выберет лучший вариант для решения вашей задачи. В данном случае, для собачьего детского сада, укажите места и временные интервалы, указанные каждым владельцем для каждой собаки.
deliveries[] массив объектов ( VisitRequest ) Это список всех возможных вариантов доставки груза. Оптимизатор выбирает лучший вариант для решения вашей задачи. В данном случае, для собачьего детского сада, укажите местоположение учреждения и временной интервал, когда водитель должен вернуться к обеду для каждой собаки.
label нить Это идентификатор конкретной посылки в вашем запросе. Вы можете указать метки в запросе, чтобы упростить чтение ответа. В случае с собачьим детским садом используйте описательную строку, например, "Чихуахуа", "Бернский горный пёс" или имя собаки, чтобы сопоставить решение с вашими входными данными при получении ответа от API.
VisitRequest arrivalWaypoint[] объект ( Waypoint ) Это местоположение конкретного визита на маршруте. Вы можете указать его, используя координаты широты и долготы, идентификатор места или направление. В данном случае, для собачьего детского сада, установите это место на адрес, предоставленный владельцем для pickups , и на адрес детского сада для deliveries .
timeWindows[] массив объектов ( TimeWindow ) Это массив объектов, определяющих временные ограничения для забора или доставки. В данном случае используйте его для определения временного интервала для забора каждой из собак и допустимого временного интервала для доставки собак в центр дневного ухода.
Vehicle startWaypoint[] объект ( Waypoint ) Это начальная точка маршрута транспортного средства, заданная координатами широты и долготы или идентификатором места. Этот параметр указывает оптимизатору, где транспортное средство должно начать маршрут. Если вы не укажете эту путевую точку, оптимизатор выберет одну из точек погрузки или разгрузки в качестве начальной точки. В данном случае, поскольку водитель начинает день в собачьем детском саду, используйте координаты парка Мишн Долорес.
endWaypoint[] объект ( Waypoint ) Это конечная точка маршрута транспортного средства, заданная координатами широты и долготы или идентификатором места. Этот параметр указывает оптимизатору, где транспортное средство должно завершить маршрут. Если вы не укажете эту путевую точку, оптимизатор выберет одну из точек погрузки или разгрузки в качестве конечной точки маршрута. В данном случае, для собачьего детского сада, поскольку водитель должен завершить день в этом учреждении, используйте координаты парка Мишн Долорес.
costPerHour число Это затраты, понесенные за каждый час использования транспортного средства, независимо от того, находится ли оно в движении или стоит на месте. В данном случае, применительно к собачьему детскому саду, используйте это значение для моделирования почасовой заработной платы водителя.
startTimeWindows[] массив объектов ( TimeWindow ) Это допустимый временной промежуток, в течение которого водитель может начать движение на фургоне для утреннего вывоза собак.
endTimeWindows[] массив объектов ( TimeWindow ) Это допустимый промежуток времени, в течение которого водитель может закончить движение фургона и припарковаться обратно у центра дневного ухода за собаками.

Следующий

Интерпретируйте ответ