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 date 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 l'échéance 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 d'exécution vous permet de gérer le temps de traitement de différentes manières :

  • Augmenter le temps de traitement :
    • Résoudre des requêtes très complexes
    • Obtenir 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ésoudre une requête plus rapidement, mais obtenir une réponse de moins bonne qualité.

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

Lisez cette section avant de configurer vos délais avant expiration et vos délais d'exécution pour vérifier que vous comprenez l'impact de vos choix de points de terminaison et de protocoles sur ces paramètres.

Les consignes suivantes peuvent vous aider à vérifier que 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 tests ou les requêtes ponctuelles.

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

Ouvrir le diagramme dans un onglet distinct

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éellement 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 est une durée en secondes pouvant aller de 1 seconde à 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é de la requête, ainsi que du nombre d'envois et de véhicules.

Nombre d'envois et de véhicules Aucune contrainte Fenêtres de temps et contraintes de chargement lâches ou itinéraires longs Créneaux horaires serrés, contraintes de chargement, contraintes complexes ou itinéraires très longs
1 - 8 2 s 2 s 5 s
9 - 32 5 s 10 s 20 s
33 - 100 15 s 30 s 60 s
101 - 1 000 45 s 90s 180 s
1 001 à 10 000 120 s 360s 900 s
10 001 ou plus 60 s + 120 s par tranche de 10 000 envois 360 s pour 10 000 envois 900 s pour 10 000 envois

Définissez la date limite

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

Requêtes REST

Lorsque vous utilisez REST pour appeler un point de terminaison bloquant, vous pouvez prolonger 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 effectuer cette opération 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.

Prolongez le délai au-delà des 60 secondes par défaut 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 est le 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 avant expiration lorsque vous utilisez des bibliothèques clientes ou gRPC. Le délai par défaut lors de leur utilisation 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 avant expiration et les délais d'exécution

Les paramètres suivants ont une incidence sur le fonctionnement des délais avant expiration et des délais d'exécution :

  • Contrôlez le délai maximal de 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 de requête à 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 date 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 date 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 date 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 date limite.

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 façon 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 donnez la priorité à une qualité de solution plus élevée, 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 : consacre tout le temps disponible à la recherche de meilleures solutions. L'API n'utilise pas tout le temps disponible si elle trouve une solution optimale rapidement.

Activer les pings keepalive

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 de persistance sont de petits paquets envoyés pour maintenir l'activité de la connexion, et pour détecter et empêcher la perte de connexion.

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

  • REST : configurez le keepalive au niveau de la connexion TCP.
  • gRPC : configurez des 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 des pings de persistance 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é de 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 configurer cette fonctionnalité dans le langage de votre client.

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