Interpreta la risposta

L'API Route Optimization restituisce i percorsi per i veicoli nella richiesta corrispondente. Le spedizioni vengono assegnate ai veicoli o possono essere ignorate, a seconda delle proprietà della richiesta.

Un messaggio OptimizeToursResponse (REST, gRPC) ha due proprietà di primo livello principali:

• routes[] sono i percorsi di ogni veicolo con le spedizioni assegnate. Ogni Route contiene metriche che riflettono le proprietà della singola route.
• metrics sono metriche aggregate per l'intera risposta, per tutti i veicoli e i piani di percorso. Le metriche di primo livello contengono le stesse proprietà delle metriche per route, con i valori aggregati per tutte le route.

Alcune proprietà potrebbero non essere sempre compilate a seconda dei risultati dell'ottimizzazione:

1. skippedShipments[] elenca le spedizioni non effettuate da nessun veicolo. Una spedizione può essere saltata se non può essere eseguita rispettando i vincoli specificati o se il costo di esecuzione della spedizione supera il costo della penale. Ad esempio, se il ritiro o la consegna di una spedizione prevede un timeWindow molto limitato, potrebbe non essere possibile o economicamente conveniente per un veicolo effettuare la visita durante il periodo di tempo richiesto.
2. validationErrors[] specifica gli errori che rendono la richiesta non valida o impossibile da risolvere se il valore solvingMode della richiesta è impostato su VALIDATE_ONLY. In modalità DEFAULT_SOLVE normale, gli errori di convalida verranno riportati in un messaggio di errore anziché nel corpo della risposta. Tieni presente che la modalità di risoluzione di VALIDATE_ONLY può segnalare più errori contemporaneamente, utile per eseguire rapidamente il debug delle richieste.

Nota: per interpretare una risposta, è necessaria la richiesta corrispondente. La risposta contiene riferimenti a entità nella richiesta, il che rende la risposta difficile da interpretare da sola. Alcuni messaggi come Shipment e Vehicle hanno proprietà di etichetta per facilitare la corrispondenza dei dati di richiesta e risposta.

Proprietà percorso

Ogni voce routes[] è un messaggio ShipmentRoute (REST, gRPC). Ciascun ShipmentRoute rappresenta l'assegnazione del percorso per un determinato veicolo dalla richiesta. Le proprietà ShipmentRoute importanti correlate all'elemento Vehicle corrispondente includono:

• vehicleIndex è l'indice in base zero di Vehicle nel messaggio di richiesta corrispondente. Le risposte REST omettono questa proprietà quando il valore è zero.
• vehicleStartTime è l'ora in cui il veicolo deve iniziare il percorso.
• vehicleEndTime è l'ora in cui è previsto il completamento del percorso del veicolo.

In risposta, routes avrà il seguente aspetto:

{
  "routes": [
    {
      "vehicleStartTime": "2024-02-13T00:00:00Z",
      "vehicleEndTime": "2024-02-13T00:38:42Z",
      "visits": [
        ...
      ],
      "transitions": [
        ...
      ],
      "metrics": {
        ...
      },
      ...
    }
  ],
  ...
}

Nota: le risposte REST utilizzano la rappresentazione JSON dei buffer di protocollo, che omette i campi con il rispettivo valore predefinito e che non supportano i campi presenti. Ciò significa che le proprietà dei numeri interi come vehicleIndex vengono omesse quando i relativi valori sono pari a zero. Consulta anche la documentazione ufficiale sulla mappatura JSON relativa a buffer di protocollo.

Ogni ShipmentRoute include un elenco ordinato di visits che il veicolo verrà completato. Ciascun Visit (REST, gRPC) rappresenta un elemento VisitRequest (REST, gRPC) dalla richiesta corrispondente. Le proprietà di Visit importanti includono:

• shipmentIndex è l'indice in base zero della spedizione a cui appartiene questa visita nella richiesta corrispondente.
• isPickup è vero quando una visita è una prenotazione e falso quando una visita è una consegna. Le risposte REST omettono questa proprietà quando il valore è false.
• visitRequestIndex è l'indice in base zero di VisitRequest da Shipment.pickups o Shipment.deliveries nella richiesta corrispondente rappresentata da Visit. Le risposte REST omettono questa proprietà quando il valore è zero.
• startTime è l'ora prevista di inizio della visita.
• loadDemands tipo di caricamento delle mappe per caricare la quantità richiesta per completare Visit. Gli importi di caricamento sono negativi per le visite in consegna e rappresentano il carico che viene rimosso dal veicolo.

Un esempio di Visit ha il seguente aspetto:

{
  "routes": [
    {
      ...
      "visits": [
        {
          "isPickup": true,
          "startTime": "2024-02-13T00:00:00Z",
          "detour": "0s"
        },
        ...
      ],
    },
    ...
  ],
  ...
}

Ogni ShipmentRoute include un elenco ordinato di transitions che rappresentano viaggi tra visits per un determinato veicolo. Le proprietà dei messaggi Transition importanti (REST, gRPC) includono:

• startTime è l'ora in cui inizierà la transizione del veicolo.
• travelDuration è il tempo di percorrenza del veicolo per completare la transizione.
• travelDistanceMeters è la distanza in metri che il veicolo deve percorrere per completare la transizione.
• trafficInfoUnavailable indica se sono disponibili dati sul traffico per la transizione.
• waitDuration rappresenta il tempo di inattività che il veicolo trascorre prima di poter avviare Visit. Ciò può essere dovuto ai start_time dei seguenti Visit.
• totalDuration è la durata totale della transizione, inclusi i tempi di viaggio, attesa, pausa e ritardo.
• vehicleLoads mappa il tipo di caricamento in base alla quantità trasportata dal veicolo durante questa transizione.

Un esempio di Transition ha il seguente aspetto:

{
  "routes": [
    {
      ...
      "transitions": [
        ...
        {
          "travelDuration": "1171s",
          "travelDistanceMeters": 9004,
          "waitDuration": "0s",
          "totalDuration": "1171s",
          "startTime": "2024-02-13T00:00:00Z"
        },
        ...
      ],
      ...
    }
  ],
  ...
}

La relazione tra vists e transitions è descritta in Ottimizzazione degli ordini di ritiro e interruzione della consegna, nonché nella documentazione di riferimento di ShipmentRoute (REST, gRPC).

Proprietà delle metriche

Il messaggio Metrics (REST, gRPC) riassume l'intera soluzione. Alcune proprietà Metrics importanti includono:

• totalCost è il costo totale sostenuto per completare i percorsi. Per ulteriori informazioni sui costi, consulta Parametri del modello di costo.
• usedVehicleCount è il numero totale di veicoli utilizzati nella soluzione. I veicoli possono avere percorsi vuoti quando l'ottimizzatore stabilisce che il loro utilizzo non è necessario.
• skippedMandatoryShipmentCount è il numero "obbligatorio" per le spedizioni saltate. Una spedizione obbligatoria non specifica un penaltyCost che si applica se la spedizione viene saltata. Le spedizioni obbligatorie possono comunque essere ignorate se le loro prestazioni non sono attuabili secondo i vincoli specificati. Per ulteriori informazioni sui costi, consulta Parametri del modello di costo.

Le metriche aggiuntive sono segnalate come messaggi AggregatedMetrics (REST, gRPC). Il tipo di messaggio AggregatedMetrics viene utilizzato per la proprietà Metrics.aggregatedRouteMetrics e per la proprietà ShipmentRoute.metrics Metrics.aggregatedRouteMetrics contiene metriche aggregate per tutti i ShipmentRoute nella OptimizeToursResponse. Ogni proprietà ShipmentRoute.metrics contiene metriche per quel determinato ShipmentRoute.

Le proprietà importanti di AggregatedMetrics includono:

• performedShipmentCount è il numero di spedizioni effettuate dai veicoli su tutti i percorsi.
• travelDuration è il tempo totale che i veicoli trascorrono in transito durante il completamento dei percorsi.
• waitDuration è il tempo totale di attesa dei veicoli durante il completamento dei percorsi.
• delayDuration è il tempo totale di ritardo per i veicoli. In genere il valore è zero, a meno che nella richiesta non vengano utilizzati i criteri TransitionAttributes.
• breakDuration è il tempo totale che i veicoli trascorrono nelle pause durante il completamento dei percorsi.
• visitDuration è il tempo totale che i veicoli impiegano per effettuare visite durante il completamento dei percorsi. Si tratta effettivamente della somma di tutti i valori di VisitRequest.duration per VisitRequest corrispondenti a Visit assegnati al veicolo applicabile.
• totalDuration è la durata totale richiesta per completare i percorsi dei veicoli.
• travelDistanceMeters è la distanza totale percorsa dai veicoli durante il completamento dei loro percorsi.
• maxLoads mappa i tipi di carico alla quantità massima di carico trasportata dai veicoli in qualsiasi punto del loro percorso.

Un esempio di messaggio Metrics ha il seguente aspetto:

{
  "routes": [
    ...
  ],
  "metrics": {
    "aggregatedRouteMetrics": {
      "performedShipmentCount": 1,
      "travelDuration": "2322s",
      "waitDuration": "0s",
      "delayDuration": "0s",
      "breakDuration": "0s",
      "visitDuration": "0s",
      "totalDuration": "2322s",
      "travelDistanceMeters": 18603
    },
    "usedVehicleCount": 1,
    "earliestVehicleStartTime": "2024-02-13T00:00:00Z",
    "latestVehicleEndTime": "2024-02-13T00:38:42Z",
    "totalCost": 18.603,
    "costs": {
      "model.vehicles.cost_per_kilometer": 18.603
    }
  }
}

Importante: se tutti i costi sono pari a zero nei messaggi Metrics o ShipmentRoute, è improbabile che l'ottimizzatore abbia trovato un ordine ottimale per il completamento di Visit. È necessario specificare almeno un parametro di costo, ad esempio Vehicle.costPerKilometer o globalDurationCostPerHour, altrimenti l'ottimizzatore potrebbe restituire qualsiasi soluzione che soddisfi i vincoli specificati.

Esempio completo

Un esempio completo di risposta per la richiesta da Realizza una richiesta ha il seguente aspetto:

{
  "routes": [
    {
      "vehicleStartTime": "2024-02-13T00:00:00Z",
      "vehicleEndTime": "2024-02-13T00:38:42Z",
      "visits": [
        {
          "isPickup": true,
          "startTime": "2024-02-13T00:00:00Z",
          "detour": "0s"
        },
        {
          "startTime": "2024-02-13T00:19:31Z",
          "detour": "0s"
        }
      ],
      "transitions": [
        {
          "travelDuration": "0s",
          "waitDuration": "0s",
          "totalDuration": "0s",
          "startTime": "2024-02-13T00:00:00Z"
        },
        {
          "travelDuration": "1171s",
          "travelDistanceMeters": 9004,
          "waitDuration": "0s",
          "totalDuration": "1171s",
          "startTime": "2024-02-13T00:00:00Z"
        },
        {
          "travelDuration": "1151s",
          "travelDistanceMeters": 9599,
          "waitDuration": "0s",
          "totalDuration": "1151s",
          "startTime": "2024-02-13T00:19:31Z"
        }
      ],
      "metrics": {
        "performedShipmentCount": 1,
        "travelDuration": "2322s",
        "waitDuration": "0s",
        "delayDuration": "0s",
        "breakDuration": "0s",
        "visitDuration": "0s",
        "totalDuration": "2322s",
        "travelDistanceMeters": 18603
      },
      "routeCosts": {
        "model.vehicles.cost_per_kilometer": 18.603
      },
      "routeTotalCost": 18.603
    }
  ],
  "metrics": {
    "aggregatedRouteMetrics": {
      "performedShipmentCount": 1,
      "travelDuration": "2322s",
      "waitDuration": "0s",
      "delayDuration": "0s",
      "breakDuration": "0s",
      "visitDuration": "0s",
      "totalDuration": "2322s",
      "travelDistanceMeters": 18603
    },
    "usedVehicleCount": 1,
    "earliestVehicleStartTime": "2024-02-13T00:00:00Z",
    "latestVehicleEndTime": "2024-02-13T00:38:42Z",
    "totalCost": 18.603,
    "costs": {
      "model.vehicles.cost_per_kilometer": 18.603
    }
  }
}