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 os campos relevantes de 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 atualizações de viagem

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 referência.
  • Quando você atualiza campos da viagem, como o número de passageiros e o ponto de desembarque.

Para atualizar uma viagem, envie uma solicitação usando gRPC ou 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

É possível atualizar qualquer um dos campos de viagem descritos em Campos de viagem em Criar uma viagem para um único destino. Por exemplo, depois de criar uma viagem, é comum primeiro encontrar um veículo e depois atualizar o campo vehicle_id da viagem para associá-la ao veículo que vai realizar a viagem.

Usar máscaras de campo

As máscaras de campo são uma maneira de os chamadores de API listarem os campos que uma solicitação deve ou atualizar. Usar uma FieldMask evita trabalhos desnecessários e melhora a performance. O Fleet Engine usa máscaras de campo para atualizar campos em todos os recursos.

Atualizar a viagem com o ID do veículo

É preciso configurar uma viagem com um ID do veículo para que o Fleet Engine possa rastrear o veículo ao longo da rota. O exemplo de código a seguir demonstra como atualizar a viagem com um ID de 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 das viagens

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 NEW e termina com um valor COMPLETE ou CANCELED.

Exemplo de atualização de viagem

O exemplo a seguir demonstra como atualizar o estado de 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.

Resolver erros de viagem

Ao atualizar ou encontrar viagens atuais, talvez você encontre um erro DEADLINE_EXCEEDED, em que o estado do Fleet Engine é desconhecido. Para investigar isso, chame CreateTrip novamente usando o mesmo ID da viagem que você está tentando atualizar ou monitorar. Isso precisa retornar 201 (CREATED) ou 409 (CONFLICT). No último caso, a solicitação anterior foi concluída antes de DEADLINE_EXCEEDED.

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

A seguir