Interpreta la risposta

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

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

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

Alcune proprietà potrebbero non essere sempre compilate, a seconda dei risultati di ottimizzazione:

1. skippedShipments[] elenca le spedizioni che non vengono effettuate da alcun veicolo. Una spedizione può essere saltata se non può essere eseguita entro i vincoli specificati o se il costo dell'esecuzione della spedizione supera il costo delle penali. Ad esempio, se il ritiro o la consegna di una spedizione ha un numero di consegna molto ristretto timeWindow, potrebbe non essere possibile o non è possibile 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 quando il valore del campo solvingMode della richiesta è impostato su VALIDATE_ONLY. In modalità DEFAULT_SOLVE normale, gli errori di convalida vengono visualizzati 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, il che è utile per eseguire rapidamente il debug delle richieste.

Nota: per interpretare una risposta, è necessaria la richiesta corrispondente. La risposta contiene riferimenti alle entità nella richiesta, rendendo la risposta difficile da interpretare da sola. Alcuni messaggi come Shipment e Vehicle hanno proprietà di etichetta che consentono una corrispondenza più semplice dei dati relativi alle richieste e alle risposte.

Proprietà percorso

Ogni voce routes[] è un messaggio ShipmentRoute (REST, gRPC). Ogni ShipmentRoute rappresenta l'assegnazione del percorso per un determinato veicolo della richiesta. Le proprietà ShipmentRoute importanti correlate alla proprietà 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 indica l'ora in cui il veicolo deve iniziare il percorso.
• vehicleEndTime è l'ora in cui è previsto che il veicolo finisca il percorso.

In una risposta, routes sarà simile a:

{
  "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 valore predefinito del rispettivo tipo e che non supportano i campi presenti. Ciò significa che le proprietà di numeri interi come vehicleIndex vengono omesse quando i loro valori sono zero. Consulta anche la documentazione ufficiale di mappatura JSON dei buffer di protocollo.

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

• shipmentIndex è l'indice in base zero della spedizione a cui appartiene questa visita nella richiesta corrispondente.
• isPickup è vero quando una visita è un prelievo e falso quando una visita è una consegna. Le risposte REST omettono questa proprietà quando il valore è false.
• visitRequestIndex è l'indice in base zero del VisitRequest di Shipment.pickups o Shipment.deliveries nella richiesta corrispondente rappresentata da Visit. Le risposte REST omettono questa proprietà quando il valore è zero.
• startTime è l'ora di inizio prevista della visita.
• loadDemands tipo di caricamento delle mappe per l'importo di caricamento richiesto per completare il Visit. Gli importi del carico sono negativi per le visite in consegna, poiché il carico 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 i viaggi tra visits per un determinato veicolo. Le proprietà importanti del messaggio Transition (REST, gRPC) includono:

• startTime è l'ora in cui il veicolo inizierà per eseguire la transizione.
• travelDuration è la durata del viaggio 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à del veicolo prima di poter avviare i Visit successivi. Ciò potrebbe verificarsi a causa dei start_time dei seguenti Visit.
• totalDuration è la durata totale della transizione, inclusi i tempi di viaggio, attesa, pausa e ritardo.
• Il tipo di caricamento delle mappe vehicleLoads in base alla quantità di carico 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 nell'articolo sull'ottimizzazione degli ordini con interruzione degli ordini di ritiro e consegna, nonché nella documentazione di riferimento ShipmentRoute (REST, gRPC).

Proprietà delle metriche

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

• totalCost è il costo totale sostenuto per il completamento dei percorsi. Scopri di più sui costi in Parametri del modello di costo.
• usedVehicleCount è il numero totale di veicoli utilizzati nella soluzione. I veicoli potrebbero avere percorsi vuoti quando l'ottimizzatore stabilisce che il loro utilizzo non è necessario.
• skippedMandatoryShipmentCount è il numero di spedizioni saltate "obbligatorie". Una spedizione obbligatoria non specifica un penaltyCost in corso nel caso in cui la spedizione venga saltata. Le spedizioni obbligatorie possono comunque essere saltate se le loro prestazioni non sono attuabili in base ai vincoli specificati. Scopri di più sui costi in Parametri del modello di costo.

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.metricsMetrics.aggregatedRouteMetrics contiene metriche aggregate per tutte le ShipmentRoute nella OptimizeToursResponse. Ogni proprietà ShipmentRoute.metrics contiene metriche per quella specifica ShipmentRoute.

Le proprietà AggregatedMetrics importanti includono:

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

Un messaggio Metrics di esempio 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 del 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 di risposta completo per la richiesta da Costruire una richiesta è simile a:

{
  "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
    }
  }
}