Configurare timeout e scadenze

Questo documento spiega come configurare le impostazioni di timeout e scadenza per le richieste dell'API Route Optimization. Se non imposti questi valori o li imposti in modo errato, potrebbero verificarsi problemi di connessione o di qualità della risposta.

Il timeout viene definito nel corpo della richiesta e la scadenza nell'intestazione della richiesta. L'API Route Optimization elabora la richiesta entro il limite di tempo definito da questi parametri, rispettando il valore di tempo più breve.

La configurazione di timeout e scadenze ti consente di gestire il tempo di elaborazione nei seguenti modi:

  • Aumenta il tempo di elaborazione:
    • Risolvere richieste molto complesse.
    • Ottenere una risposta di qualità superiore.
  • Riduci i tempi di elaborazione:
    • Risolvere le richieste a bassa complessità più velocemente rispetto al valore predefinito.
    • Risolvi una richiesta in meno tempo, ma ottieni una risposta di qualità inferiore.

Comprendi le tue esigenze di timeout e scadenza

Consulta questa sezione prima di configurare i timeout e le scadenze per verificare di aver compreso in che modo le scelte relative agli endpoint e ai protocolli influiscono su queste impostazioni.

Le seguenti linee guida possono aiutarti a verificare se stai utilizzando la configurazione corretta per i tuoi obiettivi.

  • Utilizza gli endpoint non bloccanti per richieste continue e ripetute e per richieste complesse che traggono vantaggio da tempi di risoluzione più lunghi.
  • Utilizza gli endpoint di blocco per richieste di piccole dimensioni e una consegna rapida dei risultati, accettando un compromesso in termini di qualità.
  • Utilizza gRPC per il tuo flusso di lavoro quotidiano, in particolare per le applicazioni di produzione.
  • Utilizza REST per test, esperimenti o richieste una tantum.

Fai clic sul pulsante di seguito per visualizzare un diagramma che può aiutarti a determinare quali sezioni di questo documento sono più pertinenti alla tua configurazione.

Apri il diagramma in una scheda separata

Imposta il parametro timeout

Imposta il valore del parametro timeout nel corpo della richiesta per specificare il tempo massimo di elaborazione di una richiesta da parte del server prima di restituire una risposta. Il tempo effettivamente impiegato potrebbe essere inferiore al tempo assegnato se l'API trova una soluzione ottimale prima di raggiungere il tempo massimo assegnato.

Imposta il parametro timeout utilizzando il buffer di protocollo della durata, che è una durata in secondi che può variare da 1 secondo a 1800 secondi. Aumenta questo valore fino a 3600 secondi utilizzando allowLargeDeadlineDespiteInterruptionRisk.

La tabella seguente elenca i valori timeout consigliati in base alla complessità della richiesta e al numero di spedizioni e veicoli.

Numero di spedizioni e veicoli Nessun vincolo Finestre temporali e vincoli di carico flessibili o percorsi lunghi Finestre temporali ristrette, vincoli di carico, vincoli complessi o percorsi molto lunghi
1 - 8 2s 2s 5 s
9 - 32 5 s 10 sec 20 sec
33 - 100 15 sec 30 sec 60 sec
101-1000 45s 90 secondi 180s
1001-10.000 120 s 360s 900s
10.001 o più 60 s + 120 s per 10.000 spedizioni 360 per 10.000 spedizioni 900 s per 10.000 spedizioni

Imposta la scadenza

Imposta la scadenza nell'intestazione della richiesta per definire il tempo massimo che l'API Route Optimization impiega per elaborare una richiesta. Le sezioni seguenti descrivono come impostare le scadenze per le richieste REST e gRPC.

Richieste REST

Quando utilizzi REST per chiamare un endpoint di blocco, puoi estendere la scadenza oltre il valore predefinito di 60 secondi, che spesso è troppo breve per richieste complesse. Devi farlo anche se hai già specificato una scadenza più lunga nel corpo della richiesta, poiché la scadenza predefinita sostituisce tutti i valori timeout impostati nel corpo della richiesta che sono superiori a 60 secondi.

Estendi la scadenza oltre i 60 secondi predefiniti impostando l'intestazione della richiesta X-Server-Timeout. A differenza del corpo della richiesta, il valore dell'intestazione è il numero di secondi, ma senza il suffisso "s". Il valore massimo che puoi impostare per questa intestazione è in linea con le limitazioni del parametro timeout.

Il seguente esempio di codice mostra un'intestazione HTTP con X-Server-Timeout impostato su 1800 secondi.

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

Librerie client e richieste gRPC

Non è necessario configurare una scadenza quando utilizzi le librerie client o gRPC. La scadenza predefinita quando li utilizzi è di 3600 secondi, ovvero il tempo di richiesta massimo per questa API. Configura il tempo di risoluzione impostando solo la proprietà timeout nel corpo della richiesta.

Parametri che influiscono su timeout e scadenze

I seguenti parametri influiscono sul funzionamento dei timeout e delle scadenze:

  • Controlla la scadenza massima della richiesta con allowLargeDeadlineDespiteInterruptionRisk.
  • Definisci il comportamento della ricerca, bilanciando la qualità della soluzione con la latenza con searchMode.

allowLargeDeadlineDespiteInterruptionRisk

Il parametro allowLargeDeadlineDespiteInterruptionRisk aumenta la scadenza massima della richiesta a 3600 secondi. Se questo parametro non è impostato, il valore massimo per i parametri timeout e deadline è 1800 secondi.

Imposta allowLargeDeadline DespiteInterruptionRisk su true per aumentare il valore dei parametri di timeout e scadenza fino a 3600 secondi.

I valori consentiti per allowLargeDeadline DespiteInterruptionRisk sono i seguenti:

  • true: aumenta il valore massimo dei parametri di timeout e scadenza a 3600 secondi, riconoscendo al contempo il rischio di interruzione.
  • false (predefinito): mantiene il valore massimo per i parametri di timeout e scadenza di 1800 secondi.

Se ritieni di aver bisogno di un timeout superiore a 3600 secondi, contatta il tuo rappresentante di Google.

searchMode

Il parametro searchMode controlla il modo in cui l'ottimizzatore cerca le soluzioni, consentendoti di dare la priorità a una risposta più rapida (latenza inferiore) o a una soluzione di qualità superiore.

Quando dai la priorità a una qualità della soluzione più elevata, l'ottimizzatore impiega un tempo considerevole per trovare una soluzione di alta qualità. Per queste richieste più lunghe, valuta la possibilità di impostare un timeout più lungo e di utilizzare endpoint non bloccanti per evitare problemi di connessione.

I valori consentiti per searchMode sono i seguenti:

  • SEARCH_MODE_UNSPECIFIED (predefinito): una modalità di ricerca non specificata, equivalente a RETURN_FAST.
  • RETURN_FAST: interrompe la ricerca dopo aver trovato la prima soluzione valida.
  • CONSUME_ALL_AVAILABLE_TIME: dedica tutto il tempo disponibile alla ricerca di soluzioni migliori. L'API non utilizza tutto il tempo disponibile se trova una soluzione ottimale in anticipo.

Attiva i ping keepalive

Quando effettui richieste a endpoint di blocco con un timeout superiore a 60 secondi, i ping keepalive aiutano a prevenire la perdita di connessione mentre aspetti una risposta. I ping keepalive sono piccoli pacchetti inviati per mantenere l'attività della connessione e per rilevare e prevenire la perdita della connessione.

Configura questi parametri in base al protocollo API che utilizzi:

  • REST: configura il keepalive a livello di connessione TCP.
  • gRPC: configura i ping keepalive sul socket TCP sottostante o direttamente nel protocollo gRPC.

Le sezioni seguenti spiegano come configurare i ping keepalive per entrambi i protocolli.

Keepalive REST

La configurazione dei ping keepalive quando utilizzi REST dipende dalla libreria client HTTP. Le librerie client e gli strumenti, come curl, potrebbero fornire opzioni di configurazione specifiche o attivare i ping automaticamente.

Se la libreria espone il socket TCP sottostante, puoi configurare i ping keepalive direttamente sul socket TCP utilizzando opzioni come SO_KEEPALIVE. A questo scopo, utilizza funzioni come setsockopt() o il loro equivalente.

Questa funzione ospitata su GitHub mostra come configurarla correttamente per il client HTTP integrato di Python.

Per ulteriori dettagli sul keepalive a livello di TCP, consulta la panoramica sul keepalive di TLDP o la documentazione della libreria client HTTP.

Keepalive gRPC

gRPC offre un proprio meccanismo keepalive integrato come parte del protocollo. Consulta la guida al keepalive gRPC per istruzioni su come configurarlo nel linguaggio del client.

Richiesta di esempio gRPC con keepalive

L'esempio seguente mostra come effettuare una richiesta optimizeTours utilizzando la libreria client Python e i ping keepalive a livello di 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)