Criar viagens de pooling compartilhadas

Este documento descreve como criar uma viagem compartilhada, definir os campos corretos e atribuir a um veículo para ser atendida. Ele pressupõe que você configurou o Fleet Engine, criou veículos, tem um app para motoristas em funcionamento e, opcionalmente, um app para o consumidor. Também é preciso conhecer os vários cenários de viagem disponíveis para viagens sob demanda. Consulte os guias relacionados abaixo para isso:

Conceitos básicos da criação de viagens

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

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

Campos da viagem

Use os campos a seguir para criar uma viagem no Fleet Engine. É possível usar campos diferentes para os diferentes tipos de viagens: com um ou vários destinos, viagens consecutivas ou compartilhadas. 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
pai 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 as mesmas funções da conta de serviço.
trip_id Sim Uma string que você cria 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 com 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.
  • Conversas: defina como EXCLUSIVE.
  • Compartilhamento de recursos: defina como SHARED.
pickup_point Sim 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 coleta e a entrega. Assim como o dropoff_point, esse campo também pode ser definido mais tarde chamando UpdateTrip, mas uma viagem com vários destinos contém destinos intermediários por definição.
vehicle_waypoints Sim

Somente viagens compartilhadas: esse campo aceita a intercalação de pontos de passagem de várias viagens. Ele contém todos os waypoints restantes do veículo atribuído, além dos waypoints de embarque e desembarque dessa viagem. Para definir esse campo, chame CreateTrip ou UpdateTrip. Também é possível atualizar os pontos de passagem 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 em pool compartilhada

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 compartilhada.

// 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 compartilhadas

Qualquer viagem criada no Fleet Engine precisa ser atribuída a um veículo para que o Fleet Engine possa calcular os horários estimados de chegada e rastrear a viagem. Você pode fazer isso durante a criação da viagem ou depois, ao atualizá-la.

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

Por exemplo, considere duas viagens compartilhadas, Viagem A e Viagem B:

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

Em uma UpdateTripRequest para a Viagem B, você define vehicleId e também define Trip.vehicle_waypoints na ordem ideal do waypoint: B Retirada → A Desembarque → B Desembarque.

  • Chamar getVehicle() retorna remainingWaypoints que contém:
    B Pickup → A Drop-off → B Drop-off.
  • getTrip() ou o callback onTripRemainingWaypointsUpdated para a Viagem A retorna remainingWaypoints que contém:
    B Pickup → A Drop-off.
  • getTrip() ou o callback onTripRemainingWaypointsUpdated da Viagem B retorna remainingWaypoints que contém:
    B Retirada → A Desembarque → B Desembarque.

Exemplo

O exemplo de integração de back-end a seguir demonstra como atualizar uma viagem com o ID do veículo e waypoints para 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