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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Как установить срок

Установите крайний срок в заголовке запроса, чтобы определить максимальное время, которое 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: увеличивает максимальное значение параметров timeout и deadline до 3600 секунд, учитывая риск прерывания.
• false (по умолчанию) – максимальное значение для параметров timeout и deadline составляет 1800 секунд.

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

searchMode

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

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

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

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

Включить пинги keepalive

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

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

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

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

REST keepalive

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

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

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

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

gRPC keepalive

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

Примечание. Серверы 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)