Membuat perjalanan penggabungan bersama

Dokumen ini menjelaskan cara membuat perjalanan berbagi tumpangan, menetapkan kolom yang benar, dan menetapkannya ke kendaraan untuk dipenuhi. Anda dianggap telah menyiapkan Fleet Engine, membuat kendaraan, memiliki aplikasi pengemudi yang berfungsi, dan jika perlu, aplikasi konsumen. Anda juga harus memahami berbagai skenario perjalanan yang tersedia untuk perjalanan on demand. Lihat panduan terkait berikut untuk mengetahuinya:

Dasar-dasar pembuatan perjalanan

Bagian ini menjelaskan detail permintaan yang diperlukan untuk membuat perjalanan di Fleet Engine. Anda mengeluarkan permintaan pembuatan menggunakan gRPC dan REST.

  • Metode CreateTrip(): gRPC atau REST
  • Pesan CreateTripRequest: gRPC saja

Kolom Perjalanan

Gunakan kolom berikut untuk membuat perjalanan di Fleet Engine. Anda dapat menggunakan kolom yang berbeda-beda untuk berbagai jenis perjalanan: perjalanan satu atau beberapa tujuan, perjalanan bolak-balik, atau perjalanan gabungan bersama. Anda dapat menyediakan kolom opsional saat membuat perjalanan, atau menetapkannya nanti saat memperbarui perjalanan.

Kolom perjalanan
Nama Wajib? Deskripsi
parent Ya String yang menyertakan project ID. ID ini harus sama dengan ID yang digunakan di seluruh integrasi Fleet Engine, dengan peran akun layanan yang sama.
trip_id Ya String yang Anda buat yang mengidentifikasi perjalanan ini secara unik. ID perjalanan memiliki batasan tertentu, seperti yang ditunjukkan dalam referensi.
trip_type Ya Tetapkan TripType ke nilai berikut untuk jenis perjalanan yang Anda buat:
  • Satu tujuan: Tetapkan ke SHARED atau EXCLUSIVE.
  • Multi-tujuan: Tetapkan ke EXCLUSIVE.
  • Berturut-turut: Tetapkan ke EXCLUSIVE.
  • Penggabungan bersama: Tetapkan ke SHARED.
pickup_point Ya Titik asal perjalanan.
Tujuan perantara Ya

Khusus perjalanan multi-tujuan: Daftar tujuan perantara yang dikunjungi pengemudi di antara pengambilan dan pengantaran. Seperti dropoff_point, kolom ini juga dapat ditetapkan nanti dengan memanggil UpdateTrip, tetapi perjalanan multi-tujuan menurut definisinya berisi tujuan perantara.
vehicle_waypoints Ya

Khusus perjalanan berbagi tumpangan: Kolom ini mendukung interleaving titik jalan dari beberapa perjalanan. File ini berisi semua titik jalan yang tersisa untuk kendaraan yang ditetapkan, serta titik jalan pengangkutan dan penurunan untuk perjalanan ini. Anda dapat menetapkan kolom ini dengan memanggil CreateTrip atau UpdateTrip. Anda juga dapat memperbarui titik jalan kendaraan melalui kolom waypoints dengan panggilan ke UpdateVehicle. Layanan tidak menampilkan informasi ini pada panggilan GetTrip karena alasan privasi.
number_of_passengers Tidak Jumlah penumpang dalam perjalanan.
dropoff_point Tidak Tujuan perjalanan.
vehicle_id Tidak ID kendaraan yang ditetapkan untuk perjalanan.

Contoh: membuat perjalanan penggabungan bersama

Contoh integrasi backend berikut menunjukkan cara membuat perjalanan dan menetapkannya ke kendaraan sebagai perjalanan gabungan bersama.

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

Perbarui perjalanan penggabungan bersama

Setiap perjalanan yang dibuat di Fleet Engine harus ditetapkan ke kendaraan agar Fleet Engine dapat menghitung perkiraan waktu tiba (ETA) perjalanan dan melacaknya. Anda dapat melakukannya selama pembuatan perjalanan atau nanti saat memperbarui perjalanan.

Untuk perjalanan penggabungan bersama, Anda harus menentukan urutan ke titik jalan yang belum dikunjungi dalam kumpulan titik jalan kendaraan (Trip.vehicle_waypoints) perjalanan. Fleet Engine menggunakan daftar ini untuk memperbarui titik jalan perjalanan secara otomatis untuk semua perjalanan di kumpulan bersama.

Misalnya, pertimbangkan dua perjalanan dengan pool bersama, Perjalanan A dan Perjalanan B:

  • Perjalanan A sedang dalam perjalanan ke lokasi pengantaran.
  • Perjalanan B kemudian ditambahkan ke kendaraan yang sama.

Dalam satu UpdateTripRequest untuk Perjalanan B, Anda menetapkan vehicleId, dan juga menetapkan Trip.vehicle_waypoints ke urutan titik jalan yang optimal: B Penjemputan → A Drop-off → B Drop-off.

  • Memanggil getVehicle() akan menampilkan remainingWaypoints yang berisi:
    B Penjemputan → Drop-off → B Drop-off.
  • Baik getTrip() maupun callback onTripRemainingWaypointsUpdated untuk Perjalanan A, akan menampilkan remainingWaypoints yang berisi:
    B Pengambilan → Pembuangan pelanggan.
  • getTrip() atau callback onTripRemainingWaypointsUpdated untuk Perjalanan B menampilkan remainingWaypoints yang berisi:
    B Penjemputan → A Pengantaran → B Pengantaran.

Contoh

Contoh integrasi backend berikut menunjukkan cara memperbarui perjalanan dengan ID kendaraan dan titik jalan untuk dua perjalanan pool bersama.

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

Langkah berikutnya