Interpreta la risposta

Sviluppatori dello Spazio economico europeo (SEE)

L'API Route Optimization restituisce i percorsi 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 spedizioni assegnate. Ogni Route contiene metriche che riflettono le proprietà di quello specifico percorso.
  • metrics sono le metriche aggregate per l'intera risposta, relative a tutti i veicoli e piani di percorso. Le metriche di primo livello contengono le stesse proprietà delle metriche per percorso, con valori aggregati per tutti i percorsi.

Alcune proprietà possono talvolta non essere compilate a seconda dei risultati dell'ottimizzazione:

  1. skippedShipments[] elenca le spedizioni non eseguite da alcun veicolo. Una spedizione può essere saltata se non può essere eseguita entro i vincoli specificati o se il costo per eseguirla supera il costo della penalità. Ad esempio, se il ritiro o la consegna di una spedizione ha una timeWindow molto ristretta, potrebbe non essere possibile o conveniente per un veicolo effettuare la visita nella finestra di tempo richiesta.
  2. validationErrors[] specifica gli errori che rendono la richiesta non valida o impossibile da risolvere quando solvingMode è impostato su VALIDATE_ONLY per la richiesta. Nella normale modalità DEFAULT_SOLVE, gli errori di convalida vengono visualizzati in un messaggio di errore anziché nel corpo della risposta. Tieni presente che la modalità di risoluzione dei problemi VALIDATE_ONLY può segnalare più errori contemporaneamente, il che è utile per eseguire rapidamente il debug delle richieste.

Proprietà del percorso

Ogni voce di routes[] è un messaggio ShipmentRoute (REST, gRPC). Ogni ShipmentRoute rappresenta l'assegnazione del percorso a un determinato veicolo a partire dalla richiesta. Le proprietà importanti di ShipmentRoute relative al corrispondente Vehicle 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 suo percorso.
  • vehicleEndTime è l'ora in cui il veicolo dovrebbe terminare il suo percorso.

In una risposta, routes avrà il seguente aspetto:

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

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à importanti di Visit includono:

  • shipmentIndex è l'indice in base zero della spedizione a cui appartiene questa visita nella richiesta corrispondente.
  • isPickup è true quando una visita è un ritiro e false 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 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 alla quantità di carico richiesta per completare la Visit. Le quantità di carico sono negative per le visite di consegna e rappresentano il carico 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 gli spostamenti 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 del viaggio che il veicolo deve compiere 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 rappresenta il tempo di inattività che il veicolo trascorre in attesa prima di poter iniziare la sua Visit successiva. Questo potrebbe essere dovuto al valore di start_time della Visit successiva.
  • totalDuration è la durata totale della transizione, inclusi i tempi di viaggio, attesa, pausa e ritardo.
  • vehicleLoads mappa il tipo di carico con la quantità di carico trasportata dal veicolo durante la 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 fermata per ritiri e consegne 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 di 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 nei Parametri del modello di costi.
  • usedVehicleCount è il numero totale di veicoli utilizzati nella soluzione. I veicoli potrebbero avere percorsi vuoti quando l'ottimizzatore determina che il loro utilizzo non è necessario.
  • skippedMandatoryShipmentCount è il numero di spedizioni saltate che sono "obbligatorie". Una spedizione obbligatoria non specifica un penaltyCost applicato se la spedizione viene saltata. Le spedizioni obbligatorie possono comunque essere saltate se la loro esecuzione non è fattibile in base a vincoli specifici. Scopri di più sui costi in Parametri del modello di costi.

Le metriche aggiuntive vengono segnalate 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 metriche aggregate per tutti gli ShipmentRoute in OptimizeToursResponse. Ogni proprietà ShipmentRoute.metrics contiene metriche per lo ShipmentRoute specifico.

Le proprietà importanti di AggregatedMetrics includono:

  • performedShipmentCount è il numero di spedizioni eseguite dai veicoli lungo l'intero percorso.
  • travelDuration è il tempo totale trascorso dai veicoli in transito durante il completamento dei percorsi.
  • waitDuration è il tempo totale trascorso dai veicoli in attesa durante il completamento dei percorsi.
  • delayDuration è il tempo di ritardo totale per i veicoli. Questo valore è in genere zero, a meno che nella richiesta non vengano utilizzati TransitionAttributes.
  • breakDuration è il tempo totale che i veicoli trascorrono in pausa durante il completamento dei percorsi.
  • visitDuration è il tempo totale trascorso dai veicoli nell'esecuzione delle visite durante il completamento dei percorsi. Si tratta in pratica della somma di tutti i valori di VisitRequest.duration per le VisitRequest corrispondenti a Visit assegnate 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 percorsi.
  • maxLoads mappa i tipi di carico alla quantità massima di carico trasportata dai veicoli in qualsiasi punto dei loro percorsi.

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

Esempio completo

Una risposta di esempio completa per la richiesta effettuata da Crea 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
    }
  }
}