Este documento explica como configurar as configuraçõ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.
Ao configurar tempos limite e prazos, é possível gerenciar o tempo de processamento das seguintes maneiras:
- Aumentar o tempo de processamento:
- Resolver solicitações de alta complexidade.
- Receber 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, geralmente não exigem ajustes de tempo limite porque são significativamente mais rápidas.
Entenda suas necessidades de tempo limite e prazo
Revise esta seção antes de configurar os tempos limite e os 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 troca de qualidade.
- Use gRPC no 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 separada
Defina 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 do que o tempo alocado se a API encontrar uma solução ideal antes de atingir o tempo máximo alocado.
Defina o parâmetro timeout usando o buffer do protocolo de duração, que é uma duração em segundos que pode variar de 1 segundo a 1.800 segundos.
Aumente esse valor em até 3.600 segundos usando
allowLargeDeadlineDespiteInterruptionRisk.
Valores timeout recomendados
A tabela a seguir lista os valores recomendados de timeout com base na complexidade da solicitação e no número de remessas e veículos.
| Número de envios e veículos | Sem restrições | Janelas de tempo e restrições de carga flexíveis ou trajetos longos | Janelas de tempo apertadas, restrições de carga, restrições complexas ou trajetos muito longos |
| 1 - 8 | 2 s | 2 s | 5 s |
| 9 - 32 | 5 s | 10 s | 20 s |
| 33 - 100 | 15s | 30 s | 60s |
| 101 a 1.000 | 45 s | 90 | 180s |
| De 1.001 a 10.000 | 120s | 360s | 900s |
| 10.001 ou mais | 60s + 120s por 10 mil envios | 360s por 10 mil fretes | 900s por 10 mil fretes |
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. Você
precisa fazer isso mesmo que já tenha especificado um prazo maior no corpo
da solicitação, já que o prazo padrão substitui qualquer valor de timeout definido no
corpo da solicitação que seja maior que 60 segundos.
Para estender o prazo além dos 60 segundos padrão, defina o cabeçalho de 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 o sufixo "s". O valor máximo que você pode definir para esse cabeçalho está alinhado com as restrições do parâmetro timeout.
O exemplo de código a seguir mostra um cabeçalho HTTP com X-Server-Timeout definido como
1.800 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 usar esses métodos é de 3.600 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 e a latência com
searchMode.
allowLargeDeadlineDespiteInterruptionRisk
O parâmetro allowLargeDeadlineDespiteInterruptionRisk aumenta o prazo máximo da solicitação para 3.600 segundos. Se esse parâmetro não for definido, o valor máximo para os parâmetros de tempo limite e prazo será de 1.800 segundos.
Defina allowLargeDeadline DespiteInterruptionRisk como true para
aumentar o valor dos parâmetros de tempo limite e prazo para até 3.600 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 3.600 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 1.800 segundos.
Se você acredita que precisa de um tempo limite maior que 3.600 segundos, entre em contato com seu representante do Google.
searchMode
O parâmetro searchMode controla como o otimizador procura 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 qualidade de solução mais alta, 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:
SEARCH_MODE_UNSPECIFIED(padrão): um modo de pesquisa não especificado, equivalente aRETURN_FAST.RETURN_FAST: interrompe a pesquisa depois de encontrar a primeira boa solução.CONSUME_ALL_AVAILABLE_TIME: passa todo o tempo disponível procurando soluções melhores. A API não usa todo o tempo disponível se encontrar uma solução ideal antes.
Ativar pings de manutenção de atividade
Quando você faz 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ê espera uma resposta. Os pings keepalive são pequenos pacotes enviados para manter a atividade de conexão e 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 manutenção ativa no soquete TCP subjacente ou diretamente no protocolo gRPC.
As seções a seguir explicam como configurar pings de manutenção de atividade para os dois protocolos.
Sinal de atividade REST
A configuração de pings de sinal de atividade ao usar REST depende da biblioteca de cliente HTTP. As bibliotecas de cliente e ferramentas, como curl, podem oferecer opções de configuração específicas ou ativar pings automaticamente.
Se a biblioteca expuser o soquete TCP subjacente, você poderá configurar pings de
manutenção de atividade diretamente no soquete TCP usando opções como SO_KEEPALIVE. Para isso, use funções como setsockopt() ou equivalentes.
Esta função hospedada no GitHub demonstra como configurar corretamente para o cliente HTTP integrado do Python.
Encontre mais detalhes sobre sinais de atividade no nível TCP na visão geral de sinais de atividade do TLDP ou na documentação da biblioteca de cliente HTTP.
Sinal de atividade do gRPC
O gRPC oferece um mecanismo de manutenção de atividade 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 pings em excesso. Evite definir uma frequência muito alta para o ping de manutenção de atividade.
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 manutenção de atividade 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)