Effettua la tua prima richiesta di ottimizzazione del percorso

Sviluppatori dello Spazio economico europeo (SEE)

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 dimostrare l'API REST. Per l'ambiente di produzione, tuttavia, il consiglio generale è di utilizzare gRPC per i vantaggi in termini di prestazioni. Tuttavia, gRPC richiede l'installazione. Per ulteriori informazioni, consulta Librerie client dell'API Route Optimization.

Scenario

Mappa di San Francisco con segnaposto per la Coit Tower, il Mission Dolores Park e il South Sunset Playground Park

Gestisci un servizio di pensione diurna per cani dalle 7:00 alle 19:00 a San Francisco. Questa mattina devi prendere due cani in luoghi diversi della città. Entrambi i proprietari di cani ti hanno indicato una fascia oraria di ritiro tra le 7:30 e le 9:30.

Hai un furgone per il lavoro e paghi l'autista 27 dollari l'ora. L'autista e il furgone iniziano la giornata al tuo asilo nido alle 7:00 e devono tornare dai prelievi mattutini entro le 12:00 per la pausa pranzo.

Oggi è il 13 febbraio 2024 e l'autista ha le seguenti attività:

  • Prendi il bovaro del bernese vicino alla Coit Tower.
  • Recupera il chihuahua al South Sunset Playground Park.
  • Lascia entrambi i cani all'asilo nido per cani al Mission Dolores Park.

Devi trovare un percorso che riduca al minimo il tempo che i cani trascorrono nel furgone, rispettando al contempo i requisiti di ritiro e arrivo.

Prima di iniziare

Per eseguire il codice in questo scenario di esempio, devi prima completare le istruzioni riportate in Configurare l'API Route Optimization.

1. Scegliere l'approccio di ottimizzazione del percorso

L'API Route Optimization offre diversi metodi tra cui scegliere a seconda della complessità del problema di ottimizzazione.

Poiché questo scenario di asilo nido per cani è una richiesta piccola e semplice, utilizza un metodo di blocco, ad esempio optimizeTours, che fornisce rapidamente risultati per le piccole richieste. Per saperne di più sui metodi dell'API Route Optimization, consulta Endpoint sincroni e asincroni.

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 tempi di attesa e i termini brevi per ridurre i tempi di attesa non necessari. Per questo scenario di asilo per cani, lo strumento di ottimizzazione non ha bisogno di molto tempo per rispondere alla tua richiesta, quindi utilizza le seguenti impostazioni:

  • Imposta il parametro timeout su 2 secondi.
  • Lascia le impostazioni della scadenza al valore predefinito, ovvero 60 secondi per le richieste REST.

2. Costruire il corpo del messaggio della richiesta

Dopo aver scelto il metodo di blocco optimizeTours e aver definito le impostazioni di timeout e scadenza, il passo 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 i passaggi successivi:

  1. 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).

  2. Definisci le spedizioni. Nel campo shipments, aggiungi un messaggio Shipment per ogni cane che deve essere preso e riportato al mattino. Qui devi definire la posizione e gli orari di ritiro preferiti di ciascun proprietario del cane e la posizione e gli orari del centro diurno per lasciare i cani.

    1. Per ogni cane, crea un VisitRequest per i ritiri e un altro per le consegne, che in questo scenario viene chiamato consegna all'asilo nido.

      • Nei ritiri, imposta arrivalWaypoint sul luogo di ritiro del cane (Coit Tower per il Bovaro del Bernese o South Sunset Playground Park per il Chihuahua) e timeWindows sull'orario di ritiro richiesto dal proprietario (dalle 7:30 alle 9:30).

      • Nelle consegne, imposta arrivalWaypoint sull'asilo nido e timeWindows sull'orario di consegna richiesto (dalle 9:30 alle 11:30).

      Per saperne di più sulle finestre temporali, consulta Finestre temporali.

    2. Puoi utilizzare il campo label per aggiungere un identificatore per ogni spedizione, ad esempio "Bovaro del Bernese" e "Chihuahua". Questo può aiutarti a identificare le spedizioni nella risposta.

    Per ulteriori informazioni sulla definizione delle spedizioni, vedi Spedizione.

  3. Definisci i veicoli. Nel campo vehicles, aggiungi un messaggio Vehicle per il tuo furgone con l'asilo nido come punto di partenza e di arrivo, il costo dello stipendio dell'autista e l'orario di lavoro del furgone.

    1. Imposta l'startWaypoint e l'endWaypoint del furgone per le località di inizio e fine della giornata, ovvero l'asilo nido vicino al Mission Dolores Park.

    2. Per ridurre al minimo i costi operativi, devi definire i vincoli di costo della tua attività. Imposta il parametro di costo costPerHour su 27, ovvero l'importo che paghi al conducente per guidare il furgone dell'asilo nido per cani. Per ulteriori informazioni sui parametri di costo, consulta Modello di costi.

    3. Per assicurarti che l'ottimizzatore crei un percorso entro l'orario di funzionamento del furgone, definisci startTimeWindows nell'intervallo accettabile per l'inizio dell'attività del conducente del furgone e endTimeWindows nell'intervallo accettabile per il rientro del conducente all'asilo nido. Per saperne di più sulle finestre temporali, consulta Finestre temporali.

    Per saperne di più sulla definizione dei veicoli, consulta Veicolo.

  4. Imposta una finestra temporale globale. La finestra temporale globale rappresenta l'intervallo di tempo in cui il furgone può effettuare i ritiri e gli accompagnamenti per il tuo asilo nido durante la giornata. Per questo scenario, imposta globalStartTime alle 7:00 e globalEndTime alle 19:00 del 13 febbraio 2024, che rappresentano gli orari di apertura della tua pensione per cani.

3. Invia la richiesta

Di seguito è riportata una semplice richiesta curl basata sullo scenario dell'asilo per cani e utilizza il metodo di blocco optimizeTours.

Prima di inviare la richiesta, sostituisci PROJECT_NUMBER_OR_ID nel codice di esempio con l'ID del tuo 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-13T07:30:00Z",
                "endTime": "2024-02-13T09:30:00Z"
              }
            ]
          }
        ],
        "deliveries": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.760202,
                  "longitude": -122.426796
                }
              }
            },
            "timeWindows": [
              {
                "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
                }
              }
            },
            "timeWindows": [
              {
                "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

Parametri di richiesta utilizzati nella richiesta

La seguente tabella descrive i parametri della richiesta utilizzati nel corpo della richiesta dello scenario di esempio. Puoi filtrare i contenuti per genitore o per ricerca di testo.

Genitore Parametro Tipo di proprietà Descrizione
OptimizeToursRequest model oggetto (ShipmentModel) Questo è il fulcro della tua richiesta. Si tratta di un singolo oggetto in cui definisci l'intero problema, inclusi tutti i cani che devi prendere e lasciare (shipments) e il furgone della tua flotta (vehicles). Consideralo il progetto completo del problema che devi ottimizzare.
timeout Durata Questo parametro specifica il tempo massimo in cui il server elabora una richiesta 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 2 secondi.
ShipmentModel shipments[] array di oggetti (Shipment) Si tratta di un array di oggetti in cui ogni oggetto rappresenta un cane che deve essere ritirato o lasciato.
vehicles[] array di oggetti (Vehicle) Si tratta di un array di oggetti in cui ogni oggetto definisce un veicolo della tua flotta. È qui che descrivi le tue risorse, ad esempio il furgone che esegue i ritiri e le consegne. Devi definire almeno un veicolo per ottenere un percorso ottimizzato.
globalStartTime Timestamp Questo è il momento più remoto in cui può verificarsi un evento nell'intero modello. Questo parametro restringe il problema di ottimizzazione nel tempo, il che è fondamentale per calcoli accurati di traffico e routing. Per questo scenario di asilo nido per cani, imposta questo valore sull'ora più presto in cui l'autista può guidare il furgone per la giornata, ovvero le 7: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 nido per cani, imposta questo valore sull'ora in cui il furgone dovrebbe terminare l'operazione, 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 la migliore per risolvere il problema. Per questo scenario di asilo nido per cani, elenca i luoghi e le fasce orarie di ritiro che ogni proprietario ha fornito per ogni cane.
deliveries[] array di oggetti (VisitRequest) Questo è un elenco di tutte le possibili opzioni di consegna per la spedizione. L'ottimizzatore sceglie la migliore per risolvere il problema. Per questo scenario di asilo nido per cani, elenca la posizione della struttura e l'intervallo di tempo in cui l'autista deve tornare per il pranzo di ogni cane.
label stringa Si tratta di un identificatore per una spedizione specifica nella tua richiesta. Puoi specificare le etichette nella richiesta per facilitare la lettura della risposta. Per questo scenario di asilo nido 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.
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 una direzione. In questo scenario di asilo nido per cani, imposta questa opzione sulla posizione fornita dal proprietario per pickups e sull'indirizzo dell'asilo nido per deliveries.
timeWindows[] array di oggetti (TimeWindow) Si tratta di un array di oggetti che definiscono i vincoli temporali per un ritiro o una consegna. Per questo scenario, utilizza questo campo per definire l'intervallo di ritiro per ciascuno dei cani e l'intervallo accettabile per lasciarli all'asilo nido.
Vehicle startWaypoint[] oggetto (Waypoint) Questa è la posizione 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 questa tappa, lo strumento di ottimizzazione sceglie uno dei ritiri o delle consegne come posizione iniziale. Per questo scenario di asilo per cani, poiché l'autista inizia la giornata presso la struttura dell'asilo, utilizza le coordinate di Mission Dolores Park.
endWaypoint[] oggetto (Waypoint) È la destinazione finale del percorso del veicolo, definita con coordinate di latitudine e longitudine o un ID luogo. Questo parametro indica all'ottimizzatore dove deve terminare il percorso del veicolo. 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é l'autista deve terminare la giornata presso la struttura dell'asilo, 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 movimento o fermo. Per questo scenario di asilo nido per cani, utilizza questo per modellare la paga oraria di un autista.
startTimeWindows[] array di oggetti (TimeWindow) Questo è l'intervallo accettabile per l'autista per iniziare a guidare il furgone per i ritiri mattutini dei cani.
endTimeWindows[] array di oggetti (TimeWindow) Questo è il periodo di tempo accettabile in cui l'autista può terminare di guidare il furgone e parcheggiare di nuovo al centro diurno per cani.

Avanti

Interpreta la risposta