Использование пресетов

Пресет — это набор настроек для реализации определенного сценария или стратегии планирования. Пресеты хранятся на стороне Яндекс Маршрутизации.

Пресет содержит параметры и их значения в формате JSON. В пресетах используются те же атрибуты и опции, что и в запросах API. В запросе API можно указать имена (уникальные идентификаторы) применяемых пресетов. При выполнении такого запроса настройки из указанных пресетов встраиваются в запрос (см. Особенности включения пресетов в запрос).

Преимущества использования пресетов:

С помощью пресетов можно задавать разные сценарии планирования (например, для условий высокого или низкого спроса, для разных складов, для будней или выходных дней).
Пресеты могут использоваться многократно, что ускоряет и облегчает составление запросов API для планирования маршрутов.
При реализации интеграции можно указать в поле preset_id имя пресета, а в дальнейшем добавлять в этот пресет новые параметры без изменения настроек самой интеграции.

Пресеты планирования. Создание и использование пресетов.

Посмотреть видео

Каждый пресет относится к одному из типов:

depot — настройки склада,
location — настройки заказа,
vehicle — настройки курьера или автомобиля,
vehicle-shift — настройки смены курьера,
options — глобальные опции.

Пресет определенного типа может быть включен только в соответствующее поле запроса API. Если поле запроса API является массивом и содержит несколько элементов, каждый элемент может содержать обращение к пресету. При этом объект может содержать обращение только к одному пресету.

Структура запроса API с пресетами

{
   "depots": [
        {
            "id": "depot1",
            "preset_id": "depot_preset_1",
            ...
        },
    ],
    "locations": [
        {
             "id": "order1",
             "preset_id": "location_preset_1",
             ...
        },
        {
             "id": "order2",
             "preset_id": "location_preset_2",
             ...
        },
        ...
    ],
    "vehicles": [
        {
            "id": "vehicle1",
             "preset_id": "vehicle_preset_1",
             ...
             "shifts": [
                  {
                      "id": "0",
                      "preset_id": "vehicle-shift_preset_fo",
                       ...
                  },
                  ...
              ],
        },
        ...
    ],
    "options": {
        "preset_id": "options_preset_id",
        ...
     }
}

Поля, которые нельзя использовать в пресетах

depot:
- address
- description
- id
- point
- ref
- title
location:
- address
- client_id
- comments
- delivery_to
- delivery_to_any
- depot_id
- description
- id
- phone
- pickup_from_any
- point
- ref
- title
- type
vehicle:
- depot_id
- ending_depot_id
- finish_at
- fixed_planned_route
- global_proximity_attraction_point
- id
- imei
- fixed_work_breaks
- middle_depot_id
- phone
- planned_route
- ref
- shifts
- start_at
- starting_depot_id
- visited_locations
vehicle-shift:
- id
options:
- date
- location_groups

Примечание

При получении запроса API, содержащего обращение к пресету, алгоритм подставляет значения параметров из пресета в текст запроса, а само обращение удаляет. В итоговом запросе, который обрабатывает алгоритм, нет используемых имен пресетов.

Публичные пресеты

Публичные пресеты могут использоваться всеми компаниями, но недоступны для редактирования.

Публичные пресеты состоят из нескольких частей, которые имеют одинаковое название, но относятся к разным типам — для объектов depots, locations, vehicles, vehicles.shifts, options. Все части пресета должны использоваться совместно, по отдельности использовать их неэффективно.

Публичные пресеты разработаны для определенных сценариев. Их настройки подобраны на большом количестве задач и позволяют оптимизировать решение в большинстве случаев. Это не исключает, что для конкретной задачи возможно подобрать параметры, которые позволят еще улучшить результат.

В настоящее время в сервисе есть публичный пресет public_minimize_mileage, настройки в нем ориентированы на минимизацию пробега.

Особенности включения пресетов в запрос

Если один и тот же параметр определен и в пресете, и в запросе пользователя, значение от пользователя считается приоритетным. При этом параметр используется целиком в виде единой структуры со всеми вложенными полями.

Например, если в запросе пользователя передается параметр penalty.early и при этом используется пресет, в котором определен параметр penalty.late, в итоговый запрос будет включен параметр penalty от пользователя, а все вложенные поля penalty из пресета будут аннулированы.

Пример использования пресетов

В примере ниже курьер развозит 4 заказа. В теле запроса прописаны все необходимые параметры.

Запрос без пресетов

{
    "depots": [
        {
            "id": "Depot",
            "point": {
                "lat": 55.733974,
                "lon": 37.587093
            },
            "time_window": "07:00:00-22:00:00",
            "penalty": {
                "out_of_time": {
                    "fixed": 0,
                    "minute": 200
                }
            },
            "hard_window": false
        }
    ],
    "locations": [
        {
            "id": "Order 1",
            "point": {
                "lat": 55.790514,
                "lon": 37.660161
            },
            "shipment_size": {
                "weight_kg": 19
            },
            "time_window": "09:00:00-18:00:00",
            "title": "Client 1",
            "penalty": {
                "out_of_time": {
                    "fixed": 0,
                    "minute": 200
                }
            },
            "hard_window": false
        },
        {
            "id": "Order 2",
            "point": {
                "lat": 55.798874,
                "lon": 37.612227
            },
            "shipment_size": {
                "weight_kg": 61
            },
            "time_window": "09:00:00-18:00:00",
            "title": "Client 2",
            "penalty": {
                "out_of_time": {
                    "fixed": 0,
                    "minute": 200
                }
            },
            "hard_window": false
        },
        {
            "id": "Order 3",
            "point": {
                "lat": 55.734126,
                "lon": 37.671705
            },
            "shipment_size": {
                "weight_kg": 18
            },
            "time_window": "09:00:00-18:00:00",
            "title": "Client 3",
            "penalty": {
                "out_of_time": {
                    "fixed": 0,
                    "minute": 200
                }
            },
            "hard_window": false
        },
        {
            "id": "Order 4",
            "point": {
                "lat": 55.662039,
                "lon": 37.556963
            },
            "shipment_size": {
                "weight_kg": 30
            },
            "time_window": "09:00:00-18:00:00",
            "title": "Client 4",
            "penalty": {
                "out_of_time": {
                    "fixed": 0,
                    "minute": 200
                }
            },
            "hard_window": false
        }
    ],
    "vehicles": [
        {
            "capacity": {
                "weight_kg": 800
            },
            "id": "Courier 1",
            "return_to_depot": false,
            "cost": {
                "km": 60,
                "fixed": 1000
            },
            "shifts": [
                {
                    "id": "0",
                    "time_window": "08:00:00-16:00:00",
                    "penalty": {
                        "out_of_time": {
                            "fixed": 0,
                            "minute": 200
                        }
                    },
                    "hard_window": false
                }
            ]
        }
    ],
    "options": {
        "time_zone": 3,
        "date": "2023-04-28",
        "quality": "normal",
        "proximity_factor": 0.1,
        "post_optimization": true,
        "global_proximity_factor": 0.2
    }
}

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

Настройки в пресете public_minimize_mileage

depot:

"body": {
    "penalty": {
        "out_of_time": {
            "fixed": 0,
            "minute": 200
        }
    }

location:

"body": {
    "penalty": {
        "out_of_time": {
            "fixed": 0,
            "minute": 200
            }
        },
    "hard_window": false
}

vehicle:

"body": {
    "cost": {
        "km": 60,
        "fixed": 1000
    }
}

vehicle-shift:

"body": {
    "penalty": {
        "out_of_time": {
            "fixed": 0,
            "minute": 200
        }
    }
}

options:

"body": {
    "quality": "normal",
    "proximity_factor": 0.1,
    "post_optimization": true,
    "global_proximity_factor": 0.2
}

Если в запросе использовать пресет public_minimize_mileage, тело запроса сократится.

Запрос с пресетом

{
    "depots": [
        {
            "id": "Depot",
            "preset_id": "public_minimize_mileage",
            "point": {
                "lat": 55.733974,
                "lon": 37.587093
            },
            "time_window": "07:00:00-22:00:00"
        }
    ],
    "locations": [
        {
            "id": "Order 1",
            "preset_id": "public_minimize_mileage",
            "point": {
                "lat": 55.790514,
                "lon": 37.660161
            },
            "shipment_size": {
                "weight_kg": 19
            },
            "time_window": "09:00:00-18:00:00",
            "title": "Client 1"
        },
        {
            "id": "Order 2",
            "preset_id": "public_minimize_mileage",
            "point": {
                "lat": 55.798874,
                "lon": 37.612227
            },
            "shipment_size": {
                "weight_kg": 61
            },
            "time_window": "09:00:00-18:00:00",
            "title": "Client 2"
        },
        {
            "id": "Order 3",
            "preset_id": "public_minimize_mileage",
            "point": {
                "lat": 55.734126,
                "lon": 37.671705
            },
            "shipment_size": {
                "weight_kg": 18
            },
            "time_window": "09:00:00-18:00:00",
            "title": "Client 3"
        },
        {
            "id": "Order 4",
            "preset_id": "public_minimize_mileage",
            "point": {
                "lat": 55.662039,
                "lon": 37.556963
            },
            "shipment_size": {
                "weight_kg": 30
            },
            "time_window": "09:00:00-18:00:00",
            "title": "Client 4"
        }
    ],
    "vehicles": [
        {
            "capacity": {
                "weight_kg": 800
            },
            "id": "Courier 1",
            "preset_id": "public_minimize_mileage",
            "return_to_depot": false,
            "shifts": [
                {
                    "id": "0",
                    "preset_id": "public_minimize_mileage",
                    "time_window": "08:00:00-16:00:00"
                }
            ]
        }
    ],
    "options": {
        "preset_id": "public_minimize_mileage",
        "time_zone": 3,
        "date": "2023-04-28"
    }
}

Как создать пресет

Работать с пресетами можно через интерфейс или с помощью методов API.

Примечание

Название должно быть уникальным для пресетов одного типа. Оно не может начинаться с public_ и содержать символ запятой.

Если у вас возникли проблемы при создании или использовании пресетов, обратитесь в службу поддержки.

Использование публичных пресетов

Чтобы использовать пресеты из справочника и публичные пресеты, отправьте запрос к ресурсу mvrp с OAuth авторизацией:

curl -H "Content-Type: application/json" -H "Authorization: OAuth <ваш-токен>" -X POST -d <тело запроса> https://courier.yandex.ru/api/v1/vrs/add/mvrp

В заголовке Authorization: OAuth <ваш-токен> вместо <ваш-токен> укажите OAuth-токен, полученный для работы с Мониторингом.

Важно

Путь в запросе с авторизацией (с OAuth-токеном) отличается от пути, указанного в спецификации (с API-ключом).

Пример 1

В задаче 20 заказов и 2 курьера, публичные пресеты не используются.

В результате планирования длина маршрута составила 85 км.

Пример Excel ⋅ Запрос API (JSON) ⋅ Ответ API ⋅ Открыть на карте

Пример 2

То же, что и в примере 1, но для минимизации пробега используется публичный пресет public_minimize_mileage.

В запросе, который обрабатывает алгоритм планирования и который можно посмотреть по ссылке ниже, имена пресетов из набора public_minimize_mileage заменены на содержимое этих пресетов. Содержимое пресетов из набора public_minimize_mileage см. в разделе Пример использования пресетов.

В результате планирования длина маршрута составила 79 км.