Esta página foi traduzida pela API Cloud Translation.

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ê tenha configurado o Fleet Engine, criado veículos, tenha um app de motorista funcionando e, opcionalmente, um app de consumidor. Você também precisa estar familiarizado com os vários cenários de viagem disponíveis para viagens sob demanda. Consulte os guias relacionados a seguir:

Configurar o Fleet Engine
Criar um veículo
Cenários de viagem na visão geral das Viagens sob demanda

Conceitos básicos da 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.

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

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: 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
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 as mesmas funções da conta de serviço.
trip_id	Sim	Uma string criada por você que identifica exclusivamente essa viagem. Os IDs de viagem têm algumas restrições, conforme indicado na referência.
trip_type	Sim	Defina 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`. Back-to-back: 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 pontos de referência restantes do veículo atribuído, bem como os pontos de referência de retirada e entrega dessa viagem. É possível definir esse campo chamando `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 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, quando a atualizar.

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 entrega.
A Viagem B é adicionada ao mesmo veículo.

Em um UpdateTripRequest para Viagem B, você define vehicleId e também define Trip.vehicle_waypoints para a ordem de ponto de passagem ideal: B _Pickup → A _Drop-off → B _Drop-off.

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 para Viagem B retorna remainingWaypoints que contém:
B _Pickup → A _Drop-off → B _Drop-off.

Exemplo

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

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

Configurar o SDK do driver