Interpréter la réponse

L'API Route Optimization renvoie les itinéraires des véhicules dans la requête correspondante. Les envois sont attribués à des véhicules ou peuvent être ignorés en fonction des propriétés de la requête.

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

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

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

1. skippedShipments[] liste les expéditions qui ne sont effectuées par aucun véhicule. Une livraison peut être ignorée si elle ne peut pas être effectuée dans les contraintes spécifiées ou si le coût de la livraison dépasse le coût de pénalité. Par exemple, si la timeWindow de la collecte ou de la livraison d'un envoi est très étroite, il est possible qu'il ne soit pas possible ou rentable pour un véhicule d'effectuer la visite dans la période requise.
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 s'affichent 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, comme Shipment et Vehicle, disposent de propriétés de libellé pour faciliter la mise en correspondance des données de requête et de réponse.

Propriétés de la route

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

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

Dans une réponse, routes se présente comme suit:

{
  "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 de Protocol Buffers, qui omet les champs dont la valeur par défaut est celle de leur type respectif et qui n'acceptent pas la présence de champs. Cela signifie que les propriétés entières telles que vehicleIndex sont omises lorsque leurs valeurs sont nulles. Consultez également la documentation officielle sur le mappage JSON Protocol Buffers.

Chaque ShipmentRoute inclut une liste ordonnée des visits que le véhicule effectuera. Chaque Visit (REST, gRPC) représente un VisitRequest (REST, gRPC) de la requête correspondante. Voici quelques propriétés Visit importantes:

• shipmentIndex correspond à l'index de base 0 de l'envoi auquel cette visite appartient dans la requête correspondante.
• isPickup est défini sur "true" lorsqu'une visite correspond à un retrait et sur "false" lorsqu'elle correspond à une livraison. Les réponses REST omettent cette propriété lorsque la valeur est "false".
• visitRequestIndex est l'indice de base zéro du VisitRequest à partir 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 nulle.
• startTime est l'heure de début prévue de la visite.
• loadDemands met en correspondance le type de charge avec la quantité de charge demandée pour effectuer la Visit. Les quantités de charge sont négatives pour les visites de livraison, car elles représentent la charge retirée du véhicule.

Voici un exemple de fichier Visit:

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

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

• startTime est l'heure à laquelle le véhicule commencera à effectuer la transition.
• travelDuration est la durée pendant laquelle le véhicule doit circuler pour effectuer la transition.
• travelDistanceMeters est la distance en mètres que le véhicule doit parcourir pour effectuer la transition.
• trafficInfoUnavailable indique si des données sur le trafic sont disponibles pour la transition.
• waitDuration représente le temps d'inactivité que le véhicule passe à attendre avant de pouvoir démarrer son prochain Visit. Cela peut être dû au start_time de l'Visit suivant.
• 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 charge à la quantité de charge transportée par le véhicule lors de cette transition.

Voici un exemple de fichier Transition:

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

Pour en savoir plus sur la relation entre vists et transitions, consultez la section Optimisation de l'ordre des arrêts de ramassage et de livraison et la documentation de référence sur ShipmentRoute (REST, gRPC). Pour en savoir plus sur les propriétés routePolyline et routeToken d'un message Transition, consultez la section Polylignes de transition et jetons de parcours.

Propriétés des métriques

Le message Metrics (REST, gRPC) résume la solution dans son ensemble. Voici quelques-unes des propriétés importantes de Metrics:

• totalCost correspond au coût total des itinéraires. Pour en savoir plus sur les coûts, consultez la section Paramètres du modèle de coûts.
• usedVehicleCount correspond au 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 est le nombre d'expéditions ignorées qui sont "obligatoires". Un envoi obligatoire ne spécifie pas de penaltyCost qui sera appliqué si l'envoi est ignoré. Les envois obligatoires peuvent toujours être ignorés si leurs performances ne sont pas réalisables dans les contraintes spécifiées. Pour en savoir plus sur les coûts, consultez la section Paramètres du modèle de coûts.

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

Voici quelques propriétés AggregatedMetrics importantes:

• performedShipmentCount correspond au nombre d'envois effectués par les véhicules sur l'ensemble de leur parcours.
• travelDuration correspond à la durée totale de trajet des véhicules pendant qu'ils effectuent leurs itinéraires.
• waitDuration correspond au temps total d'attente des véhicules pendant l'exécution de leurs itinéraires.
• delayDuration correspond au temps de retard total des véhicules. Cette valeur est généralement nulle, sauf si TransitionAttributes est utilisé dans la requête.
• breakDuration correspond à la durée totale des pauses des véhicules pendant qu'ils effectuent leurs trajets.
• visitDuration correspond au temps total passé par les véhicules à effectuer des visites lors de l'exécution de leurs itinéraires. Il s'agit en fait de la somme de toutes les valeurs VisitRequest.duration pour les VisitRequest correspondant aux Visit attribués au véhicule concerné.
• totalDuration correspond à la durée totale nécessaire pour effectuer les trajets des véhicules.
• travelDistanceMeters correspond à la distance totale parcourue par les véhicules lors de leur trajet.
• maxLoads met en correspondance les types de charge avec la quantité de charge maximale transportée par les véhicules à n'importe quel point de leur itinéraire.

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, l'optimiseur a probablement trouvé une séquence optimale pour l'exécution de Visit. Vous devez spécifier au moins un paramètre de coût, tel que Vehicle.costPerKilometer ou globalDurationCostPerHour, sinon l'optimiseur peut renvoyer n'importe quelle solution qui répond aux contraintes spécifiées.

Exemple complet

Voici un exemple de réponse complète à la requête de la section 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
    }
  }
}