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
timeoutsur 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 :
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).
Définissez les envois. Dans le champ
shipments, ajoutez un messageShipmentpour 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.Pour chaque chien, créez un
VisitRequestpour 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
arrivalWaypointsur 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éfinisseztimeWindowssur 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
arrivalWaypointsur la crèche ettimeWindowssur l'heure de dépôt requise (9h30 à 11h30).Pour toutes les prises en charge et livraisons, définissez le
durationsur 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.
Pour donner la priorité aux clients réguliers, vous définissez
penaltyCostsur1000pour le bouvier bernois et le chihuahua, et sur100pour 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.Vous pouvez utiliser le champ
labelpour 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.
Définir les véhicules Dans le champ
vehicles, ajoutez un messageVehiclepour 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.Définissez les valeurs
startWaypointetendWaypointdu 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.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
costPerHoursur27, 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.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
startTimedansstartTimeWindowssur 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
endTimedansendTimeWindowssur 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.
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
globalStartTimesur 7h00 etglobalEndTimesur 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.
| Parent | Paramètre | Type de propriété | Description |
|---|---|---|---|
OptimizeToursRequest |
model |
object (ShipmentModel) |
Il s'agit du cœur de votre requête. Il s'agit d'un objet unique dans lequel vous définissez l'ensemble de votre problème, y compris tous les chiens que vous devez récupérer et déposer (shipments) et le van 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 ce 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 à récupérer ou à déposer. |
vehicles[] |
Tableau d'objets (Vehicle) |
Il s'agit d'un tableau d'objets dans lequel chaque objet définit un véhicule de votre parc. C'est là que vous décrivez vos ressources, comme la camionnette qui effectue les collectes et les livraisons. Vous devez définir au moins un véhicule pour obtenir un itinéraire optimisé. | |
globalStartTime |
Code temporel | Il s'agit de l'heure la plus précoce possible pour tout événement de l'ensemble de votre modèle. Ce paramètre limite le problème d'optimisation dans le temps, ce qui est crucial pour des calculs précis du trafic et des itinéraires. Pour ce scénario de garderie pour chiens, définissez cette valeur sur l'heure la plus précoce à laquelle le conducteur peut utiliser le van pour la journée, soit 7h00 le 13 février 2024. | |
globalEndTime |
Code temporel | Il s'agit de l'heure la plus tardive possible pour tout événement de l'ensemble de votre modèle. Pour ce scénario de garderie pour chiens, définissez cette valeur sur l'heure à laquelle le van doit terminer son service, soit 19h le 13 février 2024. | |
Shipment |
pickups[] |
Tableau d'objets (VisitRequest) |
Il s'agit d'une 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 prise en charge fournis par chaque propriétaire pour chaque chien. |
deliveries[] |
Tableau d'objets (VisitRequest) |
Il s'agit d'une liste de toutes les options de dépôt possibles pour l'envoi. L'optimiseur choisit la meilleure solution pour résoudre votre problème. Pour ce scénario de garderie pour chiens, indiquez l'emplacement de la garderie et la période pendant laquelle le conducteur doit revenir pour le déjeuner de chaque chien. | |
label |
chaîne | Il s'agit de l'identifiant d'un envoi spécifique dans votre requête. Vous pouvez spécifier des étiquettes 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. | |
penaltyCost |
double | Il s'agit du coût de pénalité encouru si l'optimiseur ignore cet envoi. Par défaut, les envois sont obligatoires. L'optimiseur donne la priorité à la réduction du nombre d'envois obligatoires ignorés et ne les ignore que lorsqu'il n'y a pas d'autre option. Définir un coût de pénalité permet à l'optimiseur d'ignorer un envoi s'il est impossible ou trop coûteux à effectuer, et vous permet de pondérer les priorités entre les envois. Dans ce scénario, vous définissez un coût de pénalité plus élevé (1000) pour vos clients réguliers (bouvier bernois et chihuahua) et un coût de pénalité plus faible (100) pour la demande de dernière minute concernant le berger allemand. Cela indique à l'optimiseur de donner la priorité aux clients réguliers. Il envisagera donc d'ignorer le berger allemand en premier s'il ne peut pas effectuer toutes les prises en charge. |
|
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 ce paramètre sur l'emplacement fourni par le propriétaire pour pickups et sur 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 cette option pour définir la période de prise en charge de chacun des chiens et la période acceptable pour déposer les chiens au centre de garde. | |
duration |
Durée | Ce paramètre spécifie la durée de la visite (par exemple, le temps de chargement ou de déchargement). Dans ce scénario, vous définissez un tampon de cinq minutes (300s) pour toutes les prises en charge et livraisons afin de tenir compte du chargement et du déchargement des chiens par le conducteur. |
|
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 retrait ou de livraison comme point de départ. Dans ce scénario de garderie pour chiens, le conducteur commence sa journée à la garderie. Utilisez donc les coordonnées de Mission Dolores Park. |
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. Dans ce scénario de garderie pour chiens, le conducteur doit terminer sa journée à la garderie. Utilisez donc les coordonnées du Mission Dolores Park. | |
costPerHour |
nombre | 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. Dans ce scénario de garderie pour chiens, utilisez cette option pour modéliser le salaire horaire d'un conducteur. | |
startTimeWindows[] |
Tableau d'objets (TimeWindow) |
Il s'agit de la période acceptable pendant laquelle le conducteur peut commencer son service. Pour ce scénario de garderie pour chiens, définissez startTime sur 7h00, mais omettez endTime. Cela permet à l'optimiseur de retarder le début de l'équipe si la première prise en charge a lieu plus tard dans la matinée. Notez que même si vous ne fournissez pas de endTime pour startTimeWindows, l'heure de début est implicitement limitée par endTimeWindows. Le véhicule doit commencer l'itinéraire avant la fin de l'itinéraire. |
|
endTimeWindows[] |
Tableau d'objets (TimeWindow) |
Il s'agit de la période acceptable pendant laquelle le conducteur doit terminer l'itinéraire.
Pour ce scénario de garderie pour chiens, définissez endTime sur midi, mais omettez startTime. Cela permet au conducteur de retourner à la garderie immédiatement après le dernier dépôt. |