Method: providers.vehicles.search

Restituisce un elenco di veicoli che corrispondono alle opzioni di richiesta.

Richiesta HTTP

POST https://fleetengine.googleapis.com/v1/{parent=providers/*}/vehicles:search

L'URL utilizza la sintassi di transcodifica gRPC.

Parametri del percorso

Parametri
parent

string

Obbligatorio. Deve essere nel formato providers/{provider}. Il provider deve essere l'ID progetto (ad esempio sample-cloud-project) del progetto Google Cloud di cui l'account di servizio che effettua questa chiamata è membro.

Corpo della richiesta

Il corpo della richiesta contiene dati con la seguente struttura:

Rappresentazione JSON 
{
  "header": {
    object (RequestHeader)
  },
  "pickupPoint": {
    object (TerminalLocation)
  },
  "dropoffPoint": {
    object (TerminalLocation)
  },
  "pickupRadiusMeters": integer,
  "count": integer,
  "minimumCapacity": integer,
  "tripTypes": [
    enum (TripType)
  ],
  "maximumStaleness": string,
  "vehicleTypes": [
    {
      object (VehicleType)
    }
  ],
  "requiredAttributes": [
    {
      object (VehicleAttribute)
    }
  ],
  "requiredOneOfAttributes": [
    {
      object (VehicleAttributeList)
    }
  ],
  "requiredOneOfAttributeSets": [
    {
      object (VehicleAttributeList)
    }
  ],
  "orderBy": enum (VehicleMatchOrder),
  "includeBackToBack": boolean,
  "tripId": string,
  "currentTripsPresent": enum (CurrentTripsPresent),
  "filter": string
}
Campi
header

object (RequestHeader)

L'intestazione della richiesta di Fleet Engine standard.
pickupPoint

object (TerminalLocation)

Obbligatorio. Il punto di ritiro nelle vicinanze in cui effettuare la ricerca.
dropoffPoint

object (TerminalLocation)

La località di consegna prevista dal cliente. Il campo è obbligatorio se tripTypes contiene TripType.SHARED.
pickupRadiusMeters

integer

Obbligatorio. Definisce il raggio di ricerca del veicolo intorno al punto di ritiro. Verranno restituiti solo i veicoli all'interno del raggio di ricerca. Il valore deve essere compreso tra 400 e 10.000 metri (inclusi).
count

integer

Obbligatorio. Specifica il numero massimo di veicoli da restituire. Il valore deve essere compreso tra 1 e 50 (incluso).
minimumCapacity

integer

Obbligatorio. Specifica il numero di passeggeri presi in considerazione per un viaggio. Il valore deve essere maggiore o uguale a 1. Il conducente non viene considerato nel valore della capacità.
tripTypes[]

enum (TripType)

Obbligatorio. Rappresenta il tipo di viaggio proposto. Deve includere esattamente un tipo. Non consentito: UNKNOWN_TRIP_TYPE. Restringe la ricerca solo ai veicoli in grado di supportare quel tipo di viaggio.
maximumStaleness

string (Duration format)

Limita la ricerca ai veicoli che hanno inviato aggiornamenti di posizione a Fleet Engine entro il periodo di tempo specificato. I veicoli fissi che trasmettono ancora la loro posizione non sono considerati inattivi. Se questo campo non è impostato, il server utilizza cinque minuti come valore predefinito.

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

object (VehicleType)

Obbligatorio. Limita la ricerca ai veicoli con uno dei tipi specificati. È necessario specificare almeno un tipo di veicolo. I tipi di veicoli con una categoria UNKNOWN non sono consentiti.
requiredAttributes[]

object (VehicleAttribute)

I chiamanti possono formare operazioni logiche complesse utilizzando qualsiasi combinazione dei campi requiredAttributes, requiredOneOfAttributes e requiredOneOfAttributeSets.

requiredAttributes è un elenco; requiredOneOfAttributes utilizza un messaggio che consente un elenco di elenchi. La combinazione dei due campi consente di comporre questa espressione:

(requiredAttributes[0] AND requiredAttributes[1] AND ...)
AND
(requiredOneOfAttributes[0][0] OR requiredOneOfAttributes[0][1] OR
...)
AND
(requiredOneOfAttributes[1][0] OR requiredOneOfAttributes[1][1] OR
...)

Limita la ricerca ai veicoli con gli attributi specificati. Questo campo è un'operazione congiunzione/AND. È consentito un massimo di 50 attributi obbligatori. Corrisponde al numero massimo di attributi consentiti per un veicolo.
requiredOneOfAttributes[]

object (VehicleAttributeList)

Limita la ricerca ai soli veicoli con almeno uno degli attributi specificati in ogni VehicleAttributeList. All'interno di ogni elenco, un veicolo deve corrispondere ad almeno uno degli attributi. Questo campo è un'operazione di disgiunzione inclusiva/OR in ogni VehicleAttributeList e un'operazione di congiunzione/AND nella raccolta di VehicleAttributeList.
requiredOneOfAttributeSets[]

object (VehicleAttributeList)

requiredOneOfAttributeSets fornisce funzionalità aggiuntive.

Analogamente a requiredOneOfAttributes, requiredOneOfAttributeSets utilizza un messaggio che consente un elenco di elenchi, consentendo espressioni come questa:

(requiredAttributes[0] AND requiredAttributes[1] AND ...)
AND
(
  (requiredOneOfAttributeSets[0][0] AND
  requiredOneOfAttributeSets[0][1] AND
  ...)
  OR
  (requiredOneOfAttributeSets[1][0] AND
  requiredOneOfAttributeSets[1][1] AND
  ...)
)

Limita la ricerca solo ai veicoli con tutti gli attributi in un VehicleAttributeList. All'interno di ogni elenco, un veicolo deve corrispondere a tutti gli attributi. Questo campo è un'operazione di congiunzione/AND in ogni operazione VehicleAttributeList e di disgiunzione/OR incluse nella raccolta di VehicleAttributeList.
orderBy

enum (VehicleMatchOrder)

Obbligatorio. Specifica il criterio di ordinamento desiderato per i risultati.
includeBackToBack

boolean

Indica se i veicoli con una singola corsa attiva sono idonei per questa ricerca. Questo campo viene utilizzato solo quando currentTripsPresent non è specificato. Se il criterio currentTripsPresent non è specificato e questo campo è false, i veicoli con corse assegnate vengono esclusi dai risultati di ricerca. Quando currentTripsPresent non è specificato e questo campo è true, i risultati di ricerca possono includere veicoli con un viaggio attivo con stato ENROUTE_TO_DROPOFF. Quando viene specificato currentTripsPresent, questo campo non può essere impostato su true.

Il valore predefinito è false.
tripId

string

Indica il viaggio associato a SearchVehicleRequest.
currentTripsPresent

enum (CurrentTripsPresent)

Indica se i veicoli con corse attive sono idonei per questa ricerca. Deve essere impostato su un valore diverso da CURRENT_TRIPS_PRESENT_UNSPECIFIED se tripType include SHARED.
filter

string

(Facoltativo) Una query filtro da applicare durante la ricerca di veicoli. Visita la pagina http://aip.dev/160 per esempi di sintassi dei filtri.

Questo campo è progettato per sostituire i campi requiredAttributes, requiredOneOfAttributes e required_one_of_attributes_sets. Se qui viene specificato un valore non vuoto, i seguenti campi devono essere vuoti: requiredAttributes, requiredOneOfAttributes e required_one_of_attributes_sets.

Questo filtro funziona come una clausola AND con altri vincoli, ad esempio minimumCapacity o vehicleTypes.

Tieni presente che le uniche query supportate riguardano gli attributi del veicolo (ad es. attributes.<key> = <value> o attributes.<key1> = <value1> AND attributes.<key2> = <value2>). Il numero massimo di limitazioni consentite in una query di filtro è 50.

Inoltre, tutti gli attributi vengono memorizzati come stringhe, pertanto gli unici confronti supportati con gli attributi sono quelli di stringhe. Per eseguire il confronto con valori numerici o booleani, i valori devono essere tra virgolette in modo esplicito per essere trattati come stringhe (ad esempio, attributes.<key> = "10" o attributes.<key> = "true").

Corpo della risposta

Messaggio di risposta vehicles.search.

In caso di esito positivo, il corpo della risposta contiene dati con la seguente struttura:

Rappresentazione JSON 
{
  "matches": [
    {
      object (VehicleMatch)
    }
  ]
}
Campi
matches[]

object (VehicleMatch)

Elenco di veicoli che soddisfano i criteri SearchVehiclesRequest, ordinati in base al campo SearchVehiclesRequest.order_by.

VehicleAttributeList

Un tipo di dati elenco di elenchi per gli attributi del veicolo.

Rappresentazione JSON 
{
  "attributes": [
    {
      object (VehicleAttribute)
    }
  ]
}
Campi
attributes[]

object (VehicleAttribute)

Un elenco di attributi in questa raccolta.

VehicleMatchOrder

Specifica l'ordine delle corrispondenze del veicolo nella risposta.

Enum
UNKNOWN_VEHICLE_MATCH_ORDER Valore predefinito, utilizzato per ordini di corrispondenze dei veicoli non specificati o non riconosciuti.
PICKUP_POINT_ETA Ordine crescente in base al tempo di guida del veicolo fino al punto di ritiro.
PICKUP_POINT_DISTANCE In ordine crescente in base alla distanza in auto del veicolo dal punto di ritiro.
DROPOFF_POINT_ETA Ordine crescente in base al tempo di guida del veicolo fino al punto di consegna. Questo ordine può essere utilizzato solo se il punto di consegna è specificato nella richiesta.
PICKUP_POINT_STRAIGHT_DISTANCE In ordine crescente in base alla distanza in linea retta dall'ultima posizione segnalata del veicolo al punto di ritiro.
COST Ordine crescente in base al costo di corrispondenza configurato. Il costo della corrispondenza è definito come un calcolo ponderato tra la distanza in linea retta e l'orario di arrivo stimato. I pesi vengono impostati con valori predefiniti e possono essere modificati in base al cliente. Contatta l'Assistenza Google se devi modificare questi pesi per il tuo progetto.

CurrentTripsPresent

Specifica i tipi di limitazioni per le corse in corso di un veicolo.

Enum
CURRENT_TRIPS_PRESENT_UNSPECIFIED La disponibilità dei veicoli con corse presenti è regolata dal campo includeBackToBack.
NONE I veicoli senza corse possono essere visualizzati nei risultati di ricerca. Quando viene utilizzato questo valore, includeBackToBack non può essere true.
ANY Nei risultati di ricerca sono inclusi i veicoli con al massimo 5 corse in corso e 10 waypoint. Quando viene utilizzato questo valore, includeBackToBack non può essere true.

VehicleMatch

Contiene il veicolo e le relative stime per un veicolo che corrisponde ai punti delle corse attive per il veicolo SearchVehiclesRequest.

Rappresentazione JSON 
{
  "vehicle": {
    object (Vehicle)
  },
  "vehiclePickupEta": string,
  "vehiclePickupDistanceMeters": integer,
  "vehiclePickupStraightLineDistanceMeters": integer,
  "vehicleDropoffEta": string,
  "vehiclePickupToDropoffDistanceMeters": integer,
  "tripType": enum (TripType),
  "vehicleTripsWaypoints": [
    {
      object (Waypoint)
    }
  ],
  "vehicleMatchType": enum (VehicleMatchType),
  "requestedOrderedBy": enum (VehicleMatchOrder),
  "orderedBy": enum (VehicleMatchOrder)
}
Campi
vehicle

object (Vehicle)

Obbligatorio. Un veicolo che corrisponde alla richiesta.
vehiclePickupEta

string (Timestamp format)

L'orario di arrivo stimato del veicolo al punto di ritiro specificato nella richiesta. Un valore vuoto indica un errore nel calcolo dell'orario di arrivo stimato per il veicolo. Se SearchVehiclesRequest.include_back_to_back era true e questo veicolo ha una corsa attiva, vehiclePickupEta include il tempo necessario per completare la corsa attiva corrente.

Un timestamp nel formato "Zulu" RFC3339 UTC, con risoluzione in nanosecondi e fino a nove cifre frazionarie. Esempi: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".
vehiclePickupDistanceMeters

integer

La distanza dalla posizione attuale del veicolo al punto di ritiro specificato nella richiesta, inclusi eventuali punti di ritiro o di consegna intermedi per i viaggi esistenti. Questa distanza comprende la distanza calcolata in auto (percorso), più la distanza in linea retta tra il punto di arrivo della navigazione e il punto di ritiro richiesto. In genere, la distanza tra il punto di arrivo della navigazione e il punto di prelievo richiesto è ridotta. Un valore vuoto indica un errore nel calcolo della distanza.
vehiclePickupStraightLineDistanceMeters

integer

Obbligatorio. La distanza in linea retta tra il veicolo e il punto di ritiro specificato nella richiesta.
vehicleDropoffEta

string (Timestamp format)

L'orario di arrivo stimato del veicolo al punto di consegna specificato nella richiesta. L'orario di arrivo stimato include la sosta in qualsiasi tappa prima del giorno dropoffPoint specificato nella richiesta. Il valore verrà inserito solo quando nella richiesta viene specificato un punto di consegna. Un valore vuoto indica un errore nel calcolo dell'orario di arrivo stimato.

Un timestamp nel formato "Zulu" RFC3339 UTC, con risoluzione in nanosecondi e fino a nove cifre frazionarie. Esempi: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".
vehiclePickupToDropoffDistanceMeters

integer

La distanza di guida (in metri) del veicolo dal punto di prelievo al punto di consegna specificato nella richiesta. La distanza si trova solo tra i due punti e non include la posizione del veicolo o qualsiasi altro punto che deve essere visitato prima che il veicolo visiti il punto di prelievo o scarico. Il valore verrà inserito solo quando nella richiesta viene specificato un dropoffPoint. Un valore vuoto indica un errore nel calcolo della distanza dal punto di ritiro a quello di consegna specificato nella richiesta.
tripType

enum (TripType)

Obbligatorio. Il tipo di viaggio della richiesta utilizzato per calcolare l'orario di arrivo stimato fino al punto di partenza.
vehicleTripsWaypoints[]

object (Waypoint)

L'elenco ordinato di tappe utilizzate per calcolare l'orario di arrivo stimato. L'elenco include la posizione del veicolo, i punti di ritiro dei viaggi attivi per il veicolo e i punti di ritiro forniti nella richiesta. Un elenco vuoto indica un errore nel calcolo dell'orario di arrivo stimato del veicolo.
vehicleMatchType

enum (VehicleMatchType)

Tipo di corrispondenza del veicolo.
requestedOrderedBy

enum (VehicleMatchOrder)

L'ordine richiesto per ordinare le corrispondenze dei veicoli.
orderedBy

enum (VehicleMatchOrder)

L'ordine effettivo utilizzato per questo veicolo. Normalmente corrisponde al campo "orderBy" della richiesta. Tuttavia, in determinate circostanze, ad esempio in caso di errore interno del server, è possibile utilizzare un metodo diverso (ad esempio PICKUP_POINT_STRAIGHT_DISTANCE).

Waypoint

Descrive i punti intermedi lungo un percorso per un VehicleMatch in un SearchVehiclesResponse. Questo concetto è rappresentato come TripWaypoint in tutti gli altri endpoint.

Rappresentazione JSON 
{
  "latLng": {
    object (LatLng)
  },
  "eta": string
}
Campi
latLng

object (LatLng)

La posizione di questo waypoint.
eta

string (Timestamp format)

L'ora stimata in cui il veicolo arriverà a questo waypoint.

Un timestamp nel formato "Zulu" RFC3339 UTC, con risoluzione in nanosecondi e fino a nove cifre frazionarie. Esempi: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".

VehicleMatchType

Tipo di veicolo corrispondente.

Enum
UNKNOWN Tipo di corrispondenza veicolo sconosciuto
EXCLUSIVE Al momento al veicolo non è stato assegnato alcun viaggio e può procedere al punto di ritiro.
BACK_TO_BACK Al momento il veicolo è assegnato a una corsa, ma può procedere al punto di ritiro dopo aver completato la corsa in corso. I calcoli di ETA e distanza tengono conto del viaggio esistente.
CARPOOL Il veicolo ha una capacità sufficiente per una corsa condivisa.
CARPOOL_BACK_TO_BACK Il veicolo terminerà il percorso attuale e attivo prima di procedere verso il punto di prelievo. I calcoli di orario di arrivo stimato e distanza tengono conto della corsa esistente.