Atualizar campos de veículos

Este documento aborda campos importantes que podem ser atualizados ao criar e gerenciar veículos.

  • vehicle_state: determina a disponibilidade do veículo para novas viagens.
  • vehicle_type: campo obrigatório ao criar um veículo. O campo também pode servir como critério de filtro para correspondências de veículos. Consulte Criar um veículo para saber como definir esse campo.
  • attributes[]: uma matriz opcional do tipo VehicleAttribute. Use-os para definir critérios personalizados que melhoram o comportamento de filtragem ao pesquisar ou listar veículos.
  

Para uma lista completa de campos de veículos, consulte:

Campo de estado do veículo

O sistema pode definir o estado do veículo como OFFLINE ou ONLINE. Por exemplo, é possível definir o estado do veículo como ONLINE todos os dias às 9h e como OFFLINE todos os dias às 17h.

Modo off-line Modo ONLINE
Use OFFLINE para indicar que um veículo não está aceitando novas viagens. O veículo ainda pode concluir as viagens atribuídas enquanto estiver nesse estado.
  • Um Vehicle criado no estado ONLINE pode ser retornado imediatamente em resposta às consultas SearchVehicles. Consulte Pesquisar veículos para mais detalhes.
  • Os veículos criados no estado ONLINE precisam usar o campo last_location na chamada CreateVehicle.

Campo de atributos do veículo

Use o campo attributes do veículo para criar critérios personalizados que permitam que seus consumidores ou operadores de frota encontrem veículos na sua frota em uma variedade maior de critérios de pesquisa. Isso melhora os recursos dos seus apps para fornecer correspondências de veículos melhores do que as que você teria usando critérios de pesquisa baseados apenas em outros campos de veículos. Cada veículo pode ter no máximo 100 atributos, e cada um precisa ter uma chave exclusiva. Os valores podem ser strings, booleanos ou números.

Por exemplo, é possível declarar um atributo personalizado chamado class para diferenciar os veículos de transporte por aplicativo em vários níveis de classe. Use os seguintes valores de string para representar os níveis de classe do veículo: ECONOMY, STANDARD e LUXURY.

No entanto, os valores de atributos personalizados não precisam ser mutuamente exclusivos. Você pode usar critérios como aceita animais de estimação, não fumante e pode fazer viagens mais longas. Cada um deles pode ser um atributo personalizado separado que usa valores booleanos. Um determinado veículo pode receber todos esses três atributos personalizados, além do atributo personalizado class definido com o valor de string apropriado.

Usar atributos dessa forma pode fornecer uma ampla variedade de recursos úteis para encontrar veículos para viagens com necessidades específicas. Para instruções sobre como usar atributos personalizados como filtros de consulta, consulte Pesquisar veículos.

Atualizar atributos do veículo

É possível atualizar os atributos do veículo usando UpdateVehicle ou UpdateVehicleAttributes. Cada chave attributes pode ter apenas um valor por veículo. Declare atributos personalizados de veículos usando attributes na máscara de campo e forneça valores com base no método abaixo.

UpdateVehicle UpdateVehicleAttributes
Essa API não permite atualizar apenas um atributo. Ao usar esse método, qualquer uso do campo attributes na máscara de campo resulta na redeclaração do conjunto inteiro de atributos do veículo. Isso resulta na substituição de qualquer atributo preexistente que não esteja explicitamente incluído na máscara de campo. Se você usar esse método para declarar um novo atributo personalizado, também será necessário declarar novamente todos os atributos personalizados que você quer que o veículo mantenha. Se você excluir o attributes na máscara de campo, esse método vai deixar os atributos personalizados atuais como definidos anteriormente para o veículo. Se você usar attributes na máscara de campo, mas sem definir valores, isso equivale a remover todos os atributos personalizados do veículo. Esse método aceita uma lista específica de atributos para atualização. A solicitação atualiza ou adiciona apenas os atributos especificados na máscara de campo. Os atributos preexistentes que não forem especificados vão permanecer inalterados.

Exemplo de atualização de campos de veículos

Nesta seção, mostramos como atualizar os campos do veículo usando UpdateVehicleRequest, que inclui um update_mask para indicar quais campos atualizar. Consulte a documentação de buffers de protocolo sobre máscaras de campo para mais detalhes.

As atualizações em campos que não sejam last_location exigem privilégios de administrador on-demand do Fleet Engine.

Exemplo: ativar um novo tipo de viagem e um atributo personalizado

Este exemplo ativa as viagens back_to_back para o veículo e também especifica um novo atributo: class. Como observado em Atualizar atributos do veículo, atualizar o campo attributes usando essa abordagem exige que você indique todos os atributos personalizados que quer manter. Portanto, o exemplo mostra um valor cash_only gravado para evitar que ele seja substituído durante uma operação de atualização que especifica o campo attributes.

Para atualizar apenas o valor de um par de atributos de chave-valor, use o método UpdateVehicleAttributes e não inclua o campo attribute na máscara de campo da solicitação UpdateVehicle.

Consulte a referência de providers.vehicles.update para gRPC e REST.

gRPC

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("class").setValue("ECONOMY").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();

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.

REST

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": "class", "value": "LUXURY"},
      {"key": "cash_only", "value": "false"}
    ],
    "backToBackEnabled": true
}
EOM

A seguir