Method: projects.locations.optimizeTours

Invia un OptimizeToursRequest contenente un ShipmentModel e restituisce un OptimizeToursResponse contenente ShipmentRoute, ovvero un insieme di percorsi da eseguire dai veicoli per ridurre al minimo il costo complessivo.

Un modello ShipmentModel è composto principalmente da Shipment che devono essere eseguiti e da Vehicle che possono essere utilizzati per trasportare Shipment. I ShipmentRoute assegnano i Shipment ai Vehicle. Nello specifico, assegnano una serie di Visit a ogni veicolo, dove un Visit corrisponde a un VisitRequest, ovvero un ritiro o una consegna per un Shipment.

L'obiettivo è fornire un'assegnazione di ShipmentRoute a Vehicle in modo da ridurre al minimo il costo totale in cui il costo ha molti componenti definiti in ShipmentModel.

Richiesta HTTP

POST https://routeoptimization.googleapis.com/v1/{parent=projects/*/locations/*}:optimizeTours

L'URL utilizza la sintassi di transcodifica gRPC.

Parametri del percorso

Parametri
parent

string

Obbligatorio. Progetto o località di destinazione per effettuare una chiamata.

Formato: * projects/{project-id} * projects/{project-id}/locations/{location-id}

Se non viene specificata alcuna località, verrà scelta automaticamente una regione.

Corpo della richiesta

Il corpo della richiesta contiene dati con la seguente struttura:

Rappresentazione JSON 
{
  "timeout": string,
  "model": {
    object (ShipmentModel)
  },
  "solvingMode": enum (SolvingMode),
  "searchMode": enum (SearchMode),
  "injectedFirstSolutionRoutes": [
    {
      object (ShipmentRoute)
    }
  ],
  "injectedSolutionConstraint": {
    object (InjectedSolutionConstraint)
  },
  "refreshDetailsRoutes": [
    {
      object (ShipmentRoute)
    }
  ],
  "interpretInjectedSolutionsUsingLabels": boolean,
  "considerRoadTraffic": boolean,
  "populatePolylines": boolean,
  "populateTransitionPolylines": boolean,
  "allowLargeDeadlineDespiteInterruptionRisk": boolean,
  "useGeodesicDistances": boolean,
  "label": string,
  "geodesicMetersPerSecond": number,
  "maxValidationErrors": integer
}
Campi
timeout

string (Duration format)

Se questo timeout è impostato, il server restituisce una risposta prima che sia trascorso il periodo di timeout o che venga raggiunta la scadenza del server per le richieste sincrone, a seconda del caso.

Per le richieste asincrone, il server genererà una soluzione (se possibile) prima del timeout.

Una durata in secondi con un massimo di nove cifre frazionarie, che termina con "s". Esempio: "3.5s".
model

object (ShipmentModel)

Modello di spedizione da risolvere.
solvingMode

enum (SolvingMode)

Per impostazione predefinita, la modalità di risoluzione è DEFAULT_SOLVE (0).
searchMode

enum (SearchMode)

Modalità di ricerca utilizzata per risolvere la richiesta.
injectedFirstSolutionRoutes[]

object (ShipmentRoute)

Guida l'algoritmo di ottimizzazione a trovare una prima soluzione simile a una precedente.

Il modello è vincolato quando viene creata la prima soluzione. Tutte le spedizioni non effettuate su un itinerario vengono implicitamente saltate nella prima soluzione, ma possono essere effettuate in soluzioni successive.

La soluzione deve soddisfare alcuni presupposti di base della validità:

  • per tutte le route, vehicleIndex deve essere nel raggio d'azione e non essere duplicato.
  • Per tutte le visite, shipmentIndex e visitRequestIndex devono essere compresi nell'intervallo.
  • È possibile fare riferimento a una spedizione in un solo percorso.
  • il ritiro di una spedizione con ritiro/consegna deve essere effettuato prima della consegna.
  • Non è possibile effettuare più di un'alternativa per il ritiro o la consegna di una spedizione.
  • per tutti i percorsi, i tempi sono in aumento (ad es. vehicleStartTime <= visits[0].start_time <= visits[1].start_time ... <= vehicleEndTime).
  • una spedizione può essere eseguita solo su un veicolo consentito. Un veicolo è consentito se Shipment.allowed_vehicle_indices è vuoto o se il relativo vehicleIndex è incluso in Shipment.allowed_vehicle_indices.

Se la soluzione iniettata non è fattibile, non viene necessariamente restituito un errore di convalida, ma potrebbe essere restituito un errore che indica l'impossibilità di applicazione.
injectedSolutionConstraint

object (InjectedSolutionConstraint)

Limitare l'algoritmo di ottimizzazione a trovare una soluzione finale simile a una soluzione precedente. Questa opzione, ad esempio, può essere utilizzata per bloccare parti di percorsi che sono già stati completati o che devono essere completati ma non devono essere modificati.

Se la soluzione inserita non è fattibile, non viene necessariamente restituito un errore di convalida e potrebbe invece essere restituito un errore che indica l'inattuabilità.
refreshDetailsRoutes[]

object (ShipmentRoute)

Se non è vuoto, i percorsi specificati verranno aggiornati, senza modificare la sequenza di visite o i tempi di percorrenza sottostanti: verranno aggiornati solo gli altri dettagli. Questo non risolve il modello.

A partire da novembre 2020, vengono compilati solo i polilinei dei percorsi non vuoti e populatePolylines deve essere impostato su true.

I campi routePolyline dei percorsi passati potrebbero non corrispondere al percorso transitions.

Questo campo non deve essere utilizzato insieme a injectedFirstSolutionRoutes o injectedSolutionConstraint.

Shipment.ignore e Vehicle.ignore non hanno alcun effetto sul comportamento. I polilinee vengono comunque compilati tra tutte le visite in tutti i percorsi non vuoti, indipendentemente dal fatto che le spedizioni o i veicoli correlati vengano ignorati.
interpretInjectedSolutionsUsingLabels

boolean

Se il valore è vero:

Questa interpretazione si applica ai campi injectedFirstSolutionRoutes, injectedSolutionConstraint e refreshDetailsRoutes. Può essere utilizzato quando gli indici di spedizione o veicolo nella richiesta sono cambiati dalla creazione della soluzione, ad esempio perché le spedizioni o i veicoli sono stati rimossi dalla richiesta o aggiunti.

Se true, le etichette nelle seguenti categorie devono apparire al massimo una volta nella rispettiva categoria:

Se un vehicleLabel nella soluzione iniettata non corrisponde a un veicolo richiesto, il percorso corrispondente viene rimosso dalla soluzione insieme alle relative visite. Se un shipmentLabel nella soluzione iniettata non corrisponde a una spedizione di richieste, la visita corrispondente viene rimossa dalla soluzione. Se un SkippedShipment.label nella soluzione iniettata non corrisponde a una spedizione di richiesta, il SkippedShipment viene rimosso dalla soluzione.

La rimozione di visite ai percorsi o di interi percorsi da una soluzione iniettata può influire sui vincoli impliciti, il che può comportare la modifica della soluzione, errori di convalida o l'impossibilità di applicazione.

NOTA: l'utente che chiama deve assicurarsi che ogni Vehicle.label (risp. Shipment.label) identifica in modo univoco un'entità veicolo (risp. spedizione) utilizzata nelle due richieste pertinenti: la richiesta precedente che ha prodotto il OptimizeToursResponse utilizzato nella soluzione iniettata e la richiesta attuale che include la soluzione iniettata. I controlli di univocità descritti sopra non sono sufficienti a garantire questo requisito.
considerRoadTraffic

boolean

Considera la stima del traffico nel calcolo dei campi ShipmentRoute Transition.travel_duration, Visit.start_time e vehicleEndTime, nell'impostazione del campo ShipmentRoute.has_traffic_infeasibilities e nel calcolo del campo OptimizeToursResponse.total_cost.
populatePolylines

boolean

Se impostato su true, le polilinee verranno compilate nelle risposte ShipmentRoute.
populateTransitionPolylines

boolean

Se impostato su true, le polilinee e i token di route verranno compilati nella risposta ShipmentRoute.transitions.
allowLargeDeadlineDespiteInterruptionRisk

boolean

Se questo valore è impostato, la richiesta può avere una scadenza (vedi https://grpc.io/blog/deadlines) fino a 60 minuti. In caso contrario, la scadenza massima è di soli 30 minuti. Tieni presente che le richieste a lungo termine presentano un rischio di interruzione notevolmente maggiore (ma comunque ridotto).
useGeodesicDistances

boolean

Se true, le distanze di viaggio verranno calcolate utilizzando le distanze geodetiche anziché quelle di Google Maps e i tempi di viaggio verranno calcolati utilizzando le distanze geodetiche con una velocità definita da geodesicMetersPerSecond.
label

string

L'etichetta che può essere utilizzata per identificare questa richiesta, riportata in OptimizeToursResponse.request_label.
geodesicMetersPerSecond

number

Se useGeodesicDistances è impostato su true, è necessario impostare questo campo che definisce la velocità applicata al calcolo dei tempi di percorrenza. Il suo valore deve essere di almeno 1,0 metri/secondi.
maxValidationErrors

integer

Tronca il numero di errori di convalida restituiti. Questi errori sono in genere associati al payload dell'errore INVALID_ARGUMENT come dettaglio dell'errore BadRequest (https://cloud.google.com/apis/design/errors#error_details), a meno che solvingMode=VALIDATE_ONLY: consulta il campo OptimizeToursResponse.validation_errors. Il valore predefinito è 100 ed è limitato a 10.000.

Corpo della risposta

In caso di esito positivo, il corpo della risposta contiene un'istanza di OptimizeToursResponse.

Ambiti di autorizzazione

Richiede il seguente ambito OAuth:

  • https://www.googleapis.com/auth/cloud-platform

Autorizzazioni IAM

Richiede la seguente autorizzazione IAM per la risorsa parent:

  • routeoptimization.locations.use

Per ulteriori informazioni, consulta la documentazione di IAM.