Primeiros passos com o Fleet Engine

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.

Observação: considere usar o ambiente interativo do Cloud Shell em que o SDK Cloud e outras dependências, como curl, já estão instaladas. Consulte Como usar o Cloud Shell.

shell

gcloud auth login

Você verá uma mensagem de sucesso como esta:

You are now logged in as [[e-mail]].
Your current project is [project-id].  You ...

Observação :edite os valores de variáveis em blocos de código para preparar para que eles possam ser copiados e colados diretamente.

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:

1. Criar um projeto do Google Cloud usando o console do Google Cloud.
2. 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).
Superusuário de serviço do FleetEngine **(DESCONTINUADO)** 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:[e-mail] \
       --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:[e-mail] \
       --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:[e-mail] \
       --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:[e-mail] \
       --role=roles/iam.serviceAccountTokenCreator

Em que [e-mail] é o e-mail usado para autenticar com a gcloud (gcloud auth list --format='value(account)').

Observação: isso dá ao beneficiário permissão para representar qualquer conta de serviço na o projeto. Para definir permissões mais detalhadas, siga a documentação do IAM ativado definir o escopo de vinculações de papéis para uma conta de serviço específica.

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.

.

Importante: é altamente recomendável usar a biblioteca de autenticação do Fleet Engine com todas Implementações Java.

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": "[e-mail]",
  "sub": "[e-mail]",
  "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": "[e-mail]",
  "sub": "[e-mail]",
  "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": "[e-mail]",
  "sub": "[e-mail]",
  "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 campo private_key_id do seu serviço arquivo JSON da conta de serviço.
• Nos campos iss e sub, especifique o endereço de e-mail da sua conta de serviço. Esse valor está no campo client_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:[e-mail] \
       --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": "[e-mail]",
  "sub": "[e-mail]",
  "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=[e-mail] 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:

1. Use o SDK do Driver: Android, iOS a opção mais simples.
2. 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 os Vehicles correspondentes contenham todos 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 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 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.

Observação: CreateVehicle requer uma conta com o papel de superusuário do Fleet Engine.

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.

Observação :o campo update_mask precisa ser sempre definido. Não definir o O padrão do campo update_mask é gravar todos os campos. Isso pode resultar em comportamentos não intencionais.

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

Observação :é altamente recomendável usar o campo de consulta filter nas required_attributes, required_one_of_attributes e Campos required_one_of_attributes_sets, já que filter foi criado para substituir nesses campos. Se um valor não vazio for especificado no campo filter, o campos a seguir devem estar vazios: required_attributes, required_one_of_attributes e required_one_of_attributes_sets.

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 do Google. 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. do Google. 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.

Observação :o Fleet Engine não aceita a exclusão explícita de uma viagem. O serviço exclui automaticamente as viagens após sete dias sem atualizações. O Google não retém dados pessoais. Para reter os dados da viagem, o O Provedor de serviço de transporte por aplicativo precisa implementar essa funcionalidade.

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. A 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.

Observação: o uso de CreateTrip exige as credenciais da conta privilegiada mencionada na configuração do projeto do Cloud.

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 a 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.

Observação :o uso de UpdateTripRequest para atualizar o trip_status ou vehicle_id de uma viagem exige o credenciais da conta privilegiada do provedor.

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 Tripem 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, os vehicle_id é definido como o veículo em questão, e active_trips_only precisa ser definido como true.

• 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 como COMPLETE ou CANCELED, o Veículo não está incluído por SearchVehicles.

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.

Observação: Trip.vehicle_waypoints deve conter todos os waypoints restantes de todas viagens atribuídas ao veículo, mas sem waypoints adicionais. Esses waypoints devem ser ordenados de maneira que, em uma determinada viagem, o ponto de partida ocorre antes dos destinos intermediários, e todos eles são antes do ponto de entrega. Os waypoints da viagem EXCLUSIVE não podem se intercalar com em outras viagens.

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.

Observação :o Pub/Sub não garante a ordem das mensagens.

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 [e-mail] 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

• Veículo
• FieldMask

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