Atualizar viagens e gerenciar o estado delas

Este documento descreve como atualizar uma viagem e gerenciar o estado dela, o que envolve o uso de uma máscara de campo para definir campos relevantes para uma viagem. Ele pressupõe que você configurou o Fleet Engine conforme descrito neste site e está trabalhando com um veículo atribuído a uma viagem.

Noções básicas sobre a atualização de viagens

Seu sistema usa o Fleet Engine para atualizar uma viagem nas seguintes situações:

  • Ao atribuir um veículo a uma viagem depois que ela é criada.
  • Quando o status da viagem muda. Por exemplo, quando o veículo passa por pontos de passagem.
  • Quando você atualiza campos de viagem, como o número de passageiros e o ponto de entrega.

Para atualizar uma viagem, envie uma solicitação usando gRPC e REST.

  • Método UpdateTrip(): gRPC ou REST
  • Mensagem UpdateTripRequest: somente gRPC

Use as credenciais adequadas para a conta de serviço do seu projeto, conforme descrito em Fleet Engine: papéis da conta de serviço.

Atualizar campos de viagem

Você pode atualizar qualquer um dos campos de viagem descritos em Campos de viagem em Criar uma viagem de destino único. Por exemplo, depois de criar uma viagem, é uma prática comum encontrar um veículo e atualizar o campo vehicle_id da viagem para associá-lo ao veículo que vai realizar a viagem.

Usar máscaras de campo

Máscaras de campo são uma forma de os autores da chamada à API listarem os campos que uma solicitação deve atualizar ou não. Usar uma FieldMask evita trabalhos desnecessários e melhora o desempenho. O Fleet Engine usa máscaras de campo para atualizar campos em todos os recursos.

Atualizar a viagem com o ID do veículo

É necessário configurar uma viagem com um ID de veículo para que o Fleet Engine possa rastrear o veículo ao longo da rota. O exemplo de código abaixo demonstra como atualizar a viagem com um ID do veículo.

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "trip-8241890";

String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_ID;

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// The trip settings to update.
Trip trip = Trip.newBuilder()
    .setVehicleId("8241890")
    .build();

// The trip update request.
UpdateTripRequest updateTripRequest =
    UpdateTripRequest.newBuilder()      // No need for the header.
        .setName(tripName)
        .setTrip(trip)
        .setUpdateMask(FieldMask.newBuilder().addPaths("vehicle_id"))
        .build();

// Error handling.
// If the Fleet Engine has both a trip and vehicle with IDs, and if the
// credentials validate, then the service updates the trip.
try {
  Trip updatedTrip = tripService.updateTrip(updateTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:                    // Neither the trip nor vehicle exist.
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

Gerenciar o estado da viagem

Você especifica o estado de uma viagem usando um dos valores de enumeração TripStatus. Quando o estado de uma viagem muda, por exemplo, de ENROUTE_TO_PICKUP para ARRIVED_AT_PICKUP, você atualiza o estado da viagem no Fleet Engine. O ciclo de vida da viagem sempre começa com um valor de estado de NEW e termina com um valor de COMPLETE ou CANCELED.

Exemplo de atualização de viagem

O exemplo a seguir demonstra como atualizar o estado da viagem para uma viagem consecutiva no Fleet Engine.

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "trip-8241890";

String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_ID;

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// Trip settings to be updated.
Trip trip = Trip.newBuilder()
    .setTripStatus(TripStatus.ARRIVED_AT_PICKUP)
    .build();

// Trip update request
UpdateTripRequest updateTripRequest = UpdateTripRequest.newBuilder()
    .setName(tripName)
    .setTrip(trip)
    .setUpdateMask(FieldMask.newBuilder().addPaths("trip_status"))
    .build();

// Error handling.
try {
  Trip updatedTrip = tripService.updateTrip(updateTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:            // The trip doesn't exist.
      break;
    case FAILED_PRECONDITION:  // The given trip status is invalid.
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

Confira outros exemplos de como atualizar viagens na seção Outros tipos de viagem.

Processar erros de viagem

Ao atualizar ou encontrar viagens atuais, você pode encontrar um caso de um erro DEADLINE_EXCEEDED, em que o estado do Fleet Engine é desconhecido. Para investigar isso, chame CreateTrip novamente usando o mesmo ID de viagem que você está tentando atualizar ou monitorar. Isso deve retornar um 201 (CREATED) ou 409 (CONFLICT). No segundo caso, a solicitação anterior foi bem-sucedida antes de DEADLINE_EXCEEDED.

Consulte a lista de erros de rede no SDK do consumidor para Android ou iOS.

A seguir