Paylaşılan havuz gezileri oluşturma

Bu belgede, paylaşımlı bir havuz gezisinin nasıl oluşturulacağı, doğru alanların nasıl ayarlanacağı ve bu gezinin yerine getirilmesi için bir araca nasıl atanacağı açıklanmaktadır. Fleet Engine'i ayarladığınız, araçlar oluşturduğunuz, çalışan bir sürücü uygulamanız ve isteğe bağlı olarak bir tüketici uygulamanız olduğu varsayılır. Ayrıca, isteğe bağlı geziler için kullanılabilen çeşitli gezi senaryolarını da bilmeniz gerekir. Bu konuda aşağıdaki ilgili rehberlere göz atın:

Gezi oluşturmayla ilgili temel bilgiler

Bu bölümde, Fleet Engine'de gezi oluşturmak için gereken istek ayrıntıları açıklanmaktadır. gRPC ve REST'i kullanarak bir oluşturma isteği gönderirsiniz.

  • CreateTrip() yöntemi: gRPC veya REST
  • CreateTripRequest mesajı: Yalnızca gRPC

Gezi Alanları

Fleet Engine'de seyahat oluşturmak için aşağıdaki alanları kullanın. Tek veya birden fazla varış noktası olan, arka arkaya ya da paylaşımlı yolculuklar gibi farklı türlerdeki yolculuklar için farklı alanlar kullanabilirsiniz. Geziyi oluştururken isteğe bağlı alanları doldurabilir veya geziyi güncellerken daha sonra ayarlayabilirsiniz.

Seyahat alanları
Ad Zorunlu mu? Açıklama
parent Evet Proje kimliğini içeren bir dize. Bu kimlik, aynı hizmet hesabı rolleriyle birlikte tüm Fleet Engine entegrasyonunuzda kullanılan kimlikle aynı olmalıdır.
trip_id Evet Bu geziyi benzersiz şekilde tanımlamak için oluşturduğunuz dize. Gezi kimlikleri, referansta belirtildiği gibi belirli kısıtlamalara tabidir.
trip_type Evet Oluşturduğunuz gezi türü için TripType'ı aşağıdaki değerlere ayarlayın:
  • Tek hedef: SHARED veya EXCLUSIVE olarak ayarlayın.
  • Çoklu hedef: EXCLUSIVE olarak ayarlayın.
  • Arka arkaya: EXCLUSIVE olarak ayarlayın.
  • Paylaşılan havuz: SHARED olarak ayarlayın.
pickup_point Evet Gezinin başlangıç noktası.
Ara hedefler Evet

Yalnızca çok varış noktalı yolculuklar: Sürücünün yolcu alma ve bırakma arasında ziyaret ettiği ara varış noktalarının listesi. dropoff_point ile aynı şekilde, bu alan daha sonra UpdateTrip çağrılarak da ayarlanabilir ancak tanım gereği çok varış noktalı bir yolculuk ara varış noktaları içerir.
vehicle_waypoints Evet

Yalnızca paylaşımlı havuz gezileri: Bu alan, birden fazla gezideki ara noktaların iç içe geçmesini destekler. Atanan araç için kalan tüm ara noktaların yanı sıra bu seyahatin teslim alma ve bırakma ara noktalarını içerir. Bu alanı CreateTrip veya UpdateTrip yöntemini çağırarak ayarlayabilirsiniz. Ayrıca, waypoints alanını kullanarak UpdateVehicle çağrısıyla araç yol noktalarını güncelleyebilirsiniz. Hizmet, gizlilik nedeniyle GetTrip çağrılarında bu bilgileri döndürmez.
number_of_passengers Hayır Gezideki yolcu sayısı.
dropoff_point Hayır Gezinin varış noktası.
vehicle_id Hayır Gezintiye atanan aracın kimliği.

Örnek: Paylaşımlı bir yolculuk oluşturma

Aşağıdaki arka uç entegrasyonu örneğinde, nasıl gezi oluşturulacağı ve bunun nasıl paylaşımlı yolculuk olarak bir araca atanacağı gösterilmektedir.

// 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;
}

Paylaşılan havuz gezilerini güncelleme

Fleet Engine'in seyahat tahmini varış zamanlarını hesaplayabilmesi ve seyahati izleyebilmesi için Fleet Engine'de oluşturulan tüm seyahatlerin bir araca atanması gerekir. Bu işlemi gezi oluşturma sırasında veya daha sonra geziyi güncellerken yapabilirsiniz.

Ortak havuz gezilerinde, gezinin araç yol noktaları koleksiyonundaki (Trip.vehicle_waypoints) ziyaret edilmemiş yol noktalarının sırasını belirtmeniz gerekir. Fleet Engine, bu listeyi ortak havuzdaki tüm gezilerin gezi yol noktalarını otomatik olarak güncellemek için kullanır.

Örneğin, iki ortak havuz gezisi olan A Gezisi ve B Gezisi'ni ele alalım:

  • A gezisi, bırakma konumuna doğru ilerliyor.
  • Ardından B yolculuğu aynı araca eklenir.

B Gezisi için bir UpdateTripRequest içinde vehicleId değerini ayarladınız ve Trip.vehicle_waypoints değerini de en uygun ara nokta sırasına göre ayarladınız: B Teslim Alma → A Teslim Etme → B Teslim Etme.

  • getVehicle() çağrıldığında şunları içeren remainingWaypoints döndürülür:
    B Teslim alma → A Bırakma → B Bırakma.
  • getTrip() veya onTripRemainingWaypointsUpdated geri çağırma işlevi, remainingWaypoints A Seyahati için şu öğeleri içeren
    B Teslim Alma → A Teslim Etme döndürür.
  • getTrip() veya B Seyahati için onTripRemainingWaypointsUpdated geri çağırma işlemi, şunları içeren remainingWaypoints döndürür:
    B Teslim Alma → A Terk Etme → B Terk Etme.

Örnek

Aşağıdaki arka uç entegrasyonu örneğinde, bir gezinin iki paylaşımlı havuz gezisi için araç kimliği ve rota noktalarıyla nasıl güncelleneceği gösterilmektedir.

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;
}

Sırada ne var?