Questo documento mostra come effettuare la prima richiesta all'API Route Optimization utilizzando uno scenario di caso d'uso reale.
Per semplicità, l'esempio utilizza HTTP e JSON per mostrare l'API REST. Tuttavia, per l'ambiente di produzione, il consiglio generale è di utilizzare gRPC per i suoi vantaggi in termini di prestazioni. Tuttavia, gRPC richiede l'installazione. Per saperne di più, consulta Librerie client dell'API Route Optimization.
Scenario
Gestisci un servizio di asilo per cani dalle 07:00 alle 19:00 a San Francisco. Questa mattina, vuoi andare a prendere tre cani in diverse località della città e portarli al tuo centro diurno.
Il bovaro del bernese e il chihuahua sono clienti abituali che hanno prenotato i loro appuntamenti la scorsa settimana. Il pastore tedesco è una nuova richiesta dell'ultimo minuto. Se possibile, vuoi accogliere il pastore tedesco, ma non a scapito dei tuoi clienti abituali.
Hai un furgone per il lavoro e paghi il conducente 27 $l'ora. Il conducente e il furgone iniziano la giornata presso il tuo asilo nido alle 07:00 e devono tornare dai ritiri mattutini entro mezzogiorno per una pausa pranzo.
Oggi è il 13 febbraio 2024. Tutti gli orari di questo scenario sono espressi nel fuso orario locale di San Francisco, ovvero il fuso orario standard della costa del Pacifico (UTC-8) a febbraio. Il driver ha le seguenti attività:
- Prendi il bovaro del bernese vicino alla Coit Tower. Il proprietario ha richiesto una finestra di ritiro ristretta tra le 08:00 e le 08:20.
- Prendi il chihuahua al South Sunset Playground Park. Il proprietario ha offerto una finestra di ritiro più flessibile tra le 07:30 e le 09:30.
- Prendi il pastore tedesco a Land's End. Il proprietario ha anche richiesto una finestra di ritiro ristretta tra le 08:00 e le 08:20.
- Porta i cani al centro di assistenza diurna di Mission Dolores Park. L'asilo nido richiede l'arrivo tra le 09:30 e le 11:30.
Ogni visita di ritiro e consegna richiede 5 minuti per caricare o scaricare il cane.
Poiché Land's End è lontano dalla Coit Tower e le finestre di ritiro sono in conflitto, il conducente non può eseguire tutti e tre i ritiri. L'ottimizzatore deve scegliere quale cane saltare per ridurre al minimo il costo totale (salari dei conducenti ed eventuali penali per i salti).
Prima di iniziare
Per eseguire il codice in questo scenario di esempio, devi prima completare le istruzioni riportate in Configura l'API Route Optimization.
1. Scegli l'approccio di ottimizzazione dei percorsi
L'API Route Optimization offre diversi metodi tra cui scegliere, a seconda della complessità del problema di ottimizzazione.
Poiché questo scenario di asilo per cani è una richiesta piccola e semplice, utilizza un metodo di blocco, come optimizeTours, che fornisce rapidamente risultati per richieste di piccole dimensioni. Per ulteriori informazioni sugli endpoint dell'API Route Optimization, consulta Scegli un endpoint.
Utilizza il seguente URL per inviare una richiesta POST HTTP al metodo optimizeTours:
https://routeoptimization.googleapis.com/v1/projects/PROJECT_OR_ID:optimizeTours
Devi anche impostare i timeout e le scadenze in modo che siano brevi per ridurre i tempi di attesa non necessari. Per questo scenario di asilo per cani, l'ottimizzatore non ha bisogno di molto tempo per rispondere alla tua richiesta, quindi utilizza le seguenti impostazioni:
- Imposta il parametro
timeoutsu 2 secondi. - Lascia le impostazioni della scadenza sul valore predefinito, ovvero 60 secondi per le richieste REST.
2. Crea il corpo del messaggio di richiesta
Dopo aver scelto il metodo di blocco optimizeTours e aver definito le impostazioni di timeout e scadenza, il passaggio successivo consiste nel creare il corpo del messaggio di richiesta.
Per questo scenario, la richiesta è un messaggio OptimizeToursRequest codificato come JSON nell'API REST.
Per creare il messaggio di richiesta, segui questi passaggi:
Inizia con la struttura di base della richiesta, che è la seguente:
{ "timeout": ..., "model": { "shipments": [...], "vehicles": [...], "globalStartTime": "...", "globalEndTime": "..." } }Per ulteriori informazioni sulla struttura, consulta la guida ai concetti chiave per la struttura di base (ShipmentModel, Shipment e Vehicle).
Definisci le spedizioni. Nel campo
shipments, aggiungi un messaggioShipmentper ogni cane che deve essere prelevato e riconsegnato al mattino. Qui definisci i luoghi e gli orari di ritiro preferiti di ogni proprietario di cani e il luogo e gli orari di consegna dei cani del centro diurno.Per ogni cane, crea un
VisitRequestper i ritiri e un altro per le consegne, che in questo scenario viene definito consegna all'asilo.In pickups, imposta
arrivalWaypointsulla località di ritiro del cane (Coit Tower per il bovaro del bernese, South Sunset Playground Park per il chihuahua o Land's End per il pastore tedesco). ImpostatimeWindowssull'orario di partenza richiesto dal proprietario (dalle 08:00 alle 08:20 per il bovaro del bernese e il pastore tedesco e dalle 07:30 alle 09:30 per il chihuahua).In deliveries, imposta
arrivalWaypointsul centro diurno etimeWindowssull'ora di arrivo richiesta (dalle 09:30 alle 11:30).Per tutti i ritiri e le consegne, imposta
durationsu 5 minuti (300s) per tenere conto del carico e dello scarico dei cani.
Per saperne di più sulle finestre temporali, consulta Finestre temporali.
Per dare la priorità ai clienti abituali, imposti
penaltyCostsu1000per il bovaro del bernese e il chihuahua e su100per il pastore tedesco. Con i costi di penalità impostati, l'ottimizzatore può saltare uno qualsiasi dei cani, ma considera prima di saltare il pastore tedesco (che ha una penalità inferiore) se i vincoli rendono impossibile eseguire tutti i ritiri.Puoi utilizzare il campo
labelper aggiungere un identificatore per ogni spedizione, ad esempio "Bovaro del bernese", "Chihuahua" e "Pastore tedesco". In questo modo puoi identificare le spedizioni nella risposta.
Per saperne di più sulla definizione delle spedizioni, consulta Spedizione.
Definisci i veicoli. Nel campo
vehicles, aggiungi un messaggioVehicleper il tuo furgone con l'asilo nido come punto di partenza e di arrivo, il costo dello stipendio del conducente e l'orario di apertura del furgone.Imposta
startWaypointeendWaypointper il furgone sulle località di partenza e di arrivo della giornata, ovvero l'asilo nido vicino a Mission Dolores Park.Per ridurre al minimo i costi operativi, devi definire i vincoli di costo della tua attività. Imposta il parametro di costo
costPerHoursu27, ovvero l'importo che paghi al conducente per guidare il furgone dell'asilo per cani. Per saperne di più sui parametri di costo, consulta Modello di costo.Per assicurarti che l'ottimizzatore crei un percorso entro l'orario di apertura del furgone, definisci una finestra di operatività per il veicolo. Questa finestra imposta i vincoli di ora di inizio e di fine per il percorso. Definendo solo una metà di ogni finestra temporale, darai all'ottimizzatore la flessibilità di iniziare il percorso più tardi o terminarlo prima:
Se imposti
startTimeinstartTimeWindowsalle 07:00, il conducente può iniziare il turno alle 07:00. Può anche iniziare più tardi se non ci sono ritiri la mattina presto.Se imposti
endTimeinendTimeWindowssu mezzogiorno, il conducente deve terminare il turno entro mezzogiorno. Possono anche terminare il turno non appena completano l'ultima consegna.
Omettendo l'altra metà delle finestre, si riducono al minimo i tempi di attesa e di deviazione del conducente. Per saperne di più sulle finestre temporali, consulta Finestre temporali.
Per saperne di più sulla definizione dei veicoli, consulta Veicolo.
Imposta una finestra temporale globale. La finestra temporale globale rappresenta il periodo di tempo in cui il furgone può effettuare i ritiri e le consegne per l'asilo nido durante il giorno. Per questo scenario, imposta
globalStartTimealle 07:00 eglobalEndTimealle 19:00 del 13 febbraio 2024, che rappresentano l'orario di apertura del tuo asilo per cani.
3. Invia la richiesta
Di seguito è riportata una semplice richiesta curl basata sullo scenario dell'asilo per cani che utilizza il metodo di blocco optimizeTours.
Prima di inviare la richiesta, sostituisci PROJECT_NUMBER_OR_ID nel codice campione con l'ID progetto 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
Parametri di richiesta utilizzati nella richiesta
La seguente tabella descrive i parametri di richiesta utilizzati nel corpo della richiesta dello scenario di esempio. Puoi filtrare i contenuti per elemento principale o tramite ricerca testuale.
| Genitore | Parametro | Tipo di proprietà | Descrizione |
|---|---|---|---|
OptimizeToursRequest |
model |
oggetto (ShipmentModel) |
Questo è l'elemento centrale della tua richiesta. Si tratta di un singolo oggetto in cui definisci l'intero problema, inclusi tutti i cani che devi ritirare e consegnare (shipments) e il furgone della tua flotta (vehicles). Consideralo come il progetto completo del problema che devi ottimizzare. |
timeout |
Durata | Questo parametro specifica il tempo massimo di elaborazione di una richiesta da parte del server prima di restituire una risposta. Utilizza questo parametro per ridurre il tempo di attesa. Per richieste piccole e rapide, come questo scenario di asilo per cani, imposta questo valore su 2s. | |
ShipmentModel |
shipments[] |
array di oggetti (Shipment) |
Si tratta di un array di oggetti in cui ogni oggetto rappresenta un cane che deve essere prelevato o consegnato. |
vehicles[] |
array di oggetti (Vehicle) |
Si tratta di un array di oggetti in cui ogni oggetto definisce un veicolo della tua flotta. Qui descrivi le tue risorse, ad esempio il furgone che effettua i ritiri e le consegne. Devi definire almeno un veicolo per ottenere un percorso ottimizzato. | |
globalStartTime |
Timestamp | Questa è la prima ora possibile in cui può verificarsi un evento nell'intero modello. Questo parametro restringe il problema di ottimizzazione nel tempo, il che è fondamentale per calcoli accurati del traffico e del percorso. Per questo scenario di asilo per cani, imposta questo valore sull'orario più presto in cui il conducente può utilizzare il furgone per il giorno, ovvero le 07:00 del 13 febbraio 2024. | |
globalEndTime |
Timestamp | Questo è l'ultimo momento possibile in cui può verificarsi un evento nell'intero modello. Per questo scenario di asilo per cani, imposta questo valore sull'ora in cui è previsto che il furgone termini il suo servizio, ovvero le 19:00 del 13 febbraio 2024. | |
Shipment |
pickups[] |
array di oggetti (VisitRequest) |
Questo è un elenco di tutte le possibili opzioni di ritiro per la spedizione. L'ottimizzatore sceglie quello migliore per risolvere il problema. Per questo scenario di asilo per cani, elenca i luoghi di ritiro e le fasce orarie fornite da ciascun proprietario per ogni cane. |
deliveries[] |
array di oggetti (VisitRequest) |
Questo è un elenco di tutte le possibili opzioni di consegna per la spedizione. L'ottimizzatore sceglie quello migliore per risolvere il problema. Per questo scenario di asilo per cani, elenca la posizione della struttura e la finestra temporale in cui il conducente deve tornare per il pranzo di ogni cane. | |
label |
stringa | Si tratta di un identificatore per una spedizione specifica nella richiesta. Puoi specificare le etichette nella richiesta per facilitare la lettura della risposta. Per questo scenario di asilo per cani, utilizza una stringa descrittiva come "Chihuahua", "Bovaro del bernese" o il nome del cane per abbinare la soluzione al tuo input quando ricevi la risposta dell'API. | |
penaltyCost |
doppia | Questo è il costo della penalità sostenuto se l'ottimizzatore salta questa spedizione. Per impostazione predefinita, le spedizioni sono obbligatorie: l'ottimizzatore dà la priorità alla riduzione al minimo delle spedizioni obbligatorie saltate e le salta solo quando non ci sono altre opzioni. L'impostazione di un costo di penalità consente all'ottimizzatore di saltare una spedizione se non è fattibile o è troppo costosa da eseguire e ti consente di valutare le priorità tra le spedizioni. In questo scenario, imposti un costo di penalità più elevato (1000) per i tuoi clienti abituali (bovaro del bernese e chihuahua) e un costo di penalità inferiore (100) per la richiesta last minute del pastore tedesco. In questo modo, l'ottimizzatore dà la priorità ai clienti abituali, quindi considera di saltare prima il pastore tedesco quando non può eseguire tutti i ritiri. |
|
VisitRequest |
arrivalWaypoint |
oggetto (Waypoint) |
Questa è la posizione di una visita specifica sul percorso. Puoi definirlo utilizzando le coordinate di latitudine e longitudine, un ID luogo o un'intestazione. In questo scenario di asilo per cani, imposta questo valore sulla località fornita dal proprietario per pickups e sull'indirizzo dell'asilo per deliveries. |
timeWindows[] |
array di oggetti (TimeWindow) |
Si tratta di un array di oggetti che definiscono i vincoli di tempo per un ritiro o una consegna. Per questo scenario, utilizza questo campo per definire la finestra di ritiro per ogni cane e la finestra accettabile per la consegna dei cani presso il centro diurno. | |
duration |
Durata | Questo parametro specifica la durata della visita (ad es. il tempo di carico o scarico). In questo scenario, imposti un buffer di 5 minuti (300s) per tutti i ritiri e le consegne per tenere conto del tempo necessario al conducente per caricare e scaricare i cani. |
|
Vehicle |
startWaypoint |
oggetto (Waypoint) |
Questa è la località di partenza del percorso del veicolo, definita con coordinate di latitudine e longitudine o un ID luogo. Questo parametro indica all'ottimizzatore dove il veicolo deve iniziare il percorso. Se non definisci questo waypoint, l'ottimizzatore sceglie uno dei ritiri o delle consegne come località di partenza. Per questo scenario di asilo per cani, poiché il conducente inizia la giornata presso la struttura, utilizza le coordinate di Mission Dolores Park. |
endWaypoint |
oggetto (Waypoint) |
Questa è la destinazione finale del percorso del veicolo, definita con le coordinate di latitudine e longitudine o un ID luogo. Questo parametro indica all'ottimizzatore dove il veicolo deve terminare il percorso. Se non definisci questo waypoint, l'ottimizzatore sceglie uno dei ritiri o delle consegne come fine del percorso. Per questo scenario di asilo per cani, poiché il conducente deve terminare la giornata presso la struttura, utilizza le coordinate di Mission Dolores Park. | |
costPerHour |
numero | Questo è il costo sostenuto per ogni ora di utilizzo di un veicolo, indipendentemente dal fatto che sia in viaggio o fermo. Per questo scenario di asilo per cani, utilizza questo elemento per modellare la tariffa oraria di un conducente. | |
startTimeWindows[] |
array di oggetti (TimeWindow) |
Questa è la finestra temporale accettabile in cui il conducente può iniziare il proprio turno. Per questo scenario di asilo per cani, definisci startTime come 07:00, ma ometti endTime. In questo modo, l'ottimizzatore può ritardare l'inizio del turno se il primo ritiro è previsto più tardi nel corso della mattinata. Tieni presente che, anche se non fornisci un endTime per startTimeWindows, l'ora di inizio è implicitamente limitata da endTimeWindows. Il veicolo deve iniziare il percorso prima che questo termini. |
|
endTimeWindows[] |
array di oggetti (TimeWindow) |
Questa è la finestra temporale accettabile per il conducente per completare il percorso.
Per questo scenario di asilo per cani, definisci endTime come mezzogiorno, ma ometti startTime. In questo modo, il conducente può tornare all'asilo nido immediatamente dopo l'ultima consegna. |