Configurar tempos limite e prazos

Neste documento, explicamos como definir 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 de 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.
    • Receber uma resposta de melhor qualidade.
  • Diminuir o tempo de processamento:
    • Resolva 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.

Entender suas necessidades de tempo limite e prazo

Leia 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 sem bloqueio 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 o 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 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 de protocolo de duração, que é uma duração em segundos que pode variar de 1 a 1.800 segundos. Aumente esse valor para até 3.600 segundos usando allowLargeDeadlineDespiteInterruptionRisk.

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 remessas e veículos Sem restrições Janelas de tempo e restrições de carga flexíveis ou rotas longas Janelas de tempo apertadas, restrições de carga, restrições complexas ou rotas muito longas
1 - 8 2 s 2 s 5s
9 - 32 5s 10 s 20 s
33 - 100 15s 30 s 60s
101 a 1.000 45 s Anos 90 180s
1.001 a 10.000 120s 360s 900s
10.001 ou mais 60s + 120s por 10 mil remessas 360s por 10 mil envios 900s por 10 mil remessas

Defina 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. Isso precisa ser feito mesmo que você já tenha especificado um prazo maior no corpo da solicitação, já que o prazo padrão substitui todos os valores de 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 o sufixo "s". O valor máximo que você pode definir 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 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 usá-las é 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 de solicitação com allowLargeDeadlineDespiteInterruptionRisk.
  • Defina o comportamento da pesquisa, equilibrando a qualidade da solução com a latência usando searchMode.

allowLargeDeadlineDespiteInterruptionRisk

O parâmetro allowLargeDeadlineDespiteInterruptionRisk aumenta o prazo máximo de 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 dos 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 busca 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 sem bloqueio 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 procurando soluções melhores. A API não usará todo o tempo disponível se encontrar uma solução ideal com antecedência.

Ativar pings de keepalive

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ê aguarda uma resposta. Os pings de keepalive são pequenos pacotes enviados para manter a atividade da 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 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. As bibliotecas de cliente e ferramentas, como curl, podem fornecer opções de configuração específicas ou ativar pings automaticamente.

Se a biblioteca expor o soquete TCP, será possível configurar pings de keepalive 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 isso corretamente para o cliente HTTP integrado do Python.

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

Keepalive do 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.

Exemplo de solicitação gRPC com keepalive

O exemplo a seguir mostra como fazer uma solicitação optimizeTours usando a biblioteca de cliente do 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)