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 ciascun veicolo con le relative spedizioni assegnate. Ogni Route contiene metriche che riflettono le proprietà del singolo percorso.
• metrics sono metriche aggregate per l'intera risposta, per tutti i veicoli e i piani di itinerario. Le metriche di primo livello contengono le stesse proprietà delle metriche per itinerario, con valori aggregati per tutti gli itinerari.

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

1. skippedShipments[] elenca le spedizioni che non vengono eseguite da nessun veicolo. Una spedizione può essere saltata se non può essere eseguita entro vincoli specificati o se il costo per l'esecuzione della spedizione supera il costo della penale. Ad esempio, se il ritiro o la consegna di una spedizione ha un periodo di tempo molto ridottotimeWindow, potrebbe non essere possibile o conveniente per un veicolo eseguire la visita durante la finestra temporale richiesta.
2. validationErrors[] specifica gli errori che rendono la richiesta non valida o impossibile da risolvere quando solvingMode della richiesta è impostato su VALIDATE_ONLY. Nella normale modalità DEFAULT_SOLVE, gli errori di convalida verranno visualizzati in un messaggio di errore anziché nel corpo della risposta. Tieni presente che la modalità di risoluzione 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, il che rende difficile interpretarla autonomamente. Alcuni messaggi, come Shipment e Vehicle, hanno proprietà di etichetta per consentire una più facile corrispondenza dei dati di richiesta e risposta.

Proprietà Route

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

• vehicleIndex è l'indice a partire da 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 prevista per il termine del percorso del veicolo.

In una 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 di Protocol Buffers, che omette i campi che hanno il valore predefinito del rispettivo tipo e che non supportano il campo presente. Ciò significa che le proprietà di tipo intero come vehicleIndex vengono omesse quando i relativi valori sono pari a zero. Consulta anche la documentazione ufficiale relativa alla mappatura JSON di Protocol Buffers.

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

• shipmentIndex è l'indice a partire da zero della spedizione a cui appartiene questa visita nella richiesta corrispondente.
• isPickup è true quando una visita è un ritiro e false quando è una consegna. Le risposte REST omettono questa proprietà quando il valore è false.
• visitRequestIndex è l'indice a zero del VisitRequest da Shipment.pickups o Shipment.deliveries nella richiesta corrispondente che Visit rappresenta. Le risposte REST omettono questa proprietà quando il valore è zero.
• startTime è l'ora prevista per l'inizio della visita.
• loadDemands mappa il tipo di carico all'importo del carico richiesto per completare il Visit. Gli importi del carico sono negativi per le visite di consegna, poiché rappresentano il carico che viene rimosso dal veicolo.

Un esempio di Visit è il seguente:

{
  "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 dei messaggi Transition (REST, gRPC) includono:

• startTime è l'ora in cui il veicolo inizierà a eseguire la transizione.
• travelDuration è la durata per cui il veicolo deve percorrere la tratta per completare la transizione.
• travelDistanceMeters è la distanza in metri che il veicolo deve percorrere per completare la transizione.
• trafficInfoUnavailable indica se i dati sul traffico sono disponibili per la transizione.
• waitDuration indica il tempo di inattività del veicolo in attesa prima di poter avviare il prossimo Visit. Ciò può verificarsi a causa del start_time del Visit che segue.
• totalDuration è la durata totale della transizione, inclusi i tempi di percorrenza, attesa, interruzione e ritardo.
• vehicleLoads mappa il tipo di carico alla quantità di carico trasportata dal veicolo durante questa transizione.

Un esempio di Transition è il seguente:

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

Per ulteriori informazioni sulla relazione tra vists e transitions, consulta Ottimizzazione dell'ordine di ritiro e consegna e la documentazione di riferimento di ShipmentRoute (REST, gRPC). Per ulteriori informazioni sulle proprietà routePolyline e routeToken di un messaggio Transition, consulta Polilinee di transizione e token percorso.

Proprietà delle metriche

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

• totalCost è il costo totale sostenuto per completare i percorsi. Scopri di più sui costi in Parametri del modello di costo.
• usedVehicleCount è il numero totale di veicoli utilizzati nella soluzione. I veicoli possono avere percorsi vuoti quando l'ottimizzatore determina che il loro utilizzo non è necessario.
• skippedMandatoryShipmentCount è il numero di spedizioni ignorate che sono "obbligatorie". Una spedizione obbligatoria non specifica un penaltyCost che viene applicato se la spedizione viene saltata. Le importazioni obbligatorie possono comunque essere saltate se il loro rendimento non è fattibile in base a vincoli specifici. Scopri di più sui costi in Parametri del modello di costo.

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

Le proprietà AggregatedMetrics importanti includono:

• performedShipmentCount è il numero di spedizioni effettuate dai veicoli lungo l'intero percorso.
• travelDuration è il tempo totale che i veicoli trascorrono in transito mentre completano i loro percorsi.
• waitDuration è il tempo totale che i veicoli trascorrono in attesa durante il completamento delle loro corse.
• delayDuration è il tempo di ritardo totale dei veicoli. Di solito è zero, a meno che nella richiesta non vengano utilizzati TransitionAttributes.
• breakDuration è il tempo totale che i veicoli trascorrono in pausa durante il completamento dei loro percorsi.
• visitDuration è il tempo totale impiegato dai veicoli per effettuare le visite durante il completamento dei loro percorsi. Si tratta in pratica della somma di tutti i valori VisitRequest.duration per VisitRequest corrispondenti a Visit assegnati al veicolo applicabile.
• totalDuration è la durata totale necessaria 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 al volume massimo trasportato dai veicoli in qualsiasi punto dei loro percorsi.

Un messaggio Metrics di esempio è simile al seguente:

{
  "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 di Creare una richiesta è simile al seguente:

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