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:
    • Risolvere richieste di elevata complessità.
    • Ottenere una risposta di qualità superiore.
  • Ridurre il tempo di elaborazione:
    • Risolvi le richieste a bassa complessità più velocemente rispetto al valore predefinito.
    • Risolvi una richiesta in meno tempo, ma ricevi 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 molto più veloci.

Comprendere le esigenze di timeout e scadenza

Rivedi questa sezione prima di configurare i timeout e le scadenze per verificare di comprendere 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 corretta 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 gli endpoint di blocco per richieste di piccole dimensioni e per la rapida restituzione dei risultati, accettando un compromesso sulla 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 per la tua configurazione.

Apri 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 elabora 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 parametro timeout utilizzando il buffer del protocollo di 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 2 sec 2 sec 5 s
9 - 32 5 s 10 sec 20 sec
33 - 100 15 sec 30 sec 60 sec
101 - 1000 45 sec 90 secondi Anni '80
1001 - 10.000 120 sec 360 900 secondi
10.001 o più 60 secondi + 120 secondi ogni 10.000 spedizioni 360 per 10.000 spedizioni 900 secondi ogni 10.000 spedizioni

Impostare 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 seguenti sottosezioni 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 le richieste complesse. Devi eseguire questa operazione 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 librerie client o gRPC. Il termine predefinito quando vengono utilizzati è di 3600 secondi, il tempo massimo di richiesta 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 di timeout e 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 il termine massimo per le richieste a 3600 secondi. Se questo parametro non è impostato, il valore massimo per i parametri di timeout e scadenza è 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 il rischio di interruzione.
  • false (impostazione predefinita): 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 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 (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.

Abilita ping keepalive

Quando effettui richieste agli 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 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 tua 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 il relativo equivalente.

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

Per maggiori dettagli sul keepalive a livello TCP, consulta la panoramica del 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 keepalive di gRPC per le istruzioni su come configurare questa impostazione 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)