Configurer les délais avant expiration et les délais

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 avant expiration 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ésolvez les requêtes très complexes.
    • Obtenez une réponse de meilleure qualité.
  • Réduire le temps de traitement :
    • Résolvez les requêtes peu complexes plus rapidement que par défaut.
    • Résolvez une requête en moins de temps, mais obtenez une réponse de qualité inférieure.

Remarque : Les paramètres de délai avant expiration et de délai limite ne s'appliquent que lorsque solvingMode est défini sur sa valeur par défaut, 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 avant expiration, car elles sont beaucoup plus rapides.

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

Consultez cette section avant de configurer vos délais avant expiration et vos délais limites pour vous assurer de comprendre comment vos choix de point de terminaison et de protocole affectent ces paramètres.

Les consignes suivantes peuvent vous aider à vérifier si vous utilisez la configuration adaptée à 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 bénéficient de 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 requêtes 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 diagramme dans un nouvel onglet

Définir 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 pouvant aller de 1 à 1 800 secondes. Augmentez cette valeur jusqu'à 3 600 secondes à l'aide de allowLargeDeadlineDespiteInterruptionRisk.

Le tableau suivant répertorie les valeurs timeout recommandées en fonction de la complexité de la requête et du nombre d'expéditions et de véhicules.

Nombre d'expéditions et de véhicules Aucune contrainte Fenêtres de temps et contraintes de charge souples ou itinéraires longs Fenêtres de temps strictes, contraintes de charge, contraintes complexes ou itinéraires très longs
1 - 8 2s 2s 5s
9 - 32 5s 10s 20s
33 - 100 15s 30s 60s
101 - 1 000 45s 90s 180s
1 001 - 10 000 120s 360s 900s
10 001 ou plus 60 s + 120 s par tranche de 10 000 expéditions 360 s par tranche de 10 000 expéditions 900 s par tranche de 10 000 expéditions

Définir le délai limite

Définissez le délai limite dans l'en-tête de 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 limites 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 limite 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 limite plus long dans le corps de la requête, car le délai limite par défaut remplace toutes les valeurs timeout définies dans le corps de la requête qui sont supérieures à 60 secondes.

Étendez le délai limite au-delà de la valeur par défaut de 60 secondes en définissant 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 suffixe "s". La valeur maximale que vous pouvez définir pour cet en-tête correspond aux timeout paramètre's restrictions.

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 limite lorsque vous utilisez des bibliothèques clientes ou gRPC. Le délai limite par défaut lorsque vous les utilisez est de 3 600 secondes, soit le temps de requête maximal 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 qui affectent les délais avant expiration et les délais limites

Les paramètres suivants affectent le fonctionnement des délais avant expiration et des délais limites :

  • Contrôlez le délai limite maximal des requêtes 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 limite 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 limite 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 des paramètres de délai avant expiration et de délai limite de 1 800 secondes.

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

searchMode

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

Lorsque vous privilégiez 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 bonne solution.
  • CONSUME_ALL_AVAILABLE_TIME: passe tout le temps disponible à la recherche de meilleures solutions. L'API n'utilise pas tout le temps disponible si elle trouve une solution optimale plus tôt.

Activer les pings keepalive

Lorsque vous effectuez des requêtes vers 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 keepalive sont de petits paquets envoyés pour maintenir l'activité de 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 pings keepalive sur le socket TCP sous-jacent ou directement dans le protocole gRPC.

Les sections suivantes expliquent comment configurer les pings keepalive pour les deux protocoles.

Keepalive REST

La configuration des pings keepalive 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 keepalive 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 keepalive intégré dans le protocole. Consultez le guide sur le keepalive gRPC pour savoir comment le configurer 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 keepalive 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 keepalive 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)