Délais d'expiration et échéances

Ce document explique comment configurer les paramètres de délai avant expiration et de délai limite pour les requêtes de l'API Route Optimization. Si vous ne définissez pas ces valeurs ou si vous les définissez de manière incorrecte, vous risquez de rencontrer des problèmes de connexion ou de qualité de réponse.

Vous définissez le délai d'inactivité dans le corps de la requête et le délai limite dans l'en-tête de la requête. L'API Route Optimization traite la requête dans le délai défini par ces paramètres, en respectant la valeur de temps la plus courte.

La configuration des délais avant expiration et des délais limites vous permet de gérer le temps de traitement de différentes manières :

  • Augmenter le temps de traitement
    • résoudre des demandes très complexes ;
    • Obtenir une réponse de meilleure qualité
  • Réduire le temps de traitement
    • Résolvez les demandes peu complexes plus rapidement que par défaut.
    • Résolvez une demande plus rapidement, mais obtenez une réponse de qualité inférieure.

Remarque : Les paramètres de délai d'expiration et de date limite ne s'appliquent que lorsque solvingMode est défini sur sa valeur par défaut de DEFAULT_SOLVE. Les autres options solvingMode, telles que VALIDATE_ONLY, DETECT_SOME_INFEASIBLE_SHIPMENTS ou TRANSFORM_AND_RETURN_REQUEST, ne nécessitent généralement pas d'ajustement du délai d'expiration, car elles sont beaucoup plus rapides.

Comprendre vos besoins en termes de délai et de délai avant expiration

Consultez cette section avant de configurer vos délais d'attente et vos échéances pour vérifier que vous comprenez comment vos choix de points de terminaison et de protocoles affectent ces paramètres.

Les consignes suivantes peuvent vous aider à vérifier si votre configuration correspond à vos objectifs.

  • Utilisez des points de terminaison non bloquants pour les requêtes continues et répétées, ainsi que pour les requêtes complexes qui nécessitent des temps de résolution plus longs.
  • Utilisez des points de terminaison bloquants pour les petites requêtes et la livraison rapide des résultats, en acceptant un compromis sur la qualité.
  • Utilisez gRPC pour votre workflow quotidien, en particulier pour les applications de production.
  • Utilisez REST pour les tests, les expériences ou les demandes ponctuelles.

Cliquez sur le bouton ci-dessous pour afficher un schéma qui peut vous aider à déterminer les sections de ce document les plus pertinentes pour votre configuration.

Ouvrir le schéma dans un onglet distinct

Définissez le paramètre timeout.

Définissez la valeur du paramètre timeout dans le corps de la requête pour spécifier la durée maximale pendant laquelle le serveur traite une requête avant de renvoyer une réponse. Le temps réel passé peut être inférieur au temps alloué si l'API trouve une solution optimale avant d'atteindre le temps maximal alloué.

Définissez le paramètre timeout à l'aide du tampon de protocole de durée, qui correspond à une durée en secondes comprise entre 1 et 1 800 secondes. Augmentez cette valeur jusqu'à 3 600 secondes à l'aide de allowLargeDeadlineDespiteInterruptionRisk.

Le tableau suivant liste les valeurs timeout recommandées en fonction de la complexité des requêtes et du nombre d'envois et de véhicules.

Nombre d'envois et de véhicules Aucune contrainte Plages horaires et contraintes de chargement flexibles ou itinéraires longs Plages horaires serrées, contraintes de chargement, contraintes complexes ou itinéraires très longs
1 - 8 2s 2s 5 s
9 – 32 5 s 10 s 20 s
33 - 100 15 s 30 s 60 s
101 - 1 000 45 s Années 90 180
Entre 1 001 et 10 000 120 s 360s 900s
10 001 ou plus 60 s + 120 s pour 10 000 expéditions 360 par 10 000 expéditions 900 secondes pour 10 000 envois

Définir la date limite

Définissez le délai dans l'en-tête de la requête pour définir la durée maximale pendant laquelle l'API Route Optimization traite une requête. Les sous-sections suivantes décrivent comment définir des délais pour les requêtes REST et gRPC.

Requêtes REST

Lorsque vous utilisez REST pour appeler un point de terminaison bloquant, vous pouvez étendre le délai au-delà de la valeur par défaut de 60 secondes, qui est souvent trop courte pour les requêtes complexes. Vous devez le faire même si vous avez déjà spécifié un délai plus long dans le corps de la requête, car le délai par défaut remplace toutes les valeurs timeout définies dans le corps de la requête qui sont supérieures à 60 secondes.

Pour prolonger le délai au-delà des 60 secondes par défaut, définissez l'en-tête de requête X-Server-Timeout. Contrairement au corps de la requête, la valeur de l'en-tête correspond au nombre de secondes, mais sans le suffixe "s". La valeur maximale que vous pouvez définir pour cet en-tête correspond aux restrictions du paramètre timeout.

L'exemple de code suivant montre un en-tête HTTP avec X-Server-Timeout défini sur 1 800 secondes.

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

Bibliothèques clientes et requêtes gRPC

Vous n'avez pas besoin de configurer de délai lorsque vous utilisez des bibliothèques clientes ou gRPC. Le délai par défaut lorsque vous les utilisez est de 3 600 secondes, soit la durée maximale de requête pour cette API. Configurez le temps de résolution en définissant uniquement la propriété de délai avant expiration dans le corps de la requête.

Paramètres ayant une incidence sur les délais d'inactivité et les échéances

Les paramètres suivants affectent le fonctionnement des délais d'attente et des délais limites :

  • Contrôlez le délai maximal de la requête avec allowLargeDeadlineDespiteInterruptionRisk.
  • Définissez le comportement de la recherche en équilibrant la qualité de la solution par rapport à la latence avec searchMode.

allowLargeDeadlineDespiteInterruptionRisk

Le paramètre allowLargeDeadlineDespiteInterruptionRisk augmente le délai maximal des requêtes à 3 600 secondes. Si ce paramètre n'est pas défini, la valeur maximale des paramètres de délai avant expiration et de délai est de 1 800 secondes.

Définissez allowLargeDeadline DespiteInterruptionRisk sur true pour augmenter la valeur des paramètres de délai avant expiration et de délai limite jusqu'à 3 600 secondes.

Les valeurs autorisées pour allowLargeDeadline DespiteInterruptionRisk sont les suivantes :

  • true : augmente la valeur maximale des paramètres de délai avant expiration et de délai limite à 3 600 secondes tout en reconnaissant le risque d'interruption.
  • false (par défaut) : conserve la valeur maximale de 1 800 secondes pour les paramètres de délai avant expiration et de délai.

Si vous pensez avoir besoin d'un délai d'inactivité supérieur à 3 600 secondes, contactez votre représentant Google.

searchMode

Le paramètre searchMode contrôle la façon dont l'optimiseur recherche des solutions. Il vous permet de privilégier une réponse plus rapide (latence plus faible) ou une solution de meilleure qualité.

Lorsque vous accordez la priorité à une meilleure qualité de solution, l'optimiseur prend un certain temps pour trouver une solution de haute qualité. Pour ces requêtes plus longues, envisagez de définir un délai avant expiration plus long et d'utiliser des points de terminaison non bloquants pour éviter les problèmes de connexion.

Les valeurs autorisées pour searchMode sont les suivantes :

  • SEARCH_MODE_UNSPECIFIED (par défaut) : mode de recherche non spécifié, équivalent à RETURN_FAST.
  • RETURN_FAST : arrête la recherche après avoir trouvé la première solution appropriée.
  • CONSUME_ALL_AVAILABLE_TIME : passe tout le temps disponible à rechercher de meilleures solutions. L'API n'utilise pas tout le temps disponible si elle trouve une solution optimale rapidement.

Activer les pings keep-alive

Lorsque vous envoyez des requêtes à des points de terminaison bloquants avec un délai avant expiration supérieur à 60 secondes, les pings "keepalive" permettent d'éviter la perte de connexion pendant que vous attendez une réponse. Les pings Keep-Alive sont de petits paquets envoyés pour maintenir l'activité de la connexion, et pour détecter et prévenir la perte de connexion.

Configurez ces paramètres en fonction du protocole API que vous utilisez :

  • REST : configurez le keepalive au niveau de la connexion TCP.
  • gRPC : configurez les signaux de présence sur le socket TCP sous-jacent ou directement dans le protocole gRPC.

Les sections suivantes expliquent comment configurer les signaux de présence pour les deux protocoles.

Keepalive REST

La configuration des pings keep-alive lorsque vous utilisez REST dépend de votre bibliothèque cliente HTTP. Les bibliothèques clientes et les outils, tels que curl, peuvent fournir des options de configuration spécifiques ou activer automatiquement les pings.

Si votre bibliothèque expose le socket TCP sous-jacent, vous pouvez configurer les pings keep-alive directement sur le socket TCP à l'aide d'options telles que SO_KEEPALIVE. Pour ce faire, utilisez des fonctions telles que setsockopt() ou leur équivalent.

Cette fonction hébergée sur GitHub montre comment configurer correctement le client HTTP intégré à Python.

Pour en savoir plus sur le keepalive au niveau TCP, consultez la présentation du keepalive TLDP ou la documentation de votre bibliothèque cliente HTTP.

Keepalive gRPC

gRPC propose son propre mécanisme de maintien en vie intégré au protocole. Consultez le guide de maintien en vie gRPC pour savoir comment configurer cette fonctionnalité dans votre langage client.

Remarque : Les serveurs gRPC peuvent refuser les clients qui envoient trop de pings. Évitez de définir une fréquence de ping keep-alive trop élevée.

Exemple de requête gRPC avec keepalive

L'exemple suivant montre comment effectuer une requête optimizeTours à l'aide de la bibliothèque cliente Python et des pings de maintien en vie au niveau 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)