Interpréter la réponse

L'API Route Optimization renvoie des routes pour les véhicules dans la requête correspondante. Les livraisons sont attribuées aux véhicules ou peuvent être ignorées en fonction des propriétés de la requête.

Un message OptimizeToursResponse (REST, gRPC) possède deux propriétés de niveau supérieur:

• routes[] correspond aux itinéraires de chaque véhicule avec les livraisons qui lui sont attribuées. Chaque Route contient des métriques reflétant les propriétés de cette route individuelle.
• Les métriques metrics sont des métriques agrégées pour l'ensemble de la réponse, pour tous les véhicules et plans d'itinéraires. Les métriques de niveau supérieur contiennent les mêmes propriétés que les métriques par itinéraire, avec des valeurs agrégées pour tous les itinéraires.

Il est possible que certaines propriétés ne soient pas toujours renseignées en fonction des résultats de l'optimisation:

1. skippedShipments[] répertorie les expéditions qui ne sont effectuées par aucun véhicule. Une expédition peut être ignorée si elle ne peut pas être effectuée dans les limites spécifiées ou si le coût d'une livraison dépasse le coût de pénalité. Par exemple, si le retrait ou la livraison d'un colis ont une valeur timeWindow très restreinte, il n'est peut-être pas possible ou rentable pour un véhicule d'effectuer la visite pendant le créneau horaire requis.
2. validationErrors[] spécifie les erreurs qui rendent la requête non valide ou impossible à résoudre lorsque le solvingMode de la requête est défini sur VALIDATE_ONLY. En mode DEFAULT_SOLVE normal, les erreurs de validation apparaissent dans un message d'erreur au lieu du corps de la réponse. Notez que le mode de résolution VALIDATE_ONLY peut signaler plusieurs erreurs à la fois, ce qui est utile pour déboguer rapidement les requêtes.

Remarque :Pour interpréter une réponse, la requête correspondante est nécessaire. La réponse contient des références aux entités de la requête, ce qui la rend difficile à interpréter seule. Certains messages tels que Shipment et Vehicle possèdent des propriétés de libellé qui facilitent la mise en correspondance des données de requête et de réponse.

Propriétés des routes

Chaque entrée routes[] est un message ShipmentRoute (REST, gRPC). Chaque ShipmentRoute représente l'itinéraire attribué à un véhicule particulier à partir de la requête. Les propriétés ShipmentRoute importantes liées au Vehicle correspondant incluent:

• vehicleIndex est l'index basé sur zéro des Vehicle dans le message de requête correspondant. Les réponses REST omettent cette propriété lorsque la valeur est zéro.
• vehicleStartTime est l'heure à laquelle le véhicule doit suivre son itinéraire.
• vehicleEndTime est l'heure à laquelle le véhicule doit terminer son itinéraire.

Dans une réponse, routes ressemblera à ceci:

{
  "routes": [
    {
      "vehicleStartTime": "2024-02-13T00:00:00Z",
      "vehicleEndTime": "2024-02-13T00:38:42Z",
      "visits": [
        ...
      ],
      "transitions": [
        ...
      ],
      "metrics": {
        ...
      },
      ...
    }
  ],
  ...
}

Remarque :Les réponses REST utilisent la représentation JSON des tampons de protocole, qui omet les champs ayant la valeur par défaut de leur type respectif et qui ne sont pas compatibles avec les champs présents. Cela signifie que les propriétés entières telles que vehicleIndex sont omises si leurs valeurs sont nulles. Consultez également la documentation officielle sur le mappage JSON Protocol Buffers.

Chaque ShipmentRoute comprend une liste numérotée de visits que le véhicule effectuera. Chaque Visit (REST, gRPC) représente un VisitRequest (REST, gRPC) de la requête correspondante. Les propriétés Visit importantes incluent:

• shipmentIndex est l'indice basé sur zéro de la livraison à laquelle appartient cette visite dans la requête correspondante.
• isPickup est défini sur "true" lorsqu'une visite correspond à un retrait et sur "false" lorsqu'une visite est une livraison. Les réponses REST omettent cette propriété lorsque la valeur est "false".
• visitRequestIndex est l'indice basé sur zéro des VisitRequest de Shipment.pickups ou de Shipment.deliveries dans la requête correspondante représentée par Visit. Les réponses REST omettent cette propriété lorsque la valeur est égale à zéro.
• startTime est l'heure de début prévue de la visite.
• loadDemands mappe le type de chargement avec la quantité de chargement requise pour terminer Visit. Le nombre de chargements est négatif pour les visites en livraison. Il représente la charge en cours de déchargement du véhicule.

Voici un exemple de Visit:

{
  "routes": [
    {
      ...
      "visits": [
        {
          "isPickup": true,
          "startTime": "2024-02-13T00:00:00Z",
          "detour": "0s"
        },
        ...
      ],
    },
    ...
  ],
  ...
}

Chaque ShipmentRoute comprend une liste numérotée de transitions représentant les trajets entre visits pour un véhicule donné. Les propriétés des messages Transition importants (REST, gRPC) incluent:

• startTime correspond à l'heure à laquelle le véhicule commencera à effectuer la transition.
• travelDuration correspond à la durée de trajet du véhicule pour effectuer la transition.
• travelDistanceMeters est la distance en mètres que le véhicule doit parcourir pour effectuer la transition.
• trafficInfoUnavailable indique si les données de trafic sont disponibles pour la transition.
• waitDuration représente le temps d'inactivité du véhicule avant de pouvoir redémarrer son Visit suivant. Cela peut être dû au start_time des Visit suivants.
• totalDuration correspond à la durée totale de la transition, y compris les temps de trajet, d'attente, de pause et de retard.
• vehicleLoads mappe le type de chargement avec la quantité de chargement transportée par le véhicule pendant cette transition.

Voici un exemple de Transition:

{
  "routes": [
    {
      ...
      "transitions": [
        ...
        {
          "travelDuration": "1171s",
          "travelDistanceMeters": 9004,
          "waitDuration": "0s",
          "totalDuration": "1171s",
          "startTime": "2024-02-13T00:00:00Z"
        },
        ...
      ],
      ...
    }
  ],
  ...
}

La relation entre vists et transitions est décrite dans la section Optimisation des commandes d'arrêt de retrait et de livraison, ainsi que dans la documentation de référence sur ShipmentRoute (REST, gRPC).

Propriétés des métriques

Le message Metrics (REST, gRPC) résume l'ensemble de la solution. Voici quelques propriétés Metrics importantes:

• totalCost correspond au coût total engagé pour terminer les itinéraires. Pour en savoir plus sur les coûts, consultez la section Paramètres du modèle de coût.
• usedVehicleCount est le nombre total de véhicules utilisés dans la solution. Les véhicules peuvent avoir des itinéraires vides lorsque l'optimiseur détermine que leur utilisation n'est pas nécessaire.
• skippedMandatoryShipmentCount correspond au nombre d'expéditions ignorées qui sont "obligatoires". Une livraison obligatoire ne spécifie pas d'penaltyCost qui est envoyée si la livraison est ignorée. Les livraisons obligatoires peuvent toujours être ignorées si leurs performances ne sont pas réalisables dans des conditions spécifiques. Pour en savoir plus sur les coûts, consultez la section Paramètres du modèle de coût.

Les métriques supplémentaires sont signalées sous forme de messages AggregatedMetrics (REST, gRPC). Le type de message AggregatedMetrics est utilisé pour la propriété Metrics.aggregatedRouteMetrics. Pour la propriété ShipmentRoute.metrics, Metrics.aggregatedRouteMetrics contient des métriques agrégées pour tous les ShipmentRoute du OptimizeToursResponse. Chaque propriété ShipmentRoute.metrics contient des métriques pour cette ShipmentRoute spécifique.

Les propriétés AggregatedMetrics importantes incluent:

• performedShipmentCount correspond au nombre d'expéditions effectuées par des véhicules sur l'ensemble de leur itinéraire.
• travelDuration correspond au temps total que les véhicules passent dans le transport lorsqu'ils effectuent leurs itinéraires.
• waitDuration correspond au temps total que les véhicules passent à attendre pour terminer leur itinéraire.
• delayDuration est le retard total des véhicules. Cette valeur est généralement nulle, sauf si TransitionAttributes est utilisé dans la requête.
• breakDuration correspond au temps total que les véhicules passent sur pauses lorsqu'ils effectuent leurs itinéraires.
• visitDuration correspond au temps total que les véhicules passent à effectuer des visites. Il s'agit de la somme de toutes les valeurs VisitRequest.duration pour les VisitRequest correspondant aux Visit attribuées au véhicule concerné.
• totalDuration correspond à la durée totale requise pour parcourir les itinéraires des véhicules.
• travelDistanceMeters correspond à la distance totale parcourue par les véhicules tout au long de leur itinéraire.
• maxLoads mappe les types de chargement avec la charge maximale transportée par les véhicules à tout moment sur leurs itinéraires.

Voici un exemple de message Metrics:

{
  "routes": [
    ...
  ],
  "metrics": {
    "aggregatedRouteMetrics": {
      "performedShipmentCount": 1,
      "travelDuration": "2322s",
      "waitDuration": "0s",
      "delayDuration": "0s",
      "breakDuration": "0s",
      "visitDuration": "0s",
      "totalDuration": "2322s",
      "travelDistanceMeters": 18603
    },
    "usedVehicleCount": 1,
    "earliestVehicleStartTime": "2024-02-13T00:00:00Z",
    "latestVehicleEndTime": "2024-02-13T00:38:42Z",
    "totalCost": 18.603,
    "costs": {
      "model.vehicles.cost_per_kilometer": 18.603
    }
  }
}

Important :Si tous les coûts sont nuls dans les messages Metrics ou ShipmentRoute, il est peu probable que l'optimiseur ait trouvé une commande optimale pour l'achèvement Visit. Vous devez spécifier au moins un paramètre de coût, tel que Vehicle.costPerKilometer ou globalDurationCostPerHour. Dans le cas contraire, l'optimiseur peut renvoyer une solution répondant aux contraintes spécifiées.

Exemple complet

Voici un exemple de réponse complète à la requête provenant de Construire une requête:

{
  "routes": [
    {
      "vehicleStartTime": "2024-02-13T00:00:00Z",
      "vehicleEndTime": "2024-02-13T00:38:42Z",
      "visits": [
        {
          "isPickup": true,
          "startTime": "2024-02-13T00:00:00Z",
          "detour": "0s"
        },
        {
          "startTime": "2024-02-13T00:19:31Z",
          "detour": "0s"
        }
      ],
      "transitions": [
        {
          "travelDuration": "0s",
          "waitDuration": "0s",
          "totalDuration": "0s",
          "startTime": "2024-02-13T00:00:00Z"
        },
        {
          "travelDuration": "1171s",
          "travelDistanceMeters": 9004,
          "waitDuration": "0s",
          "totalDuration": "1171s",
          "startTime": "2024-02-13T00:00:00Z"
        },
        {
          "travelDuration": "1151s",
          "travelDistanceMeters": 9599,
          "waitDuration": "0s",
          "totalDuration": "1151s",
          "startTime": "2024-02-13T00:19:31Z"
        }
      ],
      "metrics": {
        "performedShipmentCount": 1,
        "travelDuration": "2322s",
        "waitDuration": "0s",
        "delayDuration": "0s",
        "breakDuration": "0s",
        "visitDuration": "0s",
        "totalDuration": "2322s",
        "travelDistanceMeters": 18603
      },
      "routeCosts": {
        "model.vehicles.cost_per_kilometer": 18.603
      },
      "routeTotalCost": 18.603
    }
  ],
  "metrics": {
    "aggregatedRouteMetrics": {
      "performedShipmentCount": 1,
      "travelDuration": "2322s",
      "waitDuration": "0s",
      "delayDuration": "0s",
      "breakDuration": "0s",
      "visitDuration": "0s",
      "totalDuration": "2322s",
      "travelDistanceMeters": 18603
    },
    "usedVehicleCount": 1,
    "earliestVehicleStartTime": "2024-02-13T00:00:00Z",
    "latestVehicleEndTime": "2024-02-13T00:38:42Z",
    "totalCost": 18.603,
    "costs": {
      "model.vehicles.cost_per_kilometer": 18.603
    }
  }
}