Cómo crear viajes con varios destinos

En este documento, se describe cómo crear un viaje con varios destinos, establecer los campos correctos y asignarlo a un vehículo para que lo realice. Se supone que ya configuraste Fleet Engine, creaste vehículos, tienes una app para el conductor que funciona y, de manera opcional, una app para el consumidor. También debes conocer los distintos casos de uso de viajes disponibles para los viajes a pedido. Consulta las siguientes guías relacionadas para obtener más información:

• Configura Fleet Engine
• Crea un vehículo
• Situaciones de viaje en la descripción general de Viajes a pedido

Conceptos básicos sobre la creación de viajes

En esta sección, se describen los detalles de la solicitud necesarios para crear un viaje en Fleet Engine. Emite una solicitud de creación con gRPC o REST.

• Método CreateTrip(): gRPC o REST
• Mensaje CreateTripRequest: Solo gRPC

Nota: Para usar CreateTrip(), se requieren las credenciales de la cuenta con privilegios que se menciona en Fleet Engine: Roles de la cuenta de servicio.

Campos de viaje

Usa los siguientes campos para crear un viaje en Fleet Engine. Puedes usar diferentes campos para los distintos tipos de viajes: de un solo destino o varios, consecutivos o viajes compartidos. Puedes proporcionar los campos opcionales cuando creas el viaje o puedes establecerlos más adelante cuando actualices el viaje.

Campos de viaje

Nombre	¿Obligatorio?	Descripción
parent	Sí	Es una cadena que incluye el ID del proyecto. Este ID debe ser el mismo que se usa en toda la integración de Fleet Engine, con los mismos roles de cuenta de servicio.
trip_id	Sí	Es una cadena que creas y que identifica de forma única este viaje. Los IDs de viaje tienen ciertas restricciones, como se indica en la referencia.
trip_type	Sí	Establece TripType en los siguientes valores para el tipo de viaje que estás creando: Un solo destino: Se establece en SHARED o EXCLUSIVE. Multi-destination: Se establece en EXCLUSIVE. Back-to-back: Se establece en EXCLUSIVE. Agrupación compartida: Se establece en SHARED.
pickup_point	Sí	Es el punto de origen del viaje.
Destinos intermedios	Sí	Solo para viajes con varios destinos: Es la lista de destinos intermedios que el conductor visita entre la partida y el destino. Al igual que con dropoff_point, este campo también se puede establecer más adelante llamando a UpdateTrip, pero, por definición, un viaje con varios destinos contiene destinos intermedios.
vehicle_waypoints	Sí	Solo viajes compartidos: Este campo admite la intercalación de las paradas de varios viajes. Contiene todos los puntos de referencia restantes para el vehículo asignado, así como los puntos de referencia de partida y destino de este viaje. Puedes configurar este campo llamando a CreateTrip o UpdateTrip. También puedes actualizar los puntos de referencia del vehículo a través del campo waypoints con una llamada a UpdateVehicle. El servicio no devuelve esta información en las llamadas a GetTrip por motivos de privacidad.
number_of_passengers	No	Es la cantidad de pasajeros en el viaje.
dropoff_point	No	Es el destino del viaje.
vehicle_id	No	Es el ID del vehículo asignado al viaje.

Ejemplo: Cómo crear un viaje con varios destinos

En el siguiente ejemplo, se muestra cómo crear un viaje exclusivo con varios destinos que tiene un punto de partida, un punto de destino y un destino intermedio.

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "multi-destination-trip-A";

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// Trip initial settings.
String parent = "providers/" + PROJECT_ID;

Trip trip = Trip.newBuilder()
    .setTripType(TripType.EXCLUSIVE)
    .setPickupPoint(
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder()
                .setLatitude(-6.195139).setLongitude(106.820826)))
    .setNumberOfPassengers(1)
    .setDropoffPoint(
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder()
                .setLatitude(-6.1275).setLongitude(106.6537)))
    // Add the list of intermediate destinations.
    .addAllIntermediateDestinations(
        ImmutableList.of(
            TerminalLocation.newBuilder().setPoint(
                LatLng.newBuilder()
                    .setLatitude(-6.195139).setLongitude(106.820826)).build()))
    .build();

// Create the Trip request.
CreateTripRequest createTripRequest = CreateTripRequest.newBuilder()
    .setParent(parent)
    .setTripId(TRIP_ID)  // Trip ID assigned by the Provider server.
    .setTrip(trip)       // Initial state is NEW.
    .build();

// Error handling.
try {
  Trip createdTrip =
      tripService.createTrip(createTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case ALREADY_EXISTS:  // Trip already exists.
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

Experimental: Como función experimental, el campo TerminalLocation (gRPC o REST) ahora admite el uso de place (gRPC o REST), ya sea junto con LatLng o en lugar de este.

Actualiza un viaje con varios destinos

Debes configurar el viaje con un ID de vehículo para que Fleet Engine pueda hacer un seguimiento del vehículo a lo largo de su ruta. Para obtener detalles sobre cómo actualizar un viaje, consulta Actualiza viajes y administra su estado.

Si no especificaste un destino intermedio o de descenso cuando creaste el viaje, puedes hacerlo en este momento.

Nota: Cada vez que configuras o actualizas intermediate_destinations en un viaje, Fleet Engine completa intermediate_destinations_version en la entidad de viaje creada. Debes almacenar en caché este campo en tu sistema y pasar el elemento UpdateTripRequest cuando actualices el elemento intermediate_destination_index más adelante. Esto mantiene las ubicaciones intermedias sincronizadas entre el cliente del conductor y Fleet Engine.

Ejemplo de actualización de viaje

En el siguiente ejemplo, se muestra cómo actualizar un viaje para agregar una lista de destinos intermedios y establecer un ID de vehículo.

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "multi-destination-trip-A";

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

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// The trip settings to be updated.
Trip trip = Trip.newBuilder()
    // Add the list of intermediate destinations.
    .addAllIntermediateDestinations(
        ImmutableList.of(
            TerminalLocation.newBuilder().setPoint(
                LatLng.newBuilder()
                    .setLatitude(-6.195139).setLongitude(106.820826)).build()))
    .setVehicleId("8241890")
    .build();

// The trip update request.
UpdateTripRequest updateTripRequest = UpdateTripRequest.newBuilder()
    .setName(tripName)
    .setTrip(trip)
    .setUpdateMask(
        FieldMask.newBuilder()
            .addPaths("intermediate_destinations")
            .addPaths("vehicle_id")
            .build())
    .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 PERMISSION_DENIED:
      break;
  }
  return;
}

Experimental: Como función experimental, el campo TerminalLocation (gRPC o REST) ahora admite el uso de place (gRPC o REST), ya sea junto con LatLng o en lugar de este.

Administra el estado del viaje para viajes con varios destinos

Para especificar el estado de un viaje, usa uno de los valores de enumeración TripStatus. Cuando cambia el estado de un viaje, por ejemplo, de ENROUTE_TO_PICKUP a ARRIVED_AT_PICKUP, debes actualizar el estado del viaje en Fleet Engine. El estado del viaje siempre comienza con un valor de NEW y termina con un valor de COMPLETE o CANCELED.

En el caso de un viaje con varios destinos, además de actualizar el estado del viaje como lo harías para un viaje con un solo destino, también debes actualizar lo siguiente cada vez que tu vehículo llegue a un destino intermedio:

• intermediateDestinationIndex
• intermediateDestinationsVersion

Para ello, usa los siguientes valores de la enumeración TripStatus.

• ENROUTE_TO_PICKUP
• ARRIVED_AT_PICKUP
• ENROUTE_TO_INTERMEDIATE_DESTINATION
• ARRIVED_AT_INTERMEDIATE_DESTINATION
• ENROUTE_TO_DROPOFF
• COMPLETE

Nota: El viaje debe pasar por ENROUTE_TO_INTERMEDIATE_DESTINATION y ARRIVED_AT_INTERMEDIATE_DESTINATION una vez por cada destino intermedio.

Ejemplo de viaje con destinos intermedios

A continuación, se muestra cómo crear un viaje con varios destinos que ya pasó por el punto de partida y ahora está en camino a su primer destino intermedio.

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "multi-destination-trip-A";

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

// Get the trip object from either the Fleet Engine or storage.
Trip trip = …;

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// The trip settings to be updated.
Trip trip = Trip.newBuilder()
    // Trip status cannot return to a previous state once it has passed.
    .setTripStatus(TripStatus.ENROUTE_TO_INTERMEDIATE_DESTINATION)

    // Enroute to the first intermediate destination.
    .setIntermediateDestinationIndex(0)

    // You must provide an intermediate_destinations_version to ensure that you
    // have the same intermediate destinations list as the Fleet Engine.
    .setIntermediateDestinationsVersion(
         trip.getIntermediateDestinationsVersion())
    .build();

// The trip update request.
UpdateTripRequest updateTripRequest = UpdateTripRequest.newBuilder()
    .setName(tripName)
    .setTrip(trip)
    .setUpdateMask(
        FieldMask.newBuilder()
            .addPaths("trip_status")
            .addPaths("intermediate_destination_index")
            // intermediate_destinations_version must not be in the update mask.
            .build())
    .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:  // Either the trip status is invalid, or the
                               // intermediate_destinations_version doesn't
                               // match Fleet Engine's.
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

¿Qué sigue?

• Cómo crear viajes consecutivos
• Configura el SDK de Driver