Effectuer votre première requête Route Optimization… avec des chiens

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, il est recommandé 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

Vous gérez un service de garde de chiens de 7h à 19h à San Francisco. Ce matin, vous souhaitez récupérer trois chiens à différents endroits de la ville et les amener à votre centre de garde.

Le bouvier bernois et le chihuahua sont des clients réguliers qui ont pris rendez-vous la semaine dernière. Le berger allemand est une nouvelle demande de dernière minute. Vous souhaitez accueillir le berger allemand si possible, mais pas au détriment de vos clients habituels.

Vous disposez d'un fourgon pour le travail et vous payez le chauffeur 27 $ de l'heure. Le chauffeur et le van commencent la journée à votre garderie à 7h et doivent être de retour des ramassages du matin à midi pour une pause déjeuner.

Nous sommes le 13 février 2024. Toutes les heures de ce scénario sont exprimées en heure locale de San Francisco, qui correspond à l'heure normale du Pacifique (UTC-8) en février. Le pilote effectue les tâches suivantes :

• Récupérez le bouvier bernois près de la Coit Tower. Le propriétaire a demandé un créneau de collecte serré entre 8h et 8h20.
• Récupérez le chihuahua au South Sunset Playground Park. Le propriétaire a proposé un créneau de retrait plus flexible, entre 7h30 et 9h30.
• Récupérez le berger allemand à Land's End. Le propriétaire a également demandé un créneau de collecte serré, entre 8h et 8h20.
• Dépose les chiens à la garderie du Mission Dolores Park. La crèche exige que les enfants soient déposés entre 9h30 et 11h30.

Chaque prise en charge et chaque dépose prend cinq minutes pour faire monter ou descendre le chien.

Comme Land's End est loin de Coit Tower et que leurs créneaux de prise en charge se chevauchent, le conducteur ne peut pas effectuer les trois prises en charge. L'optimiseur doit choisir le chien à ignorer pour minimiser le coût total (salaire du conducteur et pénalités d'omission).

Avant de commencer

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

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

L'API Route Optimization propose plusieurs méthodes, que vous pouvez choisir en fonction de la complexité de votre problème d'optimisation.

Étant donné que ce scénario de garderie pour chiens est une requête simple et de petite taille, utilisez une méthode bloquante, telle que optimizeTours, qui fournit rapidement des résultats pour les petites requêtes. Pour en savoir plus sur les points de terminaison de l'API Route Optimization, consultez Choisir un point de terminaison.

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 date limite 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 requête. Utilisez donc les paramètres suivants :

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

2. Créer le corps du message de 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 date limite, l'étape suivante consiste à créer le corps du message de requête.

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

Pour créer 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 sur la structure de base (ShipmentModel, Shipment et Vehicle).

2. Définissez les envois. Dans le champ shipments, ajoutez un message Shipment pour chaque chien qui doit être récupéré et déposé le matin. C'est là que vous définissez les lieux et heures de prise en charge préférés de chaque propriétaire de chien, ainsi que le lieu et les heures de dépose des chiens au centre de garde.

   1. Pour chaque chien, créez un VisitRequest pour les prises en charge et un autre pour les livraisons, qui, dans ce scénario, sont appelées "dépose à la garderie".

      • Dans les prises en charge, définissez arrivalWaypoint sur le lieu de prise en charge du chien (Coit Tower pour le bouvier bernois, South Sunset Playground Park pour le chihuahua ou Land's End pour le berger allemand). Définissez timeWindows sur l'heure de prise en charge demandée par le propriétaire (de 8h à 8h20 pour le bouvier bernois et le berger allemand, et de 7h30 à 9h30 pour le chihuahua).

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

      • Pour toutes les prises en charge et livraisons, définissez le duration sur cinq minutes (300s) pour tenir compte du chargement et du déchargement des chiens.

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

   2. Pour donner la priorité aux clients réguliers, vous définissez penaltyCost sur 1000 pour le bouvier bernois et le chihuahua, et sur 100 pour le berger allemand. Une fois les coûts de pénalité définis, l'optimiseur peut ignorer n'importe quel chien, mais il envisage d'abord d'ignorer le berger allemand (qui a une pénalité plus faible) si les contraintes rendent impossible la prise en charge de tous les chiens.

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

   Pour en savoir plus sur la définition des envois, consultez Envoi.

3. Définir les véhicules Dans le champ vehicles, ajoutez un message Vehicle pour votre fourgonnette, avec la garderie comme point de départ et d'arrivée, le coût du salaire du conducteur et les horaires d'ouverture de la fourgonnette.

   1. Définissez les valeurs startWaypoint et endWaypoint du van sur les lieux de départ et d'arrivée de la journée, à savoir la garderie située près du parc Mission Dolores.

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

   3. Pour vous assurer que l'optimiseur crée un itinéraire pendant les heures d'ouverture du van, définissez une fenêtre d'opération pour le véhicule. Cette fenêtre définit les contraintes d'heure de début et de fin de l'itinéraire. En ne définissant qu'une moitié de chaque intervalle de temps, vous donnez à l'optimiseur la flexibilité de commencer l'itinéraire plus tard ou de le terminer plus tôt :

      • Si vous définissez startTime dans startTimeWindows sur 7h00, cela signifie que le conducteur peut commencer son service dès 7h00. Il peut également commencer plus tard s'il n'y a pas de prise en charge tôt le matin.

      • Si vous définissez endTime dans endTimeWindows sur midi, le conducteur doit terminer son service à midi. Ils peuvent également terminer leur service dès qu'ils ont effectué la dernière livraison.

      L'omission de l'autre moitié des fenêtres réduit les temps d'attente et de détour du conducteur. Pour en savoir plus sur les périodes, consultez Périodes.

   Pour en savoir plus sur la définition des véhicules, consultez Véhicule.

4. Définissez une période globale. La période globale représente la période pendant laquelle le van peut effectuer des prises en charge et des dépôts pour votre crèche tout au long de la journée. Pour ce scénario, définissez globalStartTime sur 7h00 et globalEndTime sur 19h00 pour le 13 février 2024, ce qui correspond aux horaires 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 la garderie pour chiens, qui utilise la méthode optimizeTours bloquante.

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-13T08:00:00-08:00",
                "endTime": "2024-02-13T08:20:00-08:00"
              }
            ],
            "duration": "300s"
          }
        ],
        "deliveries": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.759719,
                  "longitude": -122.42798
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T09:30:00-08:00",
                "endTime": "2024-02-13T11:30:00-08:00"
              }
            ],
            "duration": "300s"
          }
        ],
        "label": "Bernese mountain dog",
        "penaltyCost": 1000
      },
      {
        "pickups": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.738067,
                  "longitude": -122.498593
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T07:30:00-08:00",
                "endTime": "2024-02-13T09:30:00-08:00"
              }
            ],
            "duration": "300s"
          }
        ],
        "deliveries": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.759719,
                  "longitude": -122.42798
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T09:30:00-08:00",
                "endTime": "2024-02-13T11:30:00-08:00"
              }
            ],
            "duration": "300s"
          }
        ],
        "label": "Chihuahua",
        "penaltyCost": 1000
      },
      {
        "pickups": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.78018,
                  "longitude": -122.51194
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T08:00:00-08:00",
                "endTime": "2024-02-13T08:20:00-08:00"
              }
            ],
            "duration": "300s"
          }
        ],
        "deliveries": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.759719,
                  "longitude": -122.42798
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T09:30:00-08:00",
                "endTime": "2024-02-13T11:30:00-08:00"
              }
            ],
            "duration": "300s"
          }
        ],
        "label": "German shepherd",
        "penaltyCost": 100
      }
    ],
    "vehicles": [
      {
        "startWaypoint": {
          "location": {
            "latLng": {
              "latitude": 37.759719,
              "longitude": -122.42798
            }
          }
        },
        "endWaypoint": {
          "location": {
            "latLng": {
              "latitude": 37.759719,
              "longitude": -122.42798
            }
          }
        },
        "costPerHour": 27,
        "startTimeWindows": [
          {
            "startTime": "2024-02-13T07:00:00-08:00"
          }
        ],
        "endTimeWindows": [
          {
            "endTime": "2024-02-13T12:00:00-08:00"
          }
        ]
      }
    ],
    "globalStartTime": "2024-02-13T07:00:00-08:00",
    "globalEndTime": "2024-02-13T19:00:00-08:00"
  }
}
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.

Suivant

Interpréter la réponsearrow_forward