Method: providers.vehicles.search

Retorna uma lista de veículos que correspondem às opções de solicitação.

Solicitação HTTP

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

O URL usa a sintaxe de transcodificação gRPC.

Parâmetros de caminho

Parâmetros
parent

string

Obrigatório. Precisa estar no formato providers/{provider}. O provedor precisa ser o ID do projeto (por exemplo, sample-cloud-project) do projeto do Google Cloud de que a conta de serviço que está fazendo a chamada faz parte.

Corpo da solicitação

O corpo da solicitação contém dados com a seguinte estrutura:

Representação 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
}
Campos
header

object (RequestHeader)

O cabeçalho de solicitação padrão do Fleet Engine.

pickupPoint

object (TerminalLocation)

Obrigatório. O ponto de encontro próximo ao qual pesquisar.

dropoffPoint

object (TerminalLocation)

O local de entrega pretendido do cliente. O campo é obrigatório se tripTypes contiver TripType.SHARED.

pickupRadiusMeters

integer

Obrigatório. Define o raio de pesquisa do veículo ao redor do ponto de embarque. Somente veículos dentro do raio de pesquisa serão retornados. O valor precisa estar entre 400 e 10.000 metros (inclusive).

count

integer

Obrigatório. Especifica o número máximo de veículos a serem retornados. O valor precisa estar entre 1 e 50 (inclusive).

minimumCapacity

integer

Obrigatório. Especifica o número de passageiros considerados para uma viagem. O valor precisa ser maior ou igual a um. O driver não é considerado no valor da capacidade.

tripTypes[]

enum (TripType)

Obrigatório. Representa o tipo de viagem proposta. Precisa incluir exatamente um tipo. A política UNKNOWN_TRIP_TYPE não é permitida. Restringe a pesquisa apenas aos veículos compatíveis com esse tipo de viagem.

maximumStaleness

string (Duration format)

Restringe a pesquisa apenas aos veículos que enviaram atualizações de localização ao Fleet Engine no período especificado. Veículos parados que ainda transmitam suas localizações não são considerados desatualizados. Se esse campo não for definido, o servidor usará cinco minutos como valor padrão.

Duração em segundos com até nove dígitos fracionários, terminando em "s". Exemplo: "3.5s".

vehicleTypes[]

object (VehicleType)

Obrigatório. Restringe a pesquisa a veículos com um dos tipos especificados. É necessário especificar pelo menos um tipo de veículo. VehicleTypes com uma categoria de UNKNOWN não são permitidos.

requiredAttributes[]

object (VehicleAttribute)

Os autores da chamada podem formar operações lógicas complexas usando qualquer combinação dos campos requiredAttributes, requiredOneOfAttributes e requiredOneOfAttributeSets.

requiredAttributes é uma lista; O requiredOneOfAttributes usa uma mensagem que permite criar uma lista de listas. Em combinação, os dois campos permitem a composição desta expressão:

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

Restringe a pesquisa apenas aos veículos com os atributos especificados. Esse campo é uma operação de conjunção/E. São permitidos no máximo 50 requiredAttributes. Esse valor corresponde ao número máximo de atributos permitidos em um veículo.

requiredOneOfAttributes[]

object (VehicleAttributeList)

Restringe a pesquisa apenas aos veículos com pelo menos um dos atributos especificados em cada VehicleAttributeList. Em cada lista, um veículo precisa corresponder a pelo menos um dos atributos. Esse campo é uma operação de disjunção/E inclusiva em cada VehicleAttributeList e uma operação de conjunção/E na coleção de VehicleAttributeList.

requiredOneOfAttributeSets[]

object (VehicleAttributeList)

requiredOneOfAttributeSets oferece mais funcionalidades.

Semelhante a requiredOneOfAttributes, requiredOneOfAttributeSets usa uma mensagem que permite uma lista de listas, permitindo expressões como esta:

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

Restringe a pesquisa apenas aos veículos com todos os atributos em uma VehicleAttributeList. Em cada lista, um veículo precisa corresponder a todos os atributos. Esse campo é uma operação de conjunção/E em cada VehicleAttributeList e uma operação inclusiva de disjunção/OU na coleção de VehicleAttributeList.

orderBy

enum (VehicleMatchOrder)

Obrigatório. Especifica o critério de ordenação desejado para os resultados.

includeBackToBack

boolean

Indica se veículos com uma única viagem ativa estão qualificados para essa pesquisa. Esse campo só é usado quando currentTripsPresent não é especificado. Quando currentTripsPresent não é especificado e esse campo é false, os veículos com viagens atribuídas são excluídos dos resultados da pesquisa. Quando currentTripsPresent não é especificado e esse campo é true, os resultados da pesquisa podem incluir veículos com uma viagem ativa com status ENROUTE_TO_DROPOFF. Quando currentTripsPresent é especificado, este campo não pode ser definido como verdadeiro.

O valor padrão é false.

tripId

string

Indica a viagem associada a este SearchVehicleRequest.

currentTripsPresent

enum (CurrentTripsPresent)

Indica se veículos com viagens ativas estão qualificados para essa pesquisa. Precisa ser definido como algo diferente de CURRENT_TRIPS_PRESENT_UNSPECIFIED se tripType incluir SHARED.

filter

string

Opcional. Uma consulta de filtro para aplicar ao pesquisar veículos. Consulte http://aip.dev/160 para ver exemplos de sintaxe de filtro.

Esse campo foi criado para substituir os campos requiredAttributes, requiredOneOfAttributes e required_one_of_attributes_sets. Se um valor não vazio for especificado aqui, os seguintes campos precisarão estar vazios: requiredAttributes, requiredOneOfAttributes e required_one_of_attributes_sets.

Esse filtro funciona como uma cláusula AND com outras restrições, como minimumCapacity ou vehicleTypes.

As únicas consultas aceitas são nos atributos do veículo (por exemplo, attributes.<key> = <value> ou attributes.<key1> = <value1> AND attributes.<key2> = <value2>). O número máximo de restrições permitido em uma consulta de filtro é 50.

Além disso, todos os atributos são armazenados como strings. Portanto, as únicas comparações compatíveis com os atributos são aquelas de strings. Para fazer uma comparação com valores numéricos ou booleanos, os valores precisam estar explicitamente entre aspas para serem tratados como strings (por exemplo, attributes.<key> = "10" ou attributes.<key> = "true").

Corpo da resposta

Mensagem de resposta de vehicles.search.

Se bem-sucedido, o corpo da resposta incluirá dados com a estrutura a seguir:

Representação JSON
{
  "matches": [
    {
      object (VehicleMatch)
    }
  ]
}
Campos
matches[]

object (VehicleMatch)

Lista de veículos que correspondem aos critérios SearchVehiclesRequest, ordenados de acordo com o campo SearchVehiclesRequest.order_by.

VehicleAttributeList

Um tipo de dados de lista de listas para atributos do veículo.

Representação JSON
{
  "attributes": [
    {
      object (VehicleAttribute)
    }
  ]
}
Campos
attributes[]

object (VehicleAttribute)

Uma lista de atributos desta coleção.

VehicleMatchOrder

Especifica a ordem das correspondências do veículo na resposta.

Enums
UNKNOWN_VEHICLE_MATCH_ORDER Padrão, usado para veículo não especificado ou não reconhecido corresponde ao pedido.
PICKUP_POINT_ETA Ordem crescente por tempo de percurso do veículo até o ponto de embarque.
PICKUP_POINT_DISTANCE Ordem crescente por distância de carro do veículo até o ponto de embarque.
DROPOFF_POINT_ETA Ordem crescente por tempo de percurso do veículo até o ponto de entrega. Esse pedido só pode ser usado se o ponto de entrega for especificado na solicitação.
PICKUP_POINT_STRAIGHT_DISTANCE Pedido crescente por distância em linha reta do último local relatado do veículo até o ponto de embarque.
COST Ordem crescente pelo custo de correspondência configurado. O custo da correspondência é definido como um cálculo ponderado entre a distância em linha reta e o ETA. Os pesos são definidos com valores padrão e podem ser modificados de acordo com o cliente. Entre em contato com o Suporte do Google se for preciso modificar os pesos no seu projeto.

CurrentTripsPresent

Especifica os tipos de restrições nas viagens atuais de um veículo.

Enums
CURRENT_TRIPS_PRESENT_UNSPECIFIED A disponibilidade de veículos com as viagens é regida pelo campo includeBackToBack.
NONE Veículos sem viagens podem aparecer nos resultados da pesquisa. Quando esse valor é usado, includeBackToBack não pode ser true.
ANY Veículos com, no máximo, 5 viagens atuais e 10 waypoints são incluídos nos resultados da pesquisa. Quando esse valor é usado, includeBackToBack não pode ser true.

VehicleMatch

Contém o veículo e as estimativas relacionadas para um veículo que corresponde aos pontos de viagens ativas do veículo SearchVehiclesRequest.

Representação 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)
}
Campos
vehicle

object (Vehicle)

Obrigatório. Um veículo que corresponde à solicitação.

vehiclePickupEta

string (Timestamp format)

O HEC de carro do veículo até o ponto de embarque especificado na solicitação. Um valor vazio indica uma falha no cálculo do HEC do veículo. Se SearchVehiclesRequest.include_back_to_back era true e este veículo tem uma viagem ativa, vehiclePickupEta vai incluir o tempo necessário para concluir a viagem ativa atual.

Um carimbo de data/hora no formato RFC3339 UTC "Zulu", com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".

vehiclePickupDistanceMeters

integer

A distância da localização atual do Veículo até o ponto de embarque especificado na solicitação, incluindo os pontos de embarque ou desembarque intermediários de viagens existentes. Essa distância compreende a distância de percurso (trajeto) calculada mais a distância em linha reta entre o ponto final da navegação e o ponto de embarque solicitado. A distância entre o ponto de destino da navegação e o ponto de embarque solicitado normalmente é pequena. Um valor vazio indica um erro no cálculo da distância.

vehiclePickupStraightLineDistanceMeters

integer

Obrigatório. A distância em linha reta entre o veículo e o ponto de embarque especificado na solicitação.

vehicleDropoffEta

string (Timestamp format)

O HEC completo do veículo até o ponto de desembarque especificado na solicitação. O ETA inclui parada em qualquer waypoint antes do dropoffPoint especificado na solicitação. O valor só é preenchido quando um ponto de desembarque é especificado na solicitação. Um valor vazio indica um erro no cálculo do HEC.

Um carimbo de data/hora no formato RFC3339 UTC "Zulu", com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".

vehiclePickupToDropoffDistanceMeters

integer

A distância de carro (em metros) do veículo entre o ponto de embarque e o ponto de desembarque especificado na solicitação. A distância é apenas entre os dois pontos e não inclui a localização do veículo ou qualquer outro ponto que precise ser visitado antes da chegada do veículo ao ponto de embarque ou desembarque. O valor só será preenchido quando dropoffPoint for especificado na solicitação. Um valor vazio indica uma falha no cálculo da distância do ponto de embarque ao desembarque especificado na solicitação.

tripType

enum (TripType)

Obrigatório. O tipo de viagem da solicitação que foi usada para calcular o HEC até o ponto de embarque.

vehicleTripsWaypoints[]

object (Waypoint)

A lista ordenada de waypoints usados para calcular o HEC. A lista inclui a localização e os pontos de embarque das viagens ativas do veículo e fornecidos na solicitação. Uma lista vazia indica uma falha no cálculo do HEC do veículo.

vehicleMatchType

enum (VehicleMatchType)

Tipo de correspondência do veículo.

requestedOrderedBy

enum (VehicleMatchOrder)

A ordem solicitada para classificar as correspondências do veículo.

orderedBy

enum (VehicleMatchOrder)

O pedido real usado para este veículo. Normalmente, isso corresponde a "orderBy" da solicitação. No entanto, em determinadas circunstâncias, como um erro interno do servidor, outro método pode ser usado (como PICKUP_POINT_STRAIGHT_DISTANCE).

Ponto de referência

Descreve pontos intermediários ao longo de um trajeto para um VehicleMatch em um SearchVehiclesResponse. Esse conceito é representado como TripWaypoint em todos os outros endpoints.

Representação JSON
{
  "latLng": {
    object (LatLng)
  },
  "eta": string
}
Campos
latLng

object (LatLng)

O local deste waypoint.

eta

string (Timestamp format)

O tempo estimado que o veículo chegará a este waypoint.

Um carimbo de data/hora no formato RFC3339 UTC "Zulu", com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".

VehicleMatchType

Tipo de correspondência de veículo.

Enums
UNKNOWN Tipo de correspondência de veículo desconhecido
EXCLUSIVE No momento, o veículo não tem uma viagem atribuída e pode prosseguir até o ponto de embarque.
BACK_TO_BACK O veículo está atribuído a uma viagem, mas pode prosseguir até o ponto de embarque depois de concluir a viagem em andamento. Os cálculos de HEC e distância consideram a viagem atual.
CARPOOL O veículo tem capacidade suficiente para uma viagem compartilhada.
CARPOOL_BACK_TO_BACK O veículo vai concluir a viagem atual e ativa antes de prosseguir para o ponto de embarque. Os cálculos de HEC e distância consideram a viagem atual.