Envoyez votre première demande d'optimisation d'itinéraire

Développeurs de l'Espace économique européen (EEE)

Ce document vous explique comment envoyer votre première requête à l'API Route Optimization à l'aide d'un scénario d'utilisation réel.

Pour plus de simplicité, l'exemple utilise HTTP et JSON pour illustrer l'API REST. Toutefois, pour votre environnement de production, la recommandation générale est d'utiliser gRPC pour ses avantages en termes de performances. Toutefois, gRPC nécessite une installation. Pour en savoir plus, consultez Bibliothèques clientes de l'API Route Optimization.

Scénario

Carte de San Francisco avec des repères pour la Coit Tower, le Mission Dolores Park et le South Sunset Playground Park

Vous gérez une garderie pour chiens de 7h à 19h à San Francisco. Ce matin, vous devez récupérer deux chiens à différents endroits de la ville. Les deux propriétaires de chiens vous ont indiqué une plage horaire de récupération entre 7h30 et 9h30.

Vous disposez d'un fourgon pour la tâche et vous payez le chauffeur 27 dollars de l'heure. Le chauffeur et le van commencent leur journée à votre crèche à 7h00 et doivent être de retour des ramassages du matin avant 12h00 pour une pause déjeuner.

Nous sommes le 13 février 2024 et le chauffeur a les tâches suivantes :

  • Récupère le bouvier bernois près de la Coit Tower.
  • Récupère le chihuahua au parc South Sunset Playground.
  • Dépose les deux chiens à la garderie canine du parc Mission Dolores.

Vous avez besoin d'un itinéraire qui minimise le temps passé par les chiens dans le van, tout en respectant les exigences de prise en charge et de dépose.

Avant de commencer

Pour exécuter le code dans cet exemple de scénario, vous devez d'abord suivre les instructions de la page Configurer l'API Route Optimization.

1. Choisir votre approche d'optimisation des itinéraires

L'API Route Optimization propose plusieurs méthodes au choix, en fonction de la complexité de votre problème d'optimisation.

Comme ce scénario de garderie pour chiens est une demande simple et de petite taille, utilisez une méthode de blocage, telle que optimizeTours, qui fournit rapidement des résultats pour les petites demandes. Pour en savoir plus sur les méthodes de l'API Route Optimization, consultez Points de terminaison synchrones et asynchrones.

Utilisez l'URL suivante pour envoyer une requête HTTP POST à la méthode optimizeTours :

https://routeoptimization.googleapis.com/v1/projects/PROJECT_OR_ID:optimizeTours

Vous devez également définir des paramètres de délai d'expiration et de délai courts pour réduire tout temps d'attente inutile. Pour ce scénario de garderie pour chiens, l'optimiseur n'a pas besoin de beaucoup de temps pour répondre à votre demande. Utilisez donc les paramètres suivants :

  • Définissez le paramètre timeout sur 2 secondes.
  • Conservez les paramètres de délai par défaut, qui sont de 60 secondes pour les requêtes REST.

2. Construire le corps du message de la requête

Après avoir choisi la méthode de blocage optimizeTours et défini les paramètres de délai avant expiration et de délai limite, l'étape suivante consiste à créer le corps du message de la requête.

Dans ce scénario, la requête est un message OptimizeToursRequest encodé au format JSON dans l'API REST.

Pour construire le message de requête, procédez comme suit :

  1. Commencez par la structure de requête de base, qui est la suivante :

    {
  "timeout": ...,
  "model": {
    "shipments": [...],
    "vehicles": [...],
    "globalStartTime": "...",
    "globalEndTime": "..."
  }
}

    Pour en savoir plus sur la structure, consultez le guide des concepts clés pour la structure de base (ShipmentModel, Shipment et Vehicle).

  2. Définissez les expéditions. Dans le champ shipments, ajoutez un message Shipment pour chaque chien qui doit être récupéré et déposé le matin. C'est ici que vous définissez le lieu et les horaires de prise en charge préférés du propriétaire du chien, ainsi que le lieu et les horaires de dépose des chiens à la garderie.

    1. Pour chaque chien, créez un VisitRequest pour les récupérations et un autre pour les livraisons, qui, dans ce scénario, sont appelées les déposes à la garderie.

      • Pour les récupérations, définissez arrivalWaypoint sur le lieu de récupération du chien (Coit Tower pour le bouvier bernois ou South Sunset Playground Park pour le chihuahua) et timeWindows sur l'heure de récupération demandée par le propriétaire (entre 7h30 et 9h30).

      • Dans les livraisons, définissez arrivalWaypoint sur la crèche et timeWindows sur l'heure de dépôt requise (entre 9h30 et 11h30).

      Pour en savoir plus sur les périodes, consultez Périodes.

    2. Vous pouvez utiliser le champ label pour ajouter un identifiant pour chaque envoi, comme "Bouvier bernois" et "Chihuahua". Cela peut vous aider à identifier les envois dans la réponse.

    Pour en savoir plus sur la définition des expéditions, consultez Expédition.

  3. Définissez les véhicules. Dans le champ vehicles, ajoutez un message Vehicle pour votre fourgon, avec la crèche comme point de départ et d'arrivée, le coût du salaire du chauffeur et les heures d'ouverture du fourgon.

    1. Définissez startWaypoint et endWaypoint pour la camionnette sur les lieux de début et de fin de la journée, à savoir la crèche près de Mission Dolores Park.

    2. Pour minimiser vos coûts d'exploitation, vous devez définir les contraintes de coûts de votre entreprise. Définissez le paramètre de coût costPerHour sur 27, qui correspond au montant que vous payez au chauffeur pour conduire la camionnette de la garderie pour chiens. Pour en savoir plus sur les paramètres de coût, consultez Modèle de coût.

    3. Pour que l'optimiseur crée un itinéraire pendant les heures de fonctionnement du véhicule, définissez startTimeWindows sur la plage acceptable pour le début de l'utilisation du véhicule par le conducteur et endTimeWindows sur la plage acceptable pour le retour du conducteur à la crèche. Pour en savoir plus sur les périodes, consultez Périodes.

  4. Définissez une période globale. L'intervalle de temps global représente la période pendant laquelle la camionnette peut effectuer des enlèvements et des dépôts pour votre crèche tout au long de la journée. Dans ce scénario, définissez globalStartTime sur 7h et globalEndTime sur 19h pour le 13 février 2024, qui correspondent aux heures d'ouverture de votre garderie pour chiens.

3. Envoyer la requête

Voici une requête curl simple basée sur le scénario de garderie pour chiens et utilisant la méthode de blocage optimizeTours.

Avant d'envoyer la requête, remplacez PROJECT_NUMBER_OR_ID dans l'exemple de code par l'ID de votre projet Google Cloud.

curl -X POST 'https://routeoptimization.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID:optimizeTours' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
--data @- << EOM
{
  "timeout": 2s,
  "model": {
    "shipments": [
      {
        "pickups": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.802395,
                  "longitude": -122.405822
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T07:30:00Z",
                "endTime": "2024-02-13T09:30:00Z"
              }
            ]
          }
        ],
        "deliveries": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.760202,
                  "longitude": -122.426796
                }
              }
            },
            "timeWindow": [
              {
                "startTime": "2024-02-13T09:30:00Z",
                "endTime": "2024-02-13T11:30:00Z"
              }
            ]
          }
        ],
        "label": "Bernese mountain dog"
      },
      {
        "pickups": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.738067,
                  "longitude": -122.498593
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T07:30:00Z",
                "endTime": "2024-02-13T09:30:00Z"
              }
            ]
          }
        ],
        "deliveries": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.760202,
                  "longitude": -122.426796
                }
              }
            },
            "timeWindow": [
              {
                "startTime": "2024-02-13T09:30:00Z",
                "endTime": "2024-02-13T11:30:00Z"
              }
            ]
          }
        ],
        "label": "Chihuahua"
      }
    ],
    "vehicles": [
      {
        "startWaypoint": {
          "location": {
            "latLng": {
              "latitude": 37.760202,
              "longitude": -122.426796
            }
          }
        },
        "endWaypoint": {
          "location": {
            "latLng": {
              "latitude": 37.760202,
              "longitude": -122.426796
            }
          }
        },
        "costPerHour": 27,
        "startTimeWindows": [
          {
            "startTime": "2024-02-13T07:00:00Z",
            "endTime": "2024-02-13T07:15:00Z"
          }
        ],
        "endTimeWindows": [
          {
            "startTime": "2024-02-13T11:45:00Z",
            "endTime": "2024-02-13T12:00:00Z"
          }
        ]
      }
    ],
    "globalStartTime": "2024-02-13T07:00:00Z",
    "globalEndTime": "2024-02-13T19:00:00Z"
  }
}
EOM

Paramètres de requête utilisés dans la requête

Le tableau suivant décrit les paramètres de requête utilisés dans le corps de la requête de l'exemple de scénario. Vous pouvez filtrer le contenu par parent ou par recherche textuelle.

Parent Paramètre Type de propriété Description
OptimizeToursRequest model object (ShipmentModel) Il s'agit du cœur de votre demande. Il s'agit d'un objet unique dans lequel vous définissez l'intégralité de votre problème, y compris tous les chiens que vous devez récupérer et déposer (shipments) et le véhicule de votre flotte (vehicles). Considérez-le comme le plan complet du problème que vous devez optimiser.
timeout Durée Ce paramètre spécifie la durée maximale pendant laquelle le serveur traite une requête avant de renvoyer une réponse. Utilisez ce paramètre pour réduire votre temps d'attente. Pour les requêtes courtes et rapides, comme dans le scénario de garderie pour chiens, définissez cette valeur sur 2 s.
ShipmentModel shipments[] Tableau d'objets (Shipment) Il s'agit d'un tableau d'objets où chaque objet représente un chien qui doit être récupéré ou déposé.
vehicles[] Tableau d'objets (Vehicle) Il s'agit d'un tableau d'objets où chaque objet définit un véhicule de votre flotte. C'est là que vous décrivez vos ressources, comme le véhicule qui effectue les collectes et les livraisons. Vous devez définir au moins un véhicule pour obtenir un itinéraire optimisé.
globalStartTime Horodatage Il s'agit de la date et de l'heure les plus précoces pour qu'un événement se produise dans l'ensemble de votre modèle. Ce paramètre réduit le problème d'optimisation dans le temps, ce qui est essentiel pour calculer précisément le trafic et les itinéraires. Dans ce scénario de garderie pour chiens, définissez cette valeur sur l'heure la plus tôt à laquelle le chauffeur peut conduire le véhicule pour la journée, soit 7h00 le 13 février 2024.
globalEndTime Horodatage Il s'agit de la dernière heure possible pour qu'un événement se produise dans l'ensemble de votre modèle. Dans ce scénario de garderie pour chiens, définissez cette valeur sur l'heure à laquelle le van devrait terminer son trajet, soit 19h00 le 13 février 2024.
Shipment pickups[] Tableau d'objets (VisitRequest) Il s'agit de la liste de toutes les options de retrait possibles pour l'envoi. L'optimiseur choisit la meilleure pour résoudre votre problème. Pour ce scénario de garderie pour chiens, listez les lieux et les créneaux horaires de récupération fournis par chaque propriétaire pour chaque chien.
deliveries[] Tableau d'objets (VisitRequest) Il s'agit de la liste de toutes les options de dépôt possibles pour le colis. L'optimiseur choisit la meilleure pour résoudre votre problème. Pour ce scénario de garderie pour chiens, indique l'emplacement de la garderie et la plage horaire à laquelle le chauffeur doit revenir pour le déjeuner de chaque chien.
label chaîne Il s'agit d'un identifiant pour une expédition spécifique dans votre demande. Vous pouvez spécifier des libellés dans votre requête pour faciliter la lecture de la réponse. Pour ce scénario de garderie pour chiens, utilisez une chaîne descriptive telle que "Chihuahua", "Bouvier bernois" ou le nom du chien pour faire correspondre la solution à votre entrée lorsque vous recevez la réponse de l'API.
VisitRequest arrivalWaypoint[] object (Waypoint) Il s'agit de l'emplacement d'une visite spécifique sur l'itinéraire. Vous pouvez le définir à l'aide de coordonnées de latitude et de longitude, d'un ID de lieu ou d'un cap. Dans ce scénario de garderie pour chiens, définissez l'emplacement fourni par le propriétaire pour pickups et l'adresse de la garderie pour deliveries.
timeWindows[] Tableau d'objets (TimeWindow) Il s'agit d'un tableau d'objets qui définissent les contraintes de temps pour un retrait ou une livraison. Dans ce scénario, utilisez-le pour définir la plage horaire de récupération de chaque chien et la plage horaire acceptable pour les déposer à la garderie.
Vehicle startWaypoint[] object (Waypoint) Il s'agit du point de départ de l'itinéraire du véhicule, défini par des coordonnées de latitude et de longitude ou un ID de lieu. Ce paramètre indique à l'optimiseur où le véhicule doit commencer l'itinéraire. Si vous ne définissez pas ce point de cheminement, l'optimiseur choisit l'un des points de collecte ou de livraison comme point de départ. Pour ce scénario de garderie pour chiens, étant donné que le chauffeur commence la journée à la garderie, utilisez les coordonnées du parc Mission Dolores.
endWaypoint[] object (Waypoint) Il s'agit de la destination finale de l'itinéraire du véhicule, définie par des coordonnées de latitude et de longitude ou un ID de lieu. Ce paramètre indique à l'optimiseur où le véhicule doit terminer l'itinéraire. Si vous ne définissez pas ce point de cheminement, l'optimiseur choisit l'un des points de retrait ou de livraison comme fin de l'itinéraire. Pour ce scénario de garderie pour chiens, étant donné que le chauffeur doit terminer la journée à la garderie, utilisez les coordonnées du parc Mission Dolores.
costPerHour Total Il s'agit du coût encouru pour chaque heure d'utilisation d'un véhicule, qu'il soit en déplacement ou à l'arrêt. Pour ce scénario de garderie pour chiens, utilisez-le pour modéliser le salaire horaire d'un chauffeur.
startTimeWindows[] Tableau d'objets (TimeWindow) Il s'agit de la plage horaire acceptable pour que le conducteur commence à conduire le van pour les ramassages de chiens le matin.
endTimeWindows[] Tableau d'objets (TimeWindow) Il s'agit de la période acceptable pour que le chauffeur termine de conduire le van et se gare à nouveau au centre de garderie pour chiens.

Suivant

Interpréter la réponse