Тайм-ауты и сроки

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

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

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

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

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

Поймите свои потребности в отношении времени ожидания и сроков

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

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

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

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

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

Установите параметр timeout

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

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

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

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

Установите крайний срок

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

REST-запросы

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

Увеличьте срок ожидания сверх 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 , чтобы увеличить значение параметров тайм-аута и крайнего срока до 3600 секунд.

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

  • true : увеличивает максимальное значение параметров тайм-аута и крайнего срока до 3600 секунд, признавая при этом риск прерывания.
  • false (по умолчанию): сохраняет максимальное значение для параметров тайм-аута и крайнего срока, равное 1800 секундам.

Если вы считаете, что вам необходим тайм-аут длительностью более 3600 секунд, обратитесь к представителю 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.

В следующих разделах объясняется, как настроить пинги keepalive для обоих протоколов.

REST-поддержка активности

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

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

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

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

gRPC keepalive

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

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

Пример запроса gRPC с поддержкой активности

В следующем примере показано, как выполнить запрос 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)