A API Fleet Engine On-demand Rides and Deliveries permite gerenciar viagens e o estado do veículo para os aplicativos em andamento de viagem e pedido. Ele processa transações entre o SDK do Driver, o SDK do consumidor e seu de back-end, que pode se comunicar com o Fleet Engine gRPC ou chamadas REST.
Pré-requisitos
Para desenvolvimento, instale o pacote do SDK (gcloud) e são autenticados seu projeto.
shell
gcloud auth login
Você verá uma mensagem de sucesso como esta:
You are now logged in as [my-user@example.com].
Your current project is [project-id]. You ...
Verifique se as APIs On Demand Rides and Deliveries Solution Fleet Engine estão configuradas corretamente.
shell
gcloud --project=project-id services enable fleetengine.googleapis.com
Se esse comando resultar em um erro, entre em contato com o administrador do projeto e ao representante do Suporte do Google para ter acesso.
Logging
O Fleet Engine pode gravar mensagens de registro sobre as chamadas de API recebidas aos registros do Google Cloud Platform. Consulte a documentação do Cloud Logging para visão geral de como ler e analisar registros.
A geração de registros pode não estar ativada por padrão para projetos criados antes da 10 de fevereiro de 2022. Consulte a documentação de geração de registros para mais detalhes.
Bibliotecas de cliente
Publicamos bibliotecas em várias linguagens de programação comuns. Esses ajudam a fornecer uma melhor experiência de desenvolvedor em relação a REST ou gRPC bruto. Para instruções sobre como receber bibliotecas de cliente para seu aplicativo de servidor, ver Bibliotecas de cliente.
Os exemplos de Java nesta documentação pressupõem familiaridade com gRPC.
Autenticação e autorização
Você pode configurar os recursos fornecidos pelo andamento da viagem e do pedido por meio do no console do Google Cloud. Essas APIs e SDKs requerem o uso de JSON Web Tokens que foram assinados usando contas de serviço criadas a partir do Google Cloud.
Configuração do projeto do Cloud
Para configurar seu projeto na nuvem, primeiro crie seu projeto e depois criar contas de serviço.
Para criar seu projeto do Google Cloud:
- Criar um projeto do Google Cloud usando o console do Google Cloud.
- Usando o painel de APIs e serviços, ative a API Local Rides and Deliveries.
As contas de serviço são associadas a um ou mais papéis. Eles são usados para criar Tokens JSON Web que concedem diferentes conjuntos de permissões, dependendo do papéis de segurança na nuvem. Normalmente, para reduzir a possibilidade de abuso, você pode criar vários contas de serviço, cada uma com o conjunto mínimo de papéis necessários.
O andamento da viagem e do pedido usa os seguintes papéis:
Papel | Descrição |
---|---|
Usuário do SDK de consumidor do Fleet Engine
roles/fleetengine.consumerSdkUser |
Concede permissão para pesquisar veículos e recuperar informações sobre veículos e viagens. Tokens criados por uma conta de serviço com este normalmente são usadas nos seus dispositivos móveis de apps de serviço de entrega e transporte particular. |
Usuário do SDK do driver do Fleet Engine
roles/fleetengine.driverSdkUser |
Concede permissão para atualizar locais e rotas de veículos e para recuperar informações sobre veículos e viagens. Tokens criados por uma conta de serviço com esse papel geralmente são usadas dispositivos móveis com apps de transporte por aplicativo para motorista de transporte por aplicativo. |
Administrador sob demanda do Fleet Engine
roles/fleetengine.ondemandAdmin |
Concede permissão de leitura e gravação para todos os recursos de veículos e viagens. Os principais com esse papel não precisam usar JWTs e precisam usar o Application Default Credentials. As declarações JWT personalizadas são ignoradas. Esse papel precisa ser restrito a ambientes confiáveis (back-end do cliente). |
roles/fleetengine.serviceSuperUser |
Concede permissão a todas as APIs de veículos e viagens. Tokens criados
por uma conta de serviço com esse papel geralmente são usadas no back-end
servidores. Este papel foi suspenso. Prefere
roles/fleetengine.ondemandAdmin . |
Por exemplo, crie uma conta de serviço para cada um dos três papéis e atribua as respectivas funções.
gcloud --project=project-id iam service-accounts create fleet-engine-consumer-sdk gcloud projects add-iam-policy-binding project-id \ --member=serviceAccount:fleet-engine-consumer-sdk@project-id.iam.gserviceaccount.com \ --role=roles/fleetengine.consumerSdkUser gcloud --project=project-id iam service-accounts create fleet-engine-driver-sdk gcloud projects add-iam-policy-binding project-id \ --member=serviceAccount:fleet-engine-driver-sdk@project-id.iam.gserviceaccount.com \ --role=roles/fleetengine.driverSdkUser gcloud --project=project-id iam service-accounts create fleet-engine-su gcloud projects add-iam-policy-binding project-id \ --member=serviceAccount:fleet-engine-su@project-id.iam.gserviceaccount.com \ --role=roles/fleetengine.serviceSuperUser
Os SDKs do driver e do consumidor são criados com base nesses papéis padrão.
Também é possível criar papéis personalizados um conjunto arbitrário de permissões a serem agrupadas. Os SDKs do driver e do consumidor vão mostrar mensagens de erro sempre que um a permissão necessária está ausente. Por isso, é altamente recomendável usando o conjunto padrão de papéis apresentado acima e não usando papéis personalizados.
Para conveniência, se você precisar criar tokens JWT para clientes não confiáveis, adicione para o papel de criador de token da conta de serviço com as ferramentas de linha de comando gcloud.
gcloud projects add-iam-policy-binding project-id \
--member=user:my-user@example.com \
--role=roles/iam.serviceAccountTokenCreator
Em que my-user@example.com
é o e-mail usado para
autenticar com a gcloud (gcloud auth list
--format='value(account)'
).
Biblioteca de autenticação do Fleet Engine
O Fleet Engine usa JSON Web Tokens (JWTs) para restringir o acesso a APIs do Fleet Engine. A nova biblioteca Fleet Engine Auth, disponíveis no GitHub (em inglês). simplifica a construção de JWTs do Fleet Engine e os assina com segurança.
A biblioteca oferece os seguintes benefícios:
- Simplifica o processo de criação de tokens do Fleet Engine.
- Fornece mecanismos de assinatura de token diferentes do uso de arquivos de credenciais (como representar uma conta de serviço.
- Anexa tokens assinados a solicitações de saída feitas de um stub gRPC ou cliente GAPIC.
Criar um JSON Web Token (JWT) para autorização
Quando você não estiver usando a biblioteca de autenticação do Fleet Engine, os JSON Web Tokens (JWTs) precisam ser criados diretamente na sua base de código. Isso exige que você tenha um conhecimento profundo sobre JWTs e a relação deles com o Fleet Engine. É por isso que nós Recomendo usar a biblioteca de autenticação do Fleet Engine.
No Fleet Engine, os JSON Web Tokens (JWTs) oferecem autenticação de curta duração além de garantir que os dispositivos modifiquem veículos, viagens ou tarefas apenas que tem autorização para isso. Os JWTs contêm um cabeçalho e uma seção de declaração. A seção de cabeçalho contém informações como chave privada a ser usada (recebida de contas de serviço) e a criptografia algoritmo. A seção "Claim" contém informações como o tempo de criação do token, o time to live (TTL) dos tokens e os serviços aos quais ele reivindicar acesso e outras informações de autorização para reduzir o escopo; acesso por exemplo, o ID do veículo.
Uma seção de cabeçalho JWT contém os seguintes campos:
Campo | Descrição |
---|---|
alg | O algoritmo a ser usado. "RS256". |
typ | O tipo de token. "JWT". |
criança | ID da chave privada da conta de serviço. É possível encontrar esse valor no campo "private_key_id" do arquivo JSON da conta de serviço. Use uma chave de uma conta de serviço com o nível correto de permissões. |
Uma seção de declarações JWT contém os seguintes campos:
Campo | Descrição |
---|---|
iss | Endereço de e-mail da sua conta de serviço. |
sub | Endereço de e-mail da sua conta de serviço. |
aud | O SERVICE_NAME da sua conta de serviço, neste caso https://fleetengine.googleapis.com/ |
iat | Carimbo de data/hora em que o token foi criado, especificado em segundos decorridos desde 00:00:00 UTC, 1o de janeiro de 1970. Aguarde 10 minutos para o desvio. Se o o carimbo de data/hora estiver muito distante no passado ou no futuro, o servidor poderá informar um erro. |
exp | Carimbo de data/hora de expiração do token, especificado em segundos decorridos desde 00:00:00 UTC, 1o de janeiro de 1970. A solicitação falhará se o carimbo de data/hora for mais de uma hora no futuro. |
autorização | Dependendo do caso de uso, pode conter `vehicleid` ou `tripid`. |
A criação de um token JWT se refere a assiná-lo. Para instruções e exemplos de código para criar e assinar o JWT, consulte Autorização da conta de serviço sem OAuth. Depois, anexe um token assinado às chamadas gRPC ou a outros métodos usados para acessar o Fleet Engine.
Declarações JWT
Ao criar o payload do JWT, inclua uma declaração adicional na autorização
com a chave vehicleid
ou tripid
definida como o valor do parâmetro
ID do veículo ou da viagem para a qual a chamada está sendo feita.
O SDK do Driver sempre usa a declaração vehicleid
, esteja você operando em um
uma viagem ou veículo. O back-end do Fleet Engine garante que o veículo
está associado à viagem solicitada antes de fazer a modificação.
O SDK do consumidor sempre usa a declaração tripid
.
O provedor de serviço de transporte por aplicativo ou de entrega precisa usar vehicleid
ou tripid
com um "*" para
corresponder a todos os "Veículos" e "Viagens". O JWT pode conter tokens,
mesmo que não sejam necessárias, o que pode simplificar a implementação da assinatura de tokens.
Casos de uso do JWT
Veja a seguir um token de exemplo para o servidor do provedor:
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_provider_service_account"
}
.
{
"iss": "provider@yourgcpproject.iam.gserviceaccount.com",
"sub": "provider@yourgcpproject.iam.gserviceaccount.com",
"aud": "https://fleetengine.googleapis.com/",
"iat": 1511900000,
"exp": 1511903600,
"authorization": {
"vehicleid": "*",
"tripid": "*"
}
}
Veja a seguir um token de exemplo para o App para o consumidor:
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_consumer_service_account"
}
.
{
"iss": "consumer@yourgcpproject.iam.gserviceaccount.com",
"sub": "consumer@yourgcpproject.iam.gserviceaccount.com",
"aud": "https://fleetengine.googleapis.com/",
"iat": 1511900000,
"exp": 1511903600,
"authorization": {
"tripid": "trip_54321"
}
}
Confira a seguir um token de exemplo para o app do motorista:
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_driver_service_account"
}
.
{
"iss": "driver@yourgcpproject.iam.gserviceaccount.com",
"sub": "driver@yourgcpproject.iam.gserviceaccount.com",
"aud": "https://fleetengine.googleapis.com/",
"iat": 1511900000,
"exp": 1511903600,
"authorization": {
"vehicleid": "driver_12345"
}
}
- No campo
kid
do cabeçalho, especifique a chave privada da conta de serviço. ID. Esse valor está no campoprivate_key_id
do seu serviço arquivo JSON da conta de serviço. - Nos campos
iss
esub
, especifique o endereço de e-mail da sua conta de serviço. Esse valor está no campoclient_email
da sua conta de serviço arquivo JSON. - No campo
aud
, especifique https://SERVICE_NAME/. - No campo
iat
, use o carimbo de data/hora de quando o token foi criado. especificado como segundos decorridos desde 1o de janeiro de 1970, 00:00:00 UTC. Aguarde 10 minutos para o desvio. Se o carimbo de data/hora estiver muito no passado, ou, no futuro, o servidor informará um erro. - No campo
exp
, use o carimbo de data/hora de quando o token expirar. especificado como segundos desde 1o de janeiro de 1970, 00:00:00 UTC. O máximo o valor permitido éiat
+ 3.600.
Ao assinar o JWT que será transmitido para um dispositivo móvel, use o a conta de serviço para o papel de Driver ou SDK do consumidor. Caso contrário, o site dispositivo poderá alterar o estado que não deveria ter.
Da mesma forma, ao assinar o JWT que será usado para chamadas privilegiadas, verifique se para usar a conta de serviço com o papel de superusuário. Caso contrário, o vai falhar.
Como gerar um JWT para teste
Gerar tokens do terminal pode ser útil durante os testes.
Para seguir essas etapas, seu usuário a conta precisa ter o papel de Criador de token da conta de serviço:
gcloud projects add-iam-policy-binding project-id \
--member=user:my-user@example.com \
--role=roles/iam.serviceAccountTokenCreator
Crie um novo arquivo chamado unsigned_token.json
com o conteúdo abaixo. O iat
é a hora atual em número de segundos após a época, que pode ser
recuperados executando date +%s
no terminal. A propriedade exp
é o
o tempo de expiração em segundos após o período, que pode ser calculado da seguinte forma:
adicionando 3600 a iat
. O prazo de validade não pode ser superior a uma hora no
futuro.
{ "aud": "https://fleetengine.googleapis.com/", "iss": "super-user-service-account@project-id.iam.gserviceaccount.com", "sub": "super-user-service-account@project-id.iam.gserviceaccount.com", "iat": iat, "exp": exp, "authorization": { "vehicleid": "*", "tripid": "*" } }
Depois, execute o comando gcloud a seguir para assinar o token em nome do Super Conta de serviço de usuário:
gcloud beta iam service-accounts sign-jwt --iam-account=super-user-service-account@project-id.iam.gserviceaccount.com unsigned_token.json signed_token.jwt
Um JWT codificado em Base64 assinado deve ser armazenado no arquivo.
signed_token.jwt
: O token é válido para a próxima hora.
Agora é possível testar o token executando um comando curl
em "Listar veículos"
Endpoint REST:
curl -X GET "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles" -H "Authorization: Bearer $(cat signed_token.jwt)"
Veículos e o ciclo de vida deles
O veículo é a entidade que representa um par entre motorista e veículo. Atualmente, Motorista e Veículo não podem ser rastreados separadamente. O serviço de transporte por aplicativo ou provedor de entrega crie um Veículo usando um ID de provedor (que deve ser igual ao ID do projeto do Google Cloud que contém a conta de serviço usada para chamar as APIs do Fleet Engine) e um ID do veículo do provedor de transporte por aplicativo ou do serviço de entrega.
Um Veículo que não foi atualizado via UpdateVehicle
após sete dias será
será excluído automaticamente, e suas viagens atribuídas, se houver, serão marcadas como
não atribuída. A abordagem recomendada para manter um veículo disponível
do Fleet Engine é atualizar a localização em intervalos regulares. Atualizações para a maioria
outros campos da entidade Vehicle
também vão prolongar a vida útil dela, desde que
o valor do novo campo for diferente do atual.
OBSERVAÇÃO: alguns campos na entidade Vehicle
, como device_settings
, são meramente de depuração.
informações que não são mantidas pelo Fleet Engine. A atualização deles não
estendem a vida da entidade Vehicle
.
É um erro chamar CreateVehicle
com um
Par de ID do provedor/ID do veículo que já existe. As embalagens de veículos
não são atualizados com frequência pode ser feita de duas maneiras: fazer chamadas frequentes
CreateVehicle
com um par esperado de ID de provedor/ID do veículo e descartando
o erro se o Veículo já existir; ou chamar CreateVehicle
depois de um
UpdateVehicle
retorna com um erro NOT_FOUND
.
Atualizações de localização de veículos
Para ter o melhor desempenho com o Fleet Engine, forneça a ele um fluxo atualizações de localização. Use uma das seguintes maneiras para fornecer essas atualizações:
- Use o SDK do Driver: Android, iOS a opção mais simples.
- Use código personalizado (útil se os locais forem redirecionadas pelo seu back-end, ou se você usa dispositivos que não sejam Android ou no iOS.
Tipos de veículo
A entidade "Veículo" contém um campo obrigatório de VehicleType
, que contém um
Uma enumeração Category
que pode ser especificada como AUTO
, TAXI
, TRUCK
TWO_WHEELER
, BICYCLE
ou PEDESTRIAN
. O tipo de veículo pode servir como
critérios de filtro em SearchVehicles
e ListVehicles
.
Todas as rotas para veículos usarão o RouteTravelMode
correspondente se o
é definida como AUTO
, TWO_WHEELER
, BICYCLE
ou PEDESTRIAN
.
Se a categoria for definida como TAXI
ou TRUCK
, o roteamento será tratado da mesma forma que
o modo AUTO
.
Atributos do veículo
A entidade "Veículo" contém um campo repetido de VehicleAttribute
. Esses
atributos não são interpretados pelo Fleet Engine. O SearchVehicles
A API inclui um campo para exigir que Vehicles
correspondente contenha todos os
os atributos incluídos definidos para o valor especificado.
O campo do atributo é adicionado a vários outros campos compatíveis
na mensagem Vehicle
, como vehicle_type
e supported_trip_types
.
waypoints restantes do veículo
A entidade Vehicle contém um campo repetido de TripWaypoint
(RPC | REST),
chamado waypoints
(RPC | REST).
Esse campo inclui os waypoints restantes nas viagens, na ordem em que
quando o veículo chegar a eles. O Fleet Engine calcula esse campo à medida que as viagens são
atribuído ao veículo e o atualiza conforme as viagens mudam de status.
Esses waypoints podem ser identificados pelos campos TripId
e WaypointType
.
Ampliar a qualificação de um veículo para correspondência
Normalmente, os serviços de serviço de transporte por aplicativo ou provedor de entrega são responsáveis pelas solicitações
solicitações a veículos. O serviço pode usar os atributos do veículo para incluir um
veículo em um número maior de pesquisas. Por exemplo, o provedor pode implementar
um conjunto de atributos correspondentes aos níveis de benefícios ou recursos oferecidos pelo
um veículo. Por exemplo, três níveis podem ser um conjunto de atributos com valores
valores: is_bronze_level
, is_silver_level
e is_gold_level
. Um veículo
pode se qualificar para os três. Quando a Fleet Engine recebe uma solicitação
viagem que requer recursos do nível prata, a pesquisa inclui o veículo em questão.
Usar atributos dessa forma inclui veículos que oferecem uma variedade de
recursos.
Há duas maneiras de atualizar os atributos do veículo. Um deles é UpdateVehicle
.
API. Ao usar essa API, todo o conjunto de atributos do veículo é
definido como o valor. Não é possível atualizar um único atributo.
O outro método é a API UpdateVehicleAttributes
. Esse método leva apenas
os atributos a serem atualizados. Os atributos incluídos na solicitação serão
defina como o novo valor ou adicionado; os atributos não especificados não serão alterados.
TUTORIAL: Criar um veículo
É preciso criar uma entidade Vehicle
para cada veículo que será rastreado na frota.
Use o endpoint CreateVehicle
com o CreateVehicleRequest
para criar um
Veículo.
O provider_id
de Vehicle
precisa ser o ID do projeto.
(por exemplo, my-on-demand-project) do projeto do Google Cloud que contém o
Contas de serviço que serão usadas para chamar a frota. Embora
várias contas de serviço podem acessar o Fleet Engine para o mesmo serviço de
ou provedor de entrega, o Fleet Engine não oferece suporte a contas de serviço de
vários projetos do Google Cloud acessando o mesmo Vehicles
.
A Vehicle
pode ser criada no estado OFFLINE
ou ONLINE
. Se
criou ONLINE
, ele pode ser retornado imediatamente em resposta a SearchVehicles
.
consultas.
Um last_location
inicial pode ser incluído na chamada CreateVehicle
.
Embora permitido, um Vehicle
não pode ser criado no estado ONLINE
sem
um last_location
.
Consulte Tipos de veículo para mais detalhes sobre o veículo type.
Confira os atributos do veículo para mais detalhes. no campo de atributos.
O valor retornado de CreateVehicle
é a entidade Vehicle
criada.
Exemplo
shell
curl -X POST \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles?vehicleId=vid-8241890" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"vehicleState": "OFFLINE",
"supportedTripTypes": ["EXCLUSIVE"],
"maximumCapacity": 4,
"vehicleType": {"category": "AUTO"},
"attributes": [{"key": "on_trip", "value": "false"}]
}
EOM
Consulte providers.vehicles.create de referência.
Java
static final String PROJECT_ID = "project-id";
VehicleServiceBlockingStub vehicleService =
VehicleService.newBlockingStub(channel);
String parent = "providers/" + PROJECT_ID;
Vehicle vehicle = Vehicle.newBuilder()
.setVehicleState(VehicleState.OFFLINE) // Initial state
.addSupportedTripTypes(TripType.EXCLUSIVE)
.setMaximumCapacity(4)
.setVehicleType(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
.addAttributes(VehicleAttribute.newBuilder()
.setKey("on_trip").setValue("false")) // Opaque to the Fleet Engine
// Add .setBackToBackEnabled(true) to make this vehicle eligible for trip
// matching while even if it is on a trip. By default this is disabled.
.build();
CreateVehicleRequest createVehicleRequest =
CreateVehicleRequest.newBuilder() // no need for the header
.setParent(parent)
.setVehicleId("vid-8241890") // Vehicle ID assigned by Rideshare or Delivery Provider
.setVehicle(vehicle) // Initial state
.build();
// In this case, the Vehicle is being created in the OFFLINE state and
// no initial position is being provided. When the Driver App checks
// in with the Rideshare or Delivery Provider, the state can be set to ONLINE and
// the Driver App will update the Vehicle Location.
try {
Vehicle createdVehicle =
vehicleService.createVehicle(createVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
// If no Exception, Vehicle created successfully.
Registros do Google Cloud Platform para criação de veículos
A API Fleet Engine grava uma entrada de registro nos registros do Google Cloud Platform quando um
a chamada para o endpoint CreateVehicle
for recebida. A entrada de registro inclui
informações sobre os valores na solicitação CreateVehicle
. Se a ligação
for bem-sucedido, ele também vai incluir informações sobre o Vehicle
que foi
retornados.
shell
gcloud --project=project-id logging read --freshness=1h '
jsonPayload.request.vehicleId="vid-8241890"
jsonPayload.@type="type.googleapis.com/maps.fleetengine.v1.CreateVehicleLog"
'
Deve imprimir um registro semelhante ao seguinte:
---
insertId: c2cf4d3a180251c1bdb892137c14f022
jsonPayload:
'@type': type.googleapis.com/maps.fleetengine.v1.CreateVehicleLog
request:
vehicle:
attributes:
- key: on_trip
value: 'false'
maximumCapacity: 4
state: VEHICLE_STATE_OFFLINE
supportedTrips:
- EXCLUSIVE_TRIP
vehicleType:
vehicleCategory: AUTO
vehicleId: vid-8241890
response:
attributes:
- key: on_trip
value: 'false'
availableCapacity: 4
currentRouteSegmentHandle: AdSiwAwCO9gZ7Pw5UZZimOXOo41cJTjg/r3SuwVPQmuuaV0sU3+3UCY+z53Cl9i6mWHLoCKbBt9Vsj5PMRgOJ8zX
maximumCapacity: 4
name: providers/project-id/vehicles/vid-8241890
state: VEHICLE_STATE_OFFLINE
supportedTrips:
- EXCLUSIVE_TRIP
vehicleType:
vehicleCategory: AUTO
labels:
vehicle_id: vid-8241890
logName: projects/project-id/logs/fleetengine.googleapis.com%2Fcreate_vehicle
receiveTimestamp: '2021-09-22T03:25:16.361159871Z'
resource:
labels:
location: global
resource_container: projects/project-id
type: fleetengine.googleapis.com/Fleet
timestamp: '2021-09-22T03:25:15.724998Z'
Notificações do Cloud Pub/Sub para a criação de veículos
A API Fleet Engine publica uma notificação pelo Cloud Pub/Sub quando uma nova veículo é criado. Para receber essas notificações, siga as instruções aqui.
Instruções: atualizar a localização de um veículo
Se você não estiver usando o SDK do motorista para atualizar a localização do veículo, faça uma uma chamada direta para o Fleet Engine com a localização do veículo. Para qualquer veículo ativo, O Fleet Engine espera uma atualização de local pelo menos uma vez por minuto e no máximo uma vez a cada 5 segundos. Essas atualizações exigem apenas o usuário do SDK do driver do Fleet Engine para conceder privilégios de acesso.
Exemplo
shell
curl -X PUT \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=last_location" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"supplementalLocation": {"latitude": 12.1, "longitude": 14.5},
"supplementalLocationTime": "$(date -u --iso-8601=seconds)",
"supplementalLocationSensor": "CUSTOMER_SUPPLIED_LOCATION",
"supplementalLocationAccuracy": 15
}
EOM
Consulte providers.vehicles.update de referência.
Java
static final String PROJECT_ID = "project-id";
static final String VEHICLE_ID = "vid-8241890";
VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);
String vehicleName = "providers/" + PROJECT_ID + "/vehicles/" + VEHICLE_ID;
Vehicle updatedVehicle = Vehicle.newBuilder()
.setLastLocation(VehicleLocation.newBuilder()
.setSupplementalLocation(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863))
.setSupplementalLocationTime(now())
.setSupplementalLocationSensor(LocationSensor.CUSTOMER_SUPPLIED_LOCATION)
.setSupplementalLocationAccuracy(DoubleValue.of(15.0))) // Optional)
.build();
UpdateVehicleRequest updateVehicleRequest = UpdateVehicleRequest.newBuilder()
.setName(vehicleName)
.setVehicle(updatedVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("last_location"))
.build();
try {
Vehicle updatedVehicle =
vehicleService.updateVehicle(updateVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
// Most implementations will call CreateVehicle in this case
break;
case PERMISSION_DENIED:
break;
}
return;
}
// If no Exception, Vehicle updated successfully.
Instruções: atualize outros campos do veículo
A frequência de atualizações de outros atributos do estado do veículo é menor do que
atualizações de posição. É necessário atualizar os atributos diferentes de last_location
Privilégios de superusuário do Fleet Engine.
O UpdateVehicleRequest
inclui um update_mask
para indicar quais campos serão
atualizar. O comportamento do campo é como na documentação do Protobuf para
máscaras de campo.
Conforme observado em Atributos do veículo, atualizar o
O campo attributes
requer a gravação de todos os atributos a serem preservados. Ela
não é possível simplesmente atualizar o valor de um par de valores-chave em uma
UpdateVehicle
. Para atualizar valores de atributos específicos, a função
A API UpdateVehicleAttributes
pode ser usada.
Exemplo
Este exemplo ativa back_to_back
.
shell
curl -X PUT \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=vehicle_state,attributes,back_to_back_enabled" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"vehicleState": "ONLINE",
"attributes": [
{"key": "on_trip", "value": "true"},
{"key": "cash_only", "value": "false"}
],
"backToBackEnabled": true
}
EOM
Consulte providers.vehicles.update de referência.
Java
static final String PROJECT_ID = "project-id";
static final String VEHICLE_ID = "vid-8241890";
VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);
String vehicleName = "providers/" + PROJECT_ID + "/vehicles/" + VEHICLE_ID;
Vehicle updatedVehicle = Vehicle.newBuilder()
.setVehicleState(VehicleState.ONLINE)
.addAllAttributes(ImmutableList.of(
VehicleAttribute.newBuilder().setKey("on_trip").setValue("true").build(),
VehicleAttribute.newBuilder().setKey("cash_only").setValue("false").build()))
.setBackToBackEnabled(true)
.build();
UpdateVehicleRequest updateVehicleRequest = UpdateVehicleRequest.newBuilder()
.setName(vehicleName)
.setVehicle(updatedVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("vehicle_state")
.addPaths("attributes")
.addPaths("back_to_back_enabled"))
.build();
// Attributes and vehicle state are being updated, so both are
// included in the field mask. Note that of on_trip were
// not being updated, but rather cash_only was being changed,
// the desired value of "on_trip" would still need to be written
// as the attributes are completely replaced in an update operation.
try {
Vehicle updatedVehicle =
vehicleService.updateVehicle(updateVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
// Most implementations will call CreateVehicle in this case
break;
case PERMISSION_DENIED:
break;
}
return;
}
// If no Exception, Vehicle updated successfully.
Registros do Google Cloud Platform para atualizações de veículos
A API Fleet Engine grava uma entrada de registro nos registros do Google Cloud Platform quando um
a chamada para o endpoint UpdateVehicle
for recebida. A entrada de registro inclui
informações sobre os valores na solicitação UpdateVehicle
. Se a ligação
for bem-sucedido, ele também vai incluir informações sobre o Vehicle
que foi
retornados.
shell
gcloud --project=project-id logging read --freshness=1h '
jsonPayload.request.vehicleId="vid-8241890"
jsonPayload.@type="type.googleapis.com/maps.fleetengine.v1.UpdateVehicleLog"
'
Notificações do Cloud Pub/Sub para atualizações de veículos
A API Fleet Engine publica uma notificação pelo Cloud Pub/Sub quando um veículo atualizado. Para receber essas notificações, siga as instruções aqui.
COMO FAZER: Pesquisar veículos
O Fleet Engine é compatível com a pesquisa de veículos. O SearchVehicles
permite que você encontre motoristas por perto que sejam mais adequados para uma tarefa, como
atender a uma solicitação de viagem ou entrega. A API SearchVehicles
retorna uma
lista de motoristas que correspondem aos atributos da tarefa com os atributos dos veículos em
sua frota. Para mais informações, consulte
Encontrar motoristas próximos.
Exemplo
Ao procurar veículos disponíveis, o Fleet Engine exclui os veículos em viagens ativas por padrão. Os serviços do provedor de serviço de transporte por aplicativo ou de entrega precisam incluí-las explicitamente nas solicitações de pesquisa. O exemplo abaixo mostra como inclua esses veículos em uma pesquisa por veículos que correspondem a uma viagem do Do Indonesia East Mall ao Centro de Convenções Balai Sidang Jakarta.
shell
Primeiro, atualize a localização do veículo que criamos nas etapas anteriores para que está qualificado. No mundo real, isso seria feito pelo SDK do Driver em execução em um dispositivo Android ou iOS no veículo.
curl -X PUT \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=last_location,attributes" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"lastLocation": {
"updateTime": "$( date -u +"%Y-%m-%dT%H:%M:%SZ" )",
"location": {
"latitude": "-6.195139",
"longitude": "106.820826"
}
},
"attributes": [{"key": "on_trip", "value": "false"}]
}
EOM
A realização da pesquisa deve render pelo menos esse veículo.
curl -X POST \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles:search" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"pickupPoint": {
"point": {"latitude": "-6.195139", "longitude": "106.820826"}
},
"dropoffPoint": {
"point": {"latitude": "-6.1275", "longitude": "106.6537"}
},
"pickupRadiusMeters": 2000,
"count": 10,
"minimumCapacity": 2,
"tripTypes": ["EXCLUSIVE"],
"vehicleTypes": [{"category": "AUTO"}],
"filter": "attributes.on_trip=\"false\"",
"orderBy": "PICKUP_POINT_ETA",
"includeBackToBack": true
}
EOM
Consulte providers.vehicles.search de referência.
Java
static final String PROJECT_ID = "project-id";
VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);
String parent = "providers/" + PROJECT_ID;
SearchVehiclesRequest searchVehiclesRequest = SearchVehiclesRequest.newBuilder()
.setParent(parent)
.setPickupPoint( // Grand Indonesia East Mall
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setDropoffPoint( // Balai Sidang Jakarta Convention Center
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.213796).setLongitude(106.807195)))
.setPickupRadiusMeters(2000)
.setCount(10)
.setMinimumCapacity(2)
.addTripTypes(TripType.EXCLUSIVE)
.addVehicleTypes(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
.setFilter("attributes.on_trip=\"false\"")
.setOrderBy(VehicleMatchOrder.PICKUP_POINT_ETA)
.setIncludeBackToBack(true) // Fleet Engine includes vehicles that are en route.
.build();
// Error handling
// If matches are returned and the authentication passed, the request completed
// successfully
try {
SearchVehiclesResponse searchVehiclesResponse =
vehicleService.searchVehicles(searchVehiclesRequest);
// Search results: Each vehicle match contains a vehicle entity and information
// about the distance and ETA to the pickup point and dropoff point.
List<VehicleMatch> vehicleMatches = searchVehiclesResponse.getMatchesList();
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
Consulta sobre filtragem de veículos
SearchVehicles
e ListVehicles
são compatíveis com a filtragem de atributos do veículo
usando uma consulta de filtro. Para saber a sintaxe da consulta de filtro, consulte
AIP-160 para exemplos.
As consultas com filtro são compatíveis APENAS com a filtragem de atributos do veículo.
não pode ser usado para outros campos. A consulta de filtro funciona como uma cláusula AND
com outras restrições, como minimum_capacity
ou vehicle_types
em
SearchVehiclesRequest
INSTRUÇÃO: listar veículos
O SearchVehicles
é otimizado para encontrar um pequeno número de veículos na classificação.
fazer pedidos com muita rapidez e serve principalmente para encontrar motoristas próximos que sejam mais adequados
a uma tarefa. No entanto, às vezes, você quer encontrar todos os veículos que atendam a alguns
critérios, mesmo que seja necessário percorrer os resultados. ListVehicles
é
projetados para esse caso de uso.
A API ListVehicles
permite encontrar todos os veículos que atendem a alguns requisitos
opções de solicitação. A API ListVehicles
retorna uma lista paginada de veículos em
do projeto que atende a alguns requisitos.
Para filtrar por atributos do veículo, consulte Consulta de filtragem de veículos.
Exemplo
Este exemplo realiza a filtragem em vehicle_type
e em atributos usando a
String filter
.
shell
curl -X POST \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles:list" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"vehicleTypes": [{"category": "AUTO"}],
"filter": "attributes.on_trip=\"false\"",
}
EOM
Consulte providers.vehicles.list de referência.
Java
static final String PROJECT_ID = "project-id";
VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);
String parent = "providers/" + PROJECT_ID;
ListVehiclesRequest listVehiclesRequest = ListVehiclesRequest.newBuilder()
.setParent(parent)
.addTripTypes(TripType.EXCLUSIVE)
.addVehicleTypes(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
.setFilter("attributes.on_trip=\"false\"")
.setIncludeBackToBack(true) // Fleet Engine includes vehicles that are en route.
.build();
// Error handling
// If matches are returned and the authentication passed, the request completed
// successfully
try {
ListVehiclesResponse listVehiclesResponse =
vehicleService.listVehicles(listVehiclesRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
Viagens e o ciclo de vida delas
A API Trip e o ciclo de vida são semelhantes à API Vehicle e ao ciclo de vida.
O provedor de transporte por aplicativo é responsável por criar viagens usando o Fleet Engine
do Google Cloud. O Fleet Engine fornece um serviço de RPC
TripService
e recursos REST, provider.trips
, Essas interfaces permitem a criação de entidades Trip, solicitações de informações, pesquisa
e da capacidade de atualização.
Uma Trip
tem um campo de status para acompanhar a progressão dela ao longo do ciclo de vida.
Os valores são movidos de NEW
para COMPLETE
, mais CANCELED
e UNKNOWN_TRIP_STATUS
.
, Consulte trip_status
para RPC
ou TripStatus para REST.
NEW
ENROUTE_TO_PICKUP
ARRIVED_AT_PICKUP
ENROUTE_TO_INTERMEDIATE_DESTINATION
ARRIVED_AT_INTERMEDIATE_DESTINATION
ENROUTE_TO_DROPOFF
COMPLETE
Seu serviço pode atualizar a viagem para CANCELED
usando qualquer um desses status.
Quando o serviço cria uma viagem, o mecanismo define o status como NEW
. Um
vehicle_id
é opcional. Assim como os veículos, os serviços excluem automaticamente as viagens não atribuídas
após sete dias sem atualização. Se o serviço tentar criar uma viagem com uma
ID que já existe, um erro será retornado. Uma viagem é considerada "ativa" se
ela está em um status diferente de COMPLETE
ou CANCELED
. Essa distinção é
importante no campo active_trips
da entidade "Veículo" e em SearchTripsRequest
.
Seu serviço só pode mudar o vehicle_id
atribuído a uma viagem quando ela
está ativo. Por exemplo, faça isso quando um motorista cancela uma viagem
trajeto e a viagem é reatribuída a outro veículo.
O status é importante ao implementar suporte de viagens. Esse suporte permite que o provedor atribua uma nova viagem a um Veículo enquanto ele estiver em uma viagem ativa. O código para criar uma viagem de ida e volta é o mesmo que uma única viagem e usa a mesma ID do veículo. A Fleet Engine adiciona a origem e o destino da nova viagem ao waypoints do veículo. Para mais informações sobre viagens de ida e volta, consulte Criar viagens com vários waypoints.
waypoints restantes da viagem
A entidade Trip contém um campo repetido de TripWaypoint
(RPC | REST),
chamado remainingWaypoints
(RPC | REST).
Este campo inclui todos os waypoints que o veículo precisará percorrer em ordem
antes do ponto de desembarque final dessa viagem. Ele calcula
Pontos de referência restantes do veículo.
Nos casos de uso Back-to-back e Waze Carpool, esta lista contém waypoints dos
outras viagens que serão percorridas antes desta, mas exclui os waypoints
depois dessa viagem. O waypoint na lista pode ser identificado pelo elemento TripId
e WaypointType
.
A relação entre o status da viagem e os waypoints restantes do veículo
Os waypoints restantes do veículo (RPC | REST) serão
serão atualizados quando o Fleet Engine receber uma solicitação de alteração do status da viagem. O
o waypoint anterior será removido da lista de waypoints restantes do veículo quando
o tripStatus
(RPC | REST)
é alterado de outro status para ENROUTE_TO_XXX. Ou seja, quando
o status da viagem é alterado de ENROUTE_TO_PICKUP para ARRIVED_AT_PICKUP, o
o ponto de embarque ainda estará na lista de waypoints restantes do veículo, mas quando a viagem
o status for alterado para ENROUTE_TO_INTERMEDIATE_DESTINATION ou ENROUTE_TO_DROPOFF,
seu ponto de embarque será removido dos waypoints restantes do veículo.
O mesmo acontece com ARRIVED_AT_INTERMEDIATE_DESTINATION e ENROUTE_TO_INTERMDEDIATE_DESTINATION. Quando ARRIVED_AT_INTERMEDIATE_DESTINATION, o destino intermediário atual não será removido dos campos restantes do veículo lista de pontos de referência até que o veículo informe que segue o trajeto para o próximo.
Quando o status da viagem for alterado para COMPLETED
, nenhum waypoint dessa viagem será
na lista de waypoints restantes do veículo.
COMO FAZER: Criar uma viagem
É necessário criar uma entidade Trip
para que cada solicitação de viagem seja rastreada e
correspondentes aos veículos da frota. Use o endpoint CreateTrip
com CreateTripRequest
para criar uma viagem.
Os atributos a seguir são obrigatórios para criar uma viagem:
parent
: uma string que inclui o ID do provedor criado quando o serviço O projeto do Google Cloud foi criado.trip_id
: uma string criada pelo provedor de serviço de transporte por aplicativo.trip
: contêiner com metadados básicos que descrevem a viagem.trip_type
: enumeração que representa se a viagem pode incluir outros passageiros. de uma origem e um destino diferentes no mesmo veículo (SHARED
) ou uma única parte (EXCLUSIVE
).pickup_point
: TerminalLocation que representa o ponto de origem do viagem. Consulte a referência da RPC ou referência da REST
Ao criar uma viagem, você pode informar number_of_passengers
e dropoff_point
e vehicle_id
. Embora esses campos não sejam obrigatórios, se forem fornecidos,
eles serão retidos. Todos os outros campos "Viagem" são ignorados. Por exemplo, todas as viagens
comece com um trip_status
de NEW
mesmo que você transmita um trip_status
de
CANCELED
na solicitação de criação.
Exemplo
O exemplo a seguir cria uma viagem para o Grand Indonesia East Mall. A viagem
é para dois passageiros e é exclusivo. O provider_id
do Trip
precisa ser
é igual ao ID do projeto. No exemplo, o provedor de serviço de transporte por aplicativo criou
Projeto do Google Cloud, project-id. Este projeto deve ter
Contas de serviço usadas para chamar o Fleet Engine. O status da viagem é NEW
.
Mais tarde, depois que o serviço faz a correspondência da viagem com um veículo, ele pode chamar
UpdateTrip
e mude o vehicle_id
quando a viagem for atribuída a um veículo.
shell
curl -X POST \
"https://fleetengine.googleapis.com/v1/providers/project-id/trips?tripId=tid-1f97" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"tripType": "EXCLUSIVE",
"numberOfPassengers": 2,
"pickupPoint": {
"point": {"latitude": "-6.195139", "longitude": "106.820826"}
},
"dropoffPoint": {
"point": {"latitude": "-6.1275", "longitude": "106.6537"}
}
}
EOM
Consulte providers.trips.create de referência.
Java
static final String PROJECT_ID = "project-id";
TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);
String parent = "providers/" + PROJECT_ID;
Trip trip = Trip.newBuilder()
.setTripType(TripType.EXCLUSIVE) // Use TripType.SHARED for carpooling
.setPickupPoint( // Grand Indonesia East Mall
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
// Provide the number of passengers if available.
.setNumberOfPassengers(2)
// Provide the drop-off point if available.
.setDropoffPoint(
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.1275).setLongitude(106.6537)))
.build();
CreateTripRequest createTripRequest =
CreateTripRequest.newBuilder() // no need for the header
.setParent(parent)
.setTripId("tid-1f97") // Trip ID assigned by the Provider
.setTrip(trip) // Initial state
.build();
// Error handling
// If Fleet Engine does not have trip with that id and the credentials of the
// requestor pass, the service creates the trip successfully.
try {
Trip createdTrip =
tripService.createTrip(createTripRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
Registros do Google Cloud Platform para criação de viagens
A API Fleet Engine grava uma entrada usando os registros do Google Cloud Platform quando um
a chamada para o endpoint CreateTrip
for recebida. A entrada de registro inclui
informações sobre os valores na solicitação CreateTrip
. Se a ligação
for bem-sucedido, ele também incluirá informações sobre o Trip
que foi retornado.
TUTORIAL: Atualizar uma viagem
A entidade Trip contém campos que permitem o rastreamento pelo serviço e para
informar a progressão da viagem pelo SDK do motorista e ao
SDK do consumidor. Para atualizar as propriedades, use UpdateTripRequest
.
mensagem. Isso atualiza os campos de viagem de acordo com o field_mask
da solicitação.
Consulte UpdateTripRequest.
O provedor de serviço de transporte por aplicativo é responsável por atualizar os seguintes atributos:
- Status da viagem.
- ID do veículo. No momento da criação ou depois de corresponder o veículo a um viagem.
- Alterações no embarque, desembarque ou waypoints.
O Fleet Engine atualiza automaticamente os seguintes campos ao usar o Recurso de Compartilhamento de jornada pelo SDK do Driver ou do SDK do consumidor:
- Rotas
- HEC
- Distância restante
- Localização do veículo
- Pontos de referência restantes
Consulte Trip
em RPC ou
Resource.Trip
em REST.
Registros do Google Cloud Platform para atualizações de viagem
A API Fleet Engine grava uma entrada usando os registros do Google Cloud Platform quando um
a chamada para o endpoint UpdateTrip
for recebida. A entrada de registro inclui
informações sobre os valores na solicitação UpdateTrip
. Se a chamada for bem-sucedida,
ela também vai incluir informações sobre o Trip
que foi retornado.
TUTORIAL: Pesquisar viagens
O Fleet Engine é compatível com a pesquisa de viagens. Como mencionado anteriormente, uma viagem é
excluído automaticamente após sete dias, então SearchTrips
não
Expor um histórico completo de todas as viagens.
Embora a SearchTrips
seja uma API flexível, a lista abaixo considera dois casos de uso.
Determinação das viagens ativas de um veículo -- O provedor pode determinar as viagens atualmente ativas de um veículo. No
SearchTripsRequest
, osvehicle_id
é definido como o veículo em questão, eactive_trips_only
precisa ser definido comotrue
.Reconciliação do provedor e do estado do mecanismo da frota: o provedor pode usar
SearchTrips
para garantir que o estado da viagem e da frota sejam correspondentes. Isso é especialmente importante para o TripStatus. Se o estado de uma viagem atribuído a "Veículo" não estiver configurado corretamente comoCOMPLETE
ouCANCELED
, o Veículo não está incluído porSearchVehicles
.
Para usar SearchTrips
dessa maneira, deixe vehicle_id
em branco, defina active_trips_only
como true
e defina minimum_staleness
como um horário maior do que a maioria das durações de viagem.
Por exemplo, você pode usar uma hora. Os resultados incluem viagens que não estão
CONCLUÍDA nem CANCELADA e não foram atualizadas há mais de uma hora. O provedor
deve examinar essas viagens para garantir que o status delas no motor da frota seja
atualizado corretamente.
Solução de problemas
No caso de um erro DEADLINE_EXCEEDED
, o estado da frota é
desconhecida. O provedor precisa chamar CreateTrip
novamente, que retorna uma
201 (CREATED) ou 409 (CONFLICT). No último caso, a solicitação anterior foi bem-sucedida
antes de DEADLINE_EXCEEDED
. Consulte os guias da API Consumer para mais informações
sobre como lidar com erros de viagem: Android
ou iOS.
Suporte de viagem do Waze
Você pode atribuir várias viagens SHARED
a um veículo compatível com TripType.SHARED
.
Você precisa especificar a ordem de todos os waypoints não transmitidos em todas as viagens atribuídas a
o veículo nesta viagem compartilhada por Trip.vehicle_waypoints
ao atribuir o
vehicle_id
para uma viagem compartilhada (em uma solicitação CreateTrip
ou UpdateTrip
).
Consulte vehicle_waypoints
para RPC
ou vehicleWaypoints
para REST.
Suporte a vários destinos
Identificar um destino intermediário
Os campos intermediateDestinations
e intermediateDestinationIndex
em viagem (RPC | REST)
são combinados para serem usados para indicar o destino.
Atualizar destino intermediário
É possível atualizar os destinos intermediários com UpdateTrip
. Durante a atualização
destinos intermediários, você precisa fornecer uma lista completa de destinos intermediários,
incluindo aqueles que já foram visitados, não apenas o
adicionados ou a serem modificados.
Quando o intermediateDestinationIndex
aponta para um índice após a posição de
destino intermediário recém-adicionado/modificado, o intermediário novo/atualizado
o destino não será adicionado aos waypoints
do veículo ou aos remainingWaypoints
da viagem.
O motivo é que todos os destinos intermediários antes de intermediateDestinationIndex
são tratados como já visitados.
Alterações no status da viagem
O campo intermediateDestinationsVersion
em (RPC | REST)
é obrigatório na solicitação de atualização do status de viagem enviada ao Fleet Engine para indicar
um destino intermediário passou. O destino intermediário segmentado
é especificado pelo campo intermediateDestinationIndex
.
Quando tripStatus
(RPC | REST) for ENROUTE_TO_INTERMEDIATE_DESTINATION, um número entre
[0..N-1] indica o próximo destino intermediário que o veículo vai atravessar.
Quando tripStatus
for ARRIVED_AT_INTERMEDIATE_DESTINATION, um número entre
[0..N-1] indica em qual destino intermediário o veículo está.
Exemplo
O exemplo de código a seguir demonstra como atualizar o status de uma viagem para ao primeiro destino intermediário, supondo que você tenha criado viagem com vários destinos e já tiver passado do ponto de embarque.
Java
static final String PROJECT_ID = "project-id";
static final String TRIP_ID = "multi-destination-trip-A";
String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_ID;
Trip trip = …; // Fetch trip object from FleetEngine or your storage.
TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);
// Trip settings to update.
Trip trip = Trip.newBuilder()
// Trip status cannot go back to a previous status once it is passed
.setTripStatus(TripStatus.ENROUTE_TO_INTERMEDIATE_DESTINATION)
// Enrouting to the first intermediate destination.
.setIntermediateDestinationIndex(0)
// intermediate_destinations_version MUST be provided to ensure you
// have the same picture on intermediate destinations list as FleetEngine has.
.setIntermediateDestinationsVersion(
trip.getIntermediateDestinationsVersion())
.build();
// Trip update request
UpdateTripRequest updateTripRequest =
UpdateTripRequest.newBuilder()
.setName(tripName)
.setTrip(trip)
.setUpdateMask(
FieldMask.newBuilder()
.addPaths("trip_status")
.addPaths("intermediate_destination_index")
// intermediate_destinations_version must not be in the
// update mask.
.build())
.build();
// Error handling
try {
Trip updatedTrip = tripService.updateTrip(updateTripRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND: // Trip does not exist.
break;
case FAILED_PRECONDITION: // The given trip status is invalid, or the
// intermediate_destinations_version
// doesn’t match FleetEngine’s.
break;
case PERMISSION_DENIED:
break;
}
return;
}
Instruções: inscreva-se para receber mensagens de notificação da API Fleet Engine
A API Fleet Engine usa o Google Cloud Pub/Sub para publicar notificações sobre o tópico criado pelo Google Cloud Projeto. O Pub/Sub não está ativado por padrão para o Fleet Engine no seu Google Cloud projeto. Registre um caso de suporte ou entre em contato com seu Engenheiro de clientes para ativar o Pub/Sub.
Para criar um tópico no projeto do Cloud, siga estas instruções. O ID do tópico precisa ser "fleet_engine_notifications".
O tópico precisa ser criado no mesmo projeto do Cloud que está chamando o Fleet Engine APIs de terceiros.
Depois de criar o tópico, é necessário conceder à API Fleet Engine
permissão para publicar no tópico. Para fazer isso, clique no tópico que você
que acabou de criar e adiciona uma nova permissão. Talvez seja necessário clicar em MOSTRAR PAINEL DE INFORMAÇÕES para abrir o editor de permissões.
O principal precisa ser geo-fleet-engine@system.gserviceaccount.com
e o papel precisa ser Pub/Sub publisher
.
Para configurar seu projeto do Cloud para receber notificações, siga estas instruções.
A API Fleet Engine publicará cada notificação em dois dados diferentes
formatos, protobuf
e
json
. O formato dos dados de cada notificação é indicado na
Atributos do PubsubMessage
com a chave data_format
e o valor protobuf
ou json
.
Esquema de notificação:
Protobuf
// A batch of notifications that is published by the Fleet Engine service using
// Cloud Pub/Sub in a single PubsubMessage.
message BatchNotification {
// Required. At least one notification must exist.
// List of notifications containing information related to changes in
// Fleet Engine data.
repeated Notification notifications = 1;
}
// A notification related to changes in Fleet Engine data.
// The data provides additional information specific to the type of the
// notification.
message Notification {
// Required. At least one type must exist.
// Type of notification.
oneof type {
// Notification related to changes in vehicle data.
VehicleNotification vehicle_notification = 1;
}
}
// Notification sent when a new vehicle was created.
message CreateVehicleNotification {
// Required.
// Vehicle must contain all fields that were set when it was created.
Vehicle vehicle = 1;
}
// Notification sent when an existing vehicle is updated.
message UpdateVehicleNotification {
// Required.
// Vehicle must only contain name and fields that are present in the
// field_mask field below.
Vehicle vehicle = 1;
// Required.
// Contains vehicle field paths that were specifically requested
// by the Provider.
google.protobuf.FieldMask field_mask = 2;
}
// Notification related to changes in vehicle data.
message VehicleNotification {
// Required. At least one type must be set.
// Type of notification.
oneof type {
// Notification sent when a new vehicle was created.
CreateVehicleNotification create_notification = 1;
// Notification sent when an existing vehicle is updated.
UpdateVehicleNotification update_notification = 2;
}
}
JSON
BatchNotification: {
"description": "A batch of notifications that is published by the Fleet Engine service using Cloud Pub/Sub in a single PubsubMessage.",
"type": "object",
"required": ["notifications"],
"properties": {
"notifications": {
"description": "At least one notification must exist. List of notifications containing information related to changes in Fleet Engine data.",
"type": "Notification[]"
}
}
}
Notification: {
"description": "A notification related to changes in Fleet Engine data. The data provides additional information specific to the type of the notification.",
"type": "object",
"properties": {
"vehicleNotification": {
"description": "Notification related to changes in vehicle data.",
"type": "VehicleNotification"
}
}
}
VehicleNotification: {
"description": "Notification related to changes in vehicle data.",
"type": "object",
"properties": {
"createNotification": {
"description": "Notification sent when a new vehicle was created.",
"type": "CreateVehicleNotification"
},
"updateNotification": {
"description": "Notification sent when an existing vehicle is updated.",
"type": "UpdateVehicleNotification"
}
}
}
CreateVehicleNotification: {
"description": "Notification sent when a new vehicle was created.",
"type": "object",
"required": ["vehicle"],
"properties": {
"vehicle": {
"description": "Vehicle must contain all fields that were set when it was created.",
"type": "Vehicle"
}
}
}
UpdateVehicleNotification: {
"description": "Notification sent when an existing vehicle is updated.",
"type": "object",
"required": ["vehicle", "fieldMask"],
"properties": {
"vehicle": {
"description": "Vehicle must only contain name and fields that are present in the fieldMask field below.",
"type": "Vehicle"
},
"fieldMask": {
"description": "Contains vehicle field paths that were specifically requested by the Provider.",
"type": "FieldMask"
}
}
}