Как настроить сроки ожидания и крайние сроки

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

Тайм-аут задается в теле запроса, а крайний срок – в заголовке. Route Optimization API обрабатывает запрос в течение времени, заданного этими параметрами, с учетом наименьшего значения.

Настройка сроков ожидания и крайних сроков позволяет управлять временем обработки следующими способами:

• Увеличьте время обработки
  • Решать сложные задачи.
  • Получить более качественный ответ.
• Сократите время обработки:
  • Быстрее, чем по умолчанию, решать простые задачи.
  • Быстрое выполнение запроса, но ответ более низкого качества.

Примечание. Параметры timeout и deadline применяются, только если для solvingMode задано значение по умолчанию DEFAULT_SOLVE. Другие варианты solvingMode, такие как VALIDATE_ONLY, DETECT_SOME_INFEASIBLE_SHIPMENTS или TRANSFORM_AND_RETURN_REQUEST, обычно не требуют корректировки времени ожидания, поскольку они значительно быстрее.

Определите, какие тайм-ауты и сроки вам нужны

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

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

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

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

Открыть диаграмму в отдельной вкладке

Как настроить параметр timeout

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

Задайте параметр timeout с помощью буфера протокола duration. Это продолжительность в секундах, которая может составлять от 1 до 1800 секунд. Увеличьте это значение до 3600 секунд с помощью allowLargeDeadlineDespiteInterruptionRisk.

Рекомендуемые значения timeout

В таблице ниже приведены рекомендуемые значения timeout в зависимости от сложности запроса, количества перевозок и транспортных средств.

Количество отправлений и транспортных средств	Без ограничений	Слишком широкие временные окна, ограничения по загрузке или длинные маршруты	Узкие временные окна, ограничения по загрузке, сложные ограничения или очень длинные маршруты
1–8	2 сек.	2 сек.	5 сек.
9–32	5 сек.	10 сек.	20 сек.
33–100	15 сек.	30 сек.	60 сек.
101–1000	45 сек.	90-е	180 сек.
1001–10 000	120 сек.	360s	900 сек.
10 001 и более	60 сек. + 120 сек. на каждые 10 000 отправлений	360 на 10 000 отправлений	900 секунд на 10 000 отправлений

Установите срок сдачи

Установите крайний срок в заголовке запроса, чтобы определить максимальное время, которое Route Optimization API тратит на обработку запроса. В следующих подразделах описывается, как установить сроки для запросов REST и gRPC.

Запросы REST

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

Чтобы продлить срок, задайте заголовок запроса X-Server-Timeout. В отличие от тела запроса, значением заголовка является количество секунд без суффикса "s". Максимальное значение, которое можно задать для этого заголовка, соответствует ограничениям параметра timeout.

В примере кода ниже показан HTTP-заголовок, в котором для X-Server-Timeout задано значение 1800 секунд.

curl -X POST 'https://routeoptimization.googleapis.com/v1/projects/:optimizeTours' \
-H "Content-Type: application/json" \
-H "X-Server-Timeout: 1800" \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
--data @- << EOM
{
  "model": {
    ...
  }
}
EOM

Клиентские библиотеки и запросы gRPC

При использовании клиентских библиотек или gRPC настраивать крайний срок не нужно. По умолчанию срок составляет 3600 секунд – это максимальное время запроса для этого API. Настройте время решения, задав только свойство timeout в теле запроса.

Параметры, влияющие на время ожидания и сроки

На работу тайм-аутов и сроков влияют следующие параметры:

• Управляйте максимальным сроком запроса с помощью allowLargeDeadlineDespiteInterruptionRisk.
• Определите поведение поиска, балансируя качество решения и задержку с помощью searchMode.

allowLargeDeadlineDespiteInterruptionRisk

Параметр allowLargeDeadlineDespiteInterruptionRisk увеличивает максимальный срок выполнения запроса до 3600 секунд. Если этот параметр не задан, максимальное значение для параметров timeout и deadline составляет 1800 секунд.

Установите для параметра allowLargeDeadline DespiteInterruptionRisk значение true, чтобы увеличить значения параметров timeout и deadline до 3600 секунд.

Примечание. Если задать для параметра allowLargeDeadline DespiteInterruptionRisk значение true, это будет означать, что вы понимаете, что более длинные запросы связаны с более высоким риском прерывания, что может привести к ошибке вместо действительного результата.

Допустимые значения для allowLargeDeadline DespiteInterruptionRisk:

• true – увеличивает максимальное значение параметров timeout и deadline до 3600 секунд, учитывая риск прерывания.
• false (по умолчанию) – сохраняет максимальное значение для параметров timeout и deadline, равное 1800 секундам.

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

searchMode

Параметр searchMode определяет, как оптимизатор ищет решения. Вы можете выбрать, что для вас важнее: более быстрый ответ (меньшая задержка) или более высокое качество решения.

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

Допустимые значения для searchMode:

• SEARCH_MODE_UNSPECIFIED (по умолчанию) – режим поиска не указан, эквивалентно RETURN_FAST.
• RETURN_FAST – поиск останавливается после нахождения первого подходящего решения.
• CONSUME_ALL_AVAILABLE_TIME: тратит все доступное время на поиск лучших решений. API не использует все доступное время, если находит оптимальное решение раньше.

Включить эхо-запросы keepalive

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

Настройте эти параметры в зависимости от используемого протокола API:

• REST. Настройте поддержку активности на уровне TCP-подключения.
• gRPC. Настройте эхо-запросы keepalive на базовом сокете TCP или непосредственно в протоколе gRPC.

В разделах ниже рассказывается, как настроить эхо-запросы для обоих протоколов.

REST keepalive

Настройка сообщений keepalive при использовании REST зависит от клиентской библиотеки HTTP-клиента. Клиентские библиотеки и инструменты, такие как curl, могут предоставлять определенные параметры конфигурации или автоматически включать пинг-запросы.

Если библиотека предоставляет доступ к базовому сокету TCP, вы можете настроить эхо-запросы keepalive непосредственно в сокете TCP, используя такие параметры, как SO_KEEPALIVE. Для этого используйте функции, например setsockopt(), или их эквиваленты.

В функции, размещенной на GitHub, показано, как правильно настроить это для встроенного HTTP-клиента Python.

Дополнительную информацию о keepalive на уровне TCP можно найти в обзоре TLDP keepalive или в документации по HTTP-клиентской библиотеке.

gRPC keepalive

В протокол gRPC встроен собственный механизм поддержания активности. Инструкции по настройке для языка клиента можно найти в руководстве по gRPC keepalive.

Примечание. Серверы gRPC могут отклонять клиентов, которые отправляют слишком много запросов ping. Не устанавливайте слишком высокую частоту отправки эхо-запросов.

Пример запроса gRPC с keepalive

В примере ниже показано, как создать запрос optimizeTours с помощью клиентской библиотеки Python и эхо-запросов keepalive на уровне gRPC.

from google.maps import routeoptimization_v1 as ro
from google.maps.routeoptimization_v1.services.route_optimization.transports import grpc as grpc_transport
import sys

_REQUEST_TIMEOUT_SECONDS = 1800
_KEEPALIVE_PING_SECONDS = 30

def create_channel(*args, **kwargs):
  raw_options = kwargs.pop("options", ())
  options = dict(raw_options)
  options["grpc.keepalive_time_ms"] = _KEEPALIVE_PING_SECONDS * 1000
  options["grpc.keepalive_timeout_ms"] = 5000
  # Allow any number of pings between the request and the response.
  options["grpc.http2.max_pings_without_data"] = 0
  print(f"Using options: {options}", file=sys.stderr)
  return grpc_transport.RouteOptimizationGrpcTransport.create_channel(
      *args,
      options=list(options.items()),
      **kwargs,
  )

def create_grpc_transport(*args, **kwargs):
  if "channel" in kwargs:
    raise ValueError(
        "`channel` is overridden by this function, and must not be provided."
    )
  return grpc_transport.RouteOptimizationGrpcTransport(
      *args,
      channel=create_channel,
      **kwargs,
  )

def run_optimize_tours(request):
  client = ro.RouteOptimizationClient(transport=create_grpc_transport)
  return client.optimize_tours(request, timeout=_REQUEST_TIMEOUT_SECONDS)