Atualizar viagens e gerenciar o estado delas

Este documento descreve como atualizar uma viagem e gerenciar seu estado, 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 uma veículo atribuído a uma viagem.

Noções básicas sobre atualização 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 de ela ter sido criada.
  • Quando o status da viagem é alterado: por exemplo, quando o veículo passa pelos waypoints.
  • Quando você atualiza os campos da viagem, como o número de passageiros e o um 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 apropriadas para a conta de serviço do seu projeto como descritos em Mecanismo de frota: papéis da conta de serviço.

Atualizar campos da viagem

Você pode atualizar qualquer um dos campos da viagem descritos em Campos da viagem em Criar uma viagem de destino única. Por exemplo, depois que você cria uma viagem, é comum praticar para encontrar 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

As máscaras de campo são uma maneira dos autores das chamadas da API listarem os campos que uma solicitação deve ou atualizar. Como usar um 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

Você precisa configurar uma viagem com um ID de veículo para que a frota possa rastrear o veículo ao longo do trajeto. O exemplo de código a seguir demonstra como atualize 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 uma das opções de enumeração TripStatus. e a distribuição dos valores dos dados. 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. A viagem ciclo de vida sempre começa com um valor de estado 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 de forma sucessiva. viagem 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;
}

Você pode ver outros exemplos de como atualizar viagens em Outros tipos de viagem. nesta seção.

Gerenciar erros de viagem

Ao atualizar ou encontrar viagens existentes, você pode se deparar com o caso de um Erro DEADLINE_EXCEEDED. Nesse caso, o estado da frota é desconhecido. Para investigar isso, primeiro chame CreateTrip de novo usando o mesmo ID de viagem que você estão tentando atualizar ou monitorar. Isso retornará um erro 201 (CREATED) ou 409 (CONFLITO). No último caso, a solicitação anterior foi bem-sucedida antes de DEADLINE_EXCEEDED:

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

A seguir