Criar viagens de pooling compartilhadas

Este documento descreve como criar uma viagem de compartilhamento, definir os campos corretos e atribuí-la a um veículo para ser concluída. Ele pressupõe que você já configurou o Fleet Engine, criou veículos, tem um app para motoristas em funcionamento e, opcionalmente, um aplicativo para o consumidor. Você também precisa estar familiarizado com os vários cenários de viagem disponíveis para viagens sob demanda. Consulte os seguintes guias relacionados:

Noções básicas sobre a criação de viagens

Esta seção descreve os detalhes da solicitação necessários para criar uma viagem no Fleet Engine. Você emite uma solicitação de criação usando gRPC e REST.

  • CreateTrip() método: gRPC ou REST
  • Mensagem CreateTripRequest: gRPC somente

Campos de viagem

Use os campos a seguir para criar uma viagem no Fleet Engine. É possível usar campos diferentes para os diferentes tipos de viagens: de destino único ou múltiplo, consecutivas ou de compartilhamento. Você pode fornecer os campos opcionais ao criar a viagem ou defini-los mais tarde ao atualizar a viagem.

Campos de viagem
Nome Obrigatório? Descrição
parent Sim Uma string que inclui o ID do projeto. Esse ID precisa ser o mesmo usado em toda a integração do Fleet Engine, com os mesmos papéis da conta de serviço
trip_id Sim Uma string que você cria e que identifica exclusivamente essa viagem. Os IDs de viagem têm algumas restrições, conforme indicado na referência.
trip_type Sim Defina o TripType como os seguintes valores para o tipo de viagem que você está criando:
  • Destino único: defina como SHARED ou EXCLUSIVE.
  • Vários destinos: defina como EXCLUSIVE.
  • Consecutivas: defina como EXCLUSIVE.
  • Compartilhamento: defina como SHARED.
pickup_point Sim O ponto de origem da viagem.
Destinos intermediários Sim

Somente viagens com vários destinos: a lista de destinos intermediários que o motorista visita entre a retirada e o desembarque. Assim como dropoff_point, esse campo também pode ser definido mais tarde chamando UpdateTrip, mas uma viagem com vários destinos, por definição, contém destinos intermediários.
vehicle_waypoints Sim

Somente viagens de compartilhamento: esse campo oferece suporte à intercalação dos waypoints de várias viagens. Ele contém todos os waypoints restantes do veículo atribuído, bem como os waypoints de embarque e desembarque dessa viagem. É possível definir esse campo chamando CreateTrip ou UpdateTrip. Também é possível atualizar os waypoints do veículo pelo campo waypoints com uma chamada para UpdateVehicle. O serviço não retorna essas informações em chamadas GetTrip por motivos de privacidade.
number_of_passengers Não O número de passageiros na viagem.
dropoff_point Não O destino da viagem.
vehicle_id Não O ID do veículo atribuído à viagem.

Exemplo: criar uma viagem de compartilhamento

O exemplo de integração de back-end a seguir demonstra como criar uma viagem e atribuí-la a um veículo como uma viagem de compartilhamento.

// Vehicle with VEHICLE_ID ID is already created and it is assigned Trip A.

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "shared-trip-A";
static final String VEHICLE_ID = "your-vehicle-id";
static final String TRIP_A_ID = "trip-a-id";
static final String TRIP_B_ID = "trip-b-id";

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

String parent = "providers/" + PROJECT_ID;

LatLng tripBPickup =
    LatLng.newBuilder().setLatitude(-12.12314).setLongitude(88.142123).build();
LatLng tripBDropoff =
    LatLng.newBuilder().setLatitude(-14.12314).setLongitude(90.142123).build();

TerminalLocation tripBPickupTerminalLocation =
    TerminalLocation.newBuilder().setPoint(tripBPickup).build();
TerminalLocation tripBDropoffTerminalLocation =
    TerminalLocation.newBuilder().setPoint(tripBDropoff).build();

// TripA already exists and it's assigned to a vehicle with VEHICLE_ID ID.
Trip tripB = Trip.newBuilder()
    .setTripType(TripType.SHARED)
    .setVehicleId(VEHICLE_ID)
    .setPickupPoint(tripBPickupTerminalLocation)
    .setDropoffPoint(tripBDropoffTerminalLocation)
    .addAllVehicleWaypoints(
        // This is where you define the arrival order for unvisited waypoints.
        // If you don't specify an order, then the Fleet Engine adds Trip B's
        // waypoints to the end of Trip A's.
        ImmutableList.of(
            // Trip B's pickup point.
            TripWaypoint.newBuilder()
                .setLocation(tripBPickupTerminalLocation)
                .setTripId(TRIP_B_ID)
                .setWaypointType(WaypointType.PICKUP_WAYPOINT_TYPE)
                .build(),
            // Trip A's drop-off point.
            TripWaypoint.newBuilder()
                .setLocation(tripA.getDropoffPoint())
                .setTripId(TRIP_A_ID)
                .setWaypointType(WaypointType.DROP_OFF_WAYPOINT_TYPE)
                .build(),
            // Trip B's drop-off point.
            TripWaypoint.newBuilder()
                .setLocation(tripBDropoffTerminalLocation)
                .setTripId(TRIP_B_ID)
                .setWaypointType(WaypointType.DROP_OFF_WAYPOINT_TYPE)
                .build()))
    .build();

// Create Trip request
CreateTripRequest createTripRequest = CreateTripRequest.newBuilder()
    .setParent(parent)
    .setTripId(TRIP_B_ID)
    .setTrip(tripB)
    .build();

try {
  // createdTrip.remainingWaypoints will contain shared-pool waypoints.
  // [tripB.pickup, tripA.dropoff, tripB.dropoff]
  Trip createdTrip = tripService.createTrip(createTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case ALREADY_EXISTS:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

Atualizar viagens de compartilhamento

Qualquer viagem criada no Fleet Engine precisa ser atribuída a um veículo para que o Fleet Engine calcule os ETAs da viagem e a rastreie. É possível fazer isso durante a criação da viagem ou mais tarde, ao atualizar a viagem.

Para viagens de compartilhamento, é necessário especificar uma ordem para os waypoints não visitados na coleção de waypoints do veículo (Trip.vehicle_waypoints) da viagem. O Fleet Engine usa essa lista para atualizar automaticamente os waypoints de todas as viagens no pool compartilhado.

Por exemplo, considere duas viagens de pool compartilhado, a viagem A e a viagem B:

  • A viagem A está a caminho do local de desembarque.
  • A viagem B é adicionada ao mesmo veículo.

Em um UpdateTripRequest para viagem B, você define o vehicleId, e também define Trip.vehicle_waypoints para a ordem ideal de waypoints: retirada B → desembarque A → desembarque B.

  • Chamar getVehicle() retorna remainingWaypoints que contêm:
    B embarque → A desembarque → B desembarque.
  • getTrip() ou o onTripRemainingWaypointsUpdated callback para viagem A retorna remainingWaypoints que contêm:
    embarque B → desembarque A.
  • getTrip() ou o onTripRemainingWaypointsUpdated callback para a viagem B retorna remainingWaypoints que contêm:
    embarque B → desembarque A → desembarque B.

Exemplo

O exemplo de integração de back-end a seguir demonstra como atualizar uma viagem com o ID do veículo e os waypoints de duas viagens de pool compartilhado.

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_A_ID = "share-trip-A";
static final String TRIP_B_ID = "share-trip-B";
static final String VEHICLE_ID = "Vehicle";

String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_B_ID;

// Get Trip A and Trip B objects from either the Fleet Engine or storage.
Trip tripA = …;
Trip tripB = …;

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// The trip settings to update.
Trip trip = Trip.newBuilder()
    .setVehicleId(VEHICLE_ID)
    .addAllVehicleWaypoints(
        // This is where you define the arrival order for unvisited waypoints.
        // If you don't specify an order, then the Fleet Engine adds Trip B's
        // waypoints to the end of Trip A's.
        ImmutableList.of(
            // Trip B's pickup point.
            TripWaypoint.newBuilder()
                .setLocation(tripB.getPickupPoint())
                .setTripId(TRIP_B_ID)
                .setWaypointType(WaypointType.PICKUP_WAYPOINT_TYPE)
                .build(),
            // Trip A's drop-off point.
            TripWaypoint.newBuilder()
                .setLocation(tripA.getDropoffPoint())
                .setTripId(TRIP_A_ID)
                .setWaypointType(WaypointType.DROP_OFF_WAYPOINT_TYPE)
                .build(),
            // Trip B's drop-off point.
            TripWaypoint.newBuilder()
                .setLocation(tripB.getDropoffPoint())
                .setTripId(TRIP_B_ID)
                .setWaypointType(WaypointType.DROP_OFF_WAYPOINT_TYPE)
                .build()))
    .build();

// The trip update request.
UpdateTripRequest updateTripRequest = UpdateTripRequest.newBuilder()
    .setName(tripName)
    .setTrip(trip)
    .setUpdateMask(FieldMask.newBuilder()
        .addPaths("vehicle_id")
        .addPaths("vehicle_waypoints"))
    .build();

// Error handling. If Fleet Engine has both a trip and vehicle with the IDs,
// and if the credentials validate, and if the given vehicle_waypoints list
// is valid, 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:          // Either the trip or vehicle does not exist.
      break;
    case PERMISSION_DENIED:
      break;
    case INVALID_REQUEST:    // vehicle_waypoints is invalid.
      break;
  }
  return;
}

A seguir