Configurar tempos limite e prazos

Este documento explica como configurar as definições de tempo limite e prazo para solicitações da API Route Optimization. Não definir esses valores ou defini-los incorretamente pode causar problemas de conexão ou de qualidade da resposta.

Você define o tempo limite no corpo da solicitação e o prazo no cabeçalho da solicitação. A API Route Optimization processa a solicitação dentro do limite de tempo definido por esses parâmetros, respeitando o menor valor de tempo.

A configuração de tempos limite e prazos permite gerenciar o tempo de processamento das seguintes maneiras:

• Aumentar o tempo de processamento:
  • Resolver solicitações de alta complexidade.
  • Obter uma resposta de maior qualidade.
• Diminuir o tempo de processamento:
  • Resolver solicitações de baixa complexidade mais rápido do que o padrão.
  • Resolver uma solicitação em menos tempo, mas receber uma resposta de qualidade inferior.

Observação: os parâmetros de tempo limite e prazo só se aplicam quando solvingMode está definido como o valor padrão de DEFAULT_SOLVE. Outras opções de solvingMode, como VALIDATE_ONLY, DETECT_SOME_INFEASIBLE_SHIPMENTS ou TRANSFORM_AND_RETURN_REQUEST, normalmente não exigem ajustes de tempo limite porque são significativamente mais rápidas.

Entender as necessidades de tempo limite e prazo

Revise esta seção antes de configurar os tempos limite e prazos para verificar se você entende como as escolhas de endpoint e protocolo afetam essas configurações.

As diretrizes a seguir podem ajudar você a confirmar se está usando a configuração certa para seus objetivos.

• Use endpoints não bloqueadores para solicitações contínuas e repetidas e para solicitações complexas que se beneficiam de tempos de resolução mais longos.
• Use endpoints de bloqueio para solicitações pequenas e entrega rápida de resultados, aceitando uma compensação de qualidade.
• Use gRPC para seu fluxo de trabalho diário, principalmente para aplicativos de produção.
• Use REST para testes, experimentos ou solicitações únicas.

Clique no botão abaixo para ver um diagrama que pode ajudar você a determinar quais seções deste documento são mais relevantes para sua configuração.

Abrir diagrama em uma guia separadaopen_in_new

Definir o parâmetro timeout

Defina o valor do parâmetro timeout no corpo da solicitação para especificar o tempo máximo que o servidor trabalha em uma solicitação antes de retornar uma resposta. O tempo real gasto pode ser menor que o tempo alocado se a API encontrar uma solução ideal antes de atingir o tempo máximo alocado.

Defina o timeout parâmetro usando o buffer de protocolo de duração, que é uma duração em segundos que pode variar de 1 segundo a 1800 segundos. Aumente esse valor para até 3600 segundos usando allowLargeDeadlineDespiteInterruptionRisk.

Valores timeout recomendados

A tabela a seguir lista os valores timeout recomendados com base na complexidade da solicitação e no número de remessas e veículos.

Definir o prazo

Defina o prazo no cabeçalho da solicitação para definir o tempo máximo que a API Route Optimization gasta processando uma solicitação. As subseções a seguir descrevem como definir prazos para solicitações REST e gRPC.

Solicitações REST

Ao usar REST para chamar um endpoint de bloqueio, é possível estender o prazo além do padrão de 60 segundos, que geralmente é muito curto para solicitações complexas. Faça isso mesmo que já tenha especificado um prazo maior no corpo da solicitação, já que o prazo padrão substitui todos os valores timeout definidos no corpo da solicitação que sejam maiores que 60 segundos.

Estenda o prazo além dos 60 segundos padrão definindo o cabeçalho da solicitação X-Server-Timeout. Ao contrário do corpo da solicitação, o valor do cabeçalho é o número de segundos, mas sem um sufixo "s". O valor máximo que pode ser definido para esse cabeçalho está alinhado às restrições do parâmetro timeout.

O exemplo de código a seguir mostra um cabeçalho HTTP com X-Server-Timeout definido como 1800 segundos.

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

Bibliotecas de cliente e solicitações gRPC

Não é necessário configurar um prazo ao usar bibliotecas de cliente ou gRPC. O prazo padrão ao usá-los é de 3600 segundos, o tempo máximo de solicitação para essa API. Configure o tempo de resolução definindo apenas a propriedade de tempo limite no corpo da solicitação.

Parâmetros que afetam tempos limite e prazos

Os parâmetros a seguir afetam o funcionamento de tempos limite e prazos:

• Controle o prazo máximo da solicitação com allowLargeDeadlineDespiteInterruptionRisk.
• Defina o comportamento da pesquisa, equilibrando a qualidade da solução de balanceamento com a latência usando searchMode.

allowLargeDeadlineDespiteInterruptionRisk

O allowLargeDeadlineDespiteInterruptionRisk parâmetro aumenta o prazo máximo da solicitação para 3600 segundos. Se esse parâmetro não estiver definido, o valor máximo para os parâmetros de tempo limite e prazo será de 1800 segundos.

Defina allowLargeDeadline DespiteInterruptionRisk como true para aumentar o valor dos parâmetros de tempo limite e prazo para até 3600 segundos.

Os valores permitidos para allowLargeDeadline DespiteInterruptionRisk são os seguintes:

• true: aumenta o valor máximo para os parâmetros de tempo limite e prazo para 3600 segundos, reconhecendo o risco de interrupção.
• false (padrão): mantém o valor máximo para os parâmetros de tempo limite e prazo de 1800 segundos.

Se você acredita que precisa de um tempo limite maior que 3600 segundos, entre em contato com seu representante do Google.

searchMode

O parâmetro searchMode controla como o otimizador pesquisa por soluções, permitindo que você priorize uma resposta mais rápida (menor latência) ou uma solução de maior qualidade.

Quando você prioriza uma maior qualidade da solução, o otimizador leva um tempo razoável para encontrar uma solução de alta qualidade. Para essas solicitações mais longas, considere definir um tempo limite maior e usar endpoints não bloqueadores para evitar problemas de conexão.

Os valores permitidos para searchMode são os seguintes:

• SEARCH_MODE_UNSPECIFIED (padrão): um modo de pesquisa não especificado, equivalente a RETURN_FAST.
• RETURN_FAST: interrompe a pesquisa depois de encontrar a primeira boa solução.
• CONSUME_ALL_AVAILABLE_TIME: gasta todo o tempo disponível pesquisando soluções melhores. A API não usa todo o tempo disponível se encontrar uma solução ideal mais cedo.

Ativar pings de keepalive

Ao fazer solicitações para endpoints de bloqueio com um tempo limite maior que 60 segundos, os pings de keepalive ajudam a evitar a perda de conexão enquanto você aguarda uma resposta. Os pings de keepalive são pequenos pacotes enviados para manter a atividade de conexão e para detectar e evitar a perda de conexão.

Configure esses parâmetros com base no protocolo de API que você usa:

• REST:configure o keepalive no nível da conexão TCP.
• gRPC:configure pings de keepalive no soquete TCP subjacente ou diretamente no protocolo gRPC.

As seções a seguir explicam como configurar pings de keepalive para os dois protocolos.

Keepalive REST

A configuração de pings de keepalive ao usar REST depende da biblioteca de cliente HTTP. Bibliotecas de cliente e ferramentas, como curl, podem fornecer opções de configuração específicas ou ativar pings automaticamente.

Se a biblioteca expõe o soquete TCP subjacente, é possível configurar pings de keepalive diretamente no soquete TCP usando opções como SO_KEEPALIVE. Para fazer isso, use funções como setsockopt() ou equivalentes.

Essa função hospedada no GitHub demonstra como configurar isso corretamente para o cliente HTTP integrado do Python.

Encontre mais detalhes sobre o keepalive no nível TCP na visão geral do keepalive TLDP ou na documentação da biblioteca de cliente HTTP.

Keepalive gRPC

O gRPC oferece um mecanismo de keepalive integrado como parte do protocolo. Consulte o guia de keepalive do gRPC para instruções sobre como configurar isso na linguagem do cliente.

Observação:os servidores gRPC podem recusar clientes que enviam muitos pings. Evite definir a frequência de ping de keepalive muito alta.

Solicitação de amostra do gRPC com keepalive

O exemplo a seguir mostra como fazer uma solicitação optimizeTours usando a biblioteca de cliente Python e pings de keepalive no nível do 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)