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, possono verificarsi problemi di connessione o di qualità della risposta.

Definisci il timeout 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 consente di gestire il tempo di elaborazione nei seguenti modi:

  • Aumenta il tempo di elaborazione:
    • Risolvi le richieste di elevata complessità.
    • Ottieni una risposta di qualità superiore.
  • Diminuisci il tempo di elaborazione:
    • Risolvi le richieste di bassa complessità più velocemente rispetto al valore predefinito.
    • Risolvi una richiesta in meno tempo, ma ottieni una risposta di qualità inferiore.

Nota: i parametri di timeout e scadenza si applicano solo quando solvingMode è impostato sul valore predefinito DEFAULT_SOLVE. Altre opzioni solvingMode, come VALIDATE_ONLY, DETECT_SOME_INFEASIBLE_SHIPMENTS o TRANSFORM_AND_RETURN_REQUEST, in genere non richiedono aggiustamenti del timeout perché sono notevolmente più veloci.

Comprendere le esigenze di timeout e scadenza

Esamina questa sezione prima di configurare i timeout e le scadenze per verificare di aver compreso in che modo le scelte di endpoint e protocollo influiscono su queste impostazioni.

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

  • Utilizza endpoint non bloccanti per richieste continue e ripetute e per richieste complesse che traggono vantaggio da tempi di risoluzione più lunghi.
  • Utilizza endpoint bloccanti per piccole richieste e consegna rapida dei risultati, accettando un compromesso sulla qualità.
  • Utilizza gRPC per il 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

Impostare il parametro timeout

Imposta il valore del parametro timeout nel corpo della richiesta per specificare il tempo massimo in cui il server lavora su una richiesta prima di restituire una risposta. Il tempo effettivo trascorso potrebbe essere inferiore al tempo assegnato se l'API trova una soluzione ottimale prima di raggiungere il tempo massimo assegnato.

Imposta il timeout parametro 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 rigide, vincoli di carico, vincoli complessi o percorsi molto lunghi
1 - 8 2s 2s 5s
9 - 32 5s 10s 20s
33 - 100 15s 30s 60s
101 - 1000 45s 90s 180s
1001 - 10.000 120s 360s 900s
10.001 o più 60 s + 120 s per 10.000 spedizioni 360 s per 10.000 spedizioni 900 s per 10.000 spedizioni

Impostare la scadenza

Imposta la scadenza nell'intestazione della richiesta per definire il tempo massimo che l'API Route Optimization dedica all'elaborazione di una richiesta. Le seguenti sottosezioni descrivono come impostare le scadenze per le richieste REST e gRPC.

Richieste REST

Quando utilizzi REST per chiamare un endpoint bloccante, puoi estendere la scadenza oltre il valore predefinito di 60 secondi, che spesso è troppo breve per le 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 il valore predefinito di 60 secondi 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 timeout limitazioni del parametro's restrictions.

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 le utilizzi è di 3600 secondi, il tempo massimo di richiesta per questa API. Configura il tempo di risoluzione impostando solo la proprietà di timeout nel corpo della richiesta.

Parametri che influiscono su timeout e scadenze

I seguenti parametri influiscono sul funzionamento di timeout e scadenze:

  • Controlla la scadenza massima della richiesta con allowLargeDeadlineDespiteInterruptionRisk.
  • Definisci il comportamento della ricerca, bilanciando la qualità della soluzione rispetto alla 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 di timeout e scadenza è di 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 per i parametri di timeout e scadenza a 3600 secondi, riconoscendo al contempo il rischio di interruzione.
  • false (valore 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 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 superiore, l'ottimizzatore impiega un po' di tempo 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 (valore 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: utilizza tutto il tempo disponibile per cercare soluzioni migliori. L'API non utilizza tutto il tempo disponibile se trova una soluzione ottimale in anticipo.

Attivare i ping keepalive

Quando effettui richieste a endpoint bloccanti 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à di connessione e per rilevare e prevenire la perdita di connessione.

Configura questi parametri in base al protocollo API che utilizzi:

  • REST: configura 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. Librerie client e strumenti, come curl, potrebbero fornire opzioni di configurazione specifiche o attivare automaticamente i ping.

Se la libreria espone il socket TCP sottostante, puoi configurare i ping keepalive direttamente sul socket TCP utilizzando opzioni come SO_KEEPALIVE. Per farlo, utilizza funzioni come setsockopt() o le relative equivalenti.

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

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

Keepalive gRPC

gRPC offre un proprio meccanismo keepalive integrato come parte del protocollo. Consulta la guida di keepalive gRPC per istruzioni su come configurare questa opzione nella lingua del client.

Nota: i server gRPC potrebbero rifiutare i client che inviano troppi ping. Evita di impostare una frequenza di ping keepalive troppo elevata.

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 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)