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 de ela ter sido 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 o gRPC e o REST.

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

Use as credenciais apropriadas para a conta de serviço do projeto, conforme descrito em Mecanismo de frota: papéis da conta de serviço.

Atualizar campos da 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 primeiro um veículo e, em seguida, atualizar o campo vehicle_id da viagem para associá-lo ao veículo que fará 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. O uso de um FieldMask evita trabalhos desnecessários e melhora o desempenho. O Fleet Engine usa máscaras 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 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 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 NEW e termina com um valor 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;
}

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

Processar erros de viagem

Ao atualizar ou encontrar viagens atuais, talvez você encontre um erro DEADLINE_EXCEEDED. Nesse caso, 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 retornará um erro 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