Atualizar viagens e gerenciar o estado delas

Neste documento, descrevemos 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 waypoints.
  • Quando você atualiza 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 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

É possível atualizar qualquer um dos campos de viagem descritos em Campos de viagem em Criar uma viagem com um único destino. Por exemplo, depois de criar uma viagem, é comum primeiro encontrar um veículo e, em seguida, 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 autores de chamadas de API listarem os campos que uma solicitação deve ou atualizar. O uso de 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

É preciso configurar uma viagem com um ID de 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 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 de viagens

Especifique 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

Veja a seguir 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, você pode se deparar com um erro DEADLINE_EXCEEDED. Nesse caso, o estado do Fleet Engine é desconhecido. Para investigar isso, primeiro chame CreateTrip novamente usando o mesmo ID de viagem que você está tentando atualizar ou monitorar. Isso deve retornar 201 (CREATED) ou 409 (CONFLICT). Nesse último caso, a solicitação anterior foi bem-sucedida antes de DEADLINE_EXCEEDED.

Confira a lista de erros de rede no SDK do Consumidor para Android ou iOS.

A seguir