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.

Princípios básicos das 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.
  • Ao atualizar os 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 de destino único. 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 o trajeto.

Usar máscaras de campo

As máscaras de campo são uma maneira de os autores de chamadas 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

É necessário configurar uma viagem com um ID do veículo para que o Fleet Engine possa rastrear o veículo ao longo do trajeto. O exemplo de código a seguir 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 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, atualize 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 de COMPLETE ou CANCELED.

Exemplo de atualização de viagem

A demonstração a seguir mostra 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.

Tratar erros de viagem

Ao atualizar ou encontrar viagens atuais, talvez você encontre um caso de erro DEADLINE_EXCEEDED, em que o estado do Fleet Engine é desconhecido. Para investigar isso, primeiro chame CreateTrip novamente usando o mesmo ID da viagem que você está tentando atualizar ou monitorar. Isso vai retornar um código 201 (CREATED) ou 409 (CONFLICT). No último 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