Membuat perjalanan multi-tujuan

Dokumen ini menjelaskan cara membuat perjalanan multi-tujuan, menetapkan kolom yang benar, dan menetapkannya ke kendaraan untuk dipenuhi. Ini mengasumsikan bahwa Anda telah menyiapkan Fleet Engine, membuat kendaraan, memiliki aplikasi pengemudi yang berfungsi, dan secara opsional, aplikasi konsumen. Anda juga harus memahami berbagai skenario perjalanan yang tersedia untuk perjalanan on-demand. Lihat panduan terkait berikut untuk mengetahuinya:

• Menyiapkan Fleet Engine
• Membuat kendaraan
• Skenario perjalanan di ringkasan Perjalanan on-demand

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: khusus gRPC

Catatan: Penggunaan CreateTrip() memerlukan kredensial untuk akun dengan hak istimewa yang disebutkan dalam Fleet Engine: Peran akun layanan.

Kolom Perjalanan

Gunakan kolom berikut untuk membuat perjalanan di Fleet Engine. Anda dapat menggunakan kolom yang berbeda untuk berbagai jenis perjalanan: perjalanan dengan satu atau beberapa tujuan, perjalanan berturut-turut, atau perjalanan gabungan bersama. Anda dapat mengisi 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 pengambilan dan pengantaran 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 multi-tujuan

Berikut ini menunjukkan cara membuat perjalanan multi-tujuan eksklusif yang memiliki titik penjemputan, titik pengantaran, dan satu tujuan perantara.

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

Memperbarui perjalanan multi-tujuan

Anda harus mengonfigurasi perjalanan dengan ID kendaraan agar Mesin Flotte dapat melacak kendaraan di sepanjang rutenya. Untuk mengetahui detail tentang cara memperbarui perjalanan, lihat Memperbarui perjalanan dan mengelola statusnya.

Jika tidak menentukan tujuan pengantaran atau tujuan perantara saat membuat perjalanan, Anda dapat melakukannya kapan saja pada tahap ini.

Catatan: Setiap kali Anda menetapkan atau memperbarui intermediate_destinations dalam perjalanan, Fleet Engine akan mengisi intermediate_destinations_version dalam entity perjalanan yang dibuat. Anda harus meng-cache kolom ini di sistem dan meneruskan UpdateTripRequest saat Anda memperbarui intermediate_destination_index nanti. Tindakan ini akan membuat tujuan perantara tetap sinkron antara klien pengemudi dan Fleet Engine.

Contoh info terbaru perjalanan

Berikut ini menunjukkan cara memperbarui perjalanan untuk menambahkan daftar tujuan perantara dan menetapkan ID kendaraan.

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

Mengelola status perjalanan untuk perjalanan multi-tujuan

Anda menentukan status perjalanan menggunakan salah satu nilai enumerasi TripStatus. Saat status perjalanan berubah, misalnya dari ENROUTE_TO_PICKUP menjadi ARRIVED_AT_PICKUP, Anda harus memperbarui status perjalanan di Fleet Engine. Status perjalanan selalu dimulai dengan nilai NEW, dan diakhiri dengan nilai COMPLETE atau CANCELED.

Untuk perjalanan multi-tujuan, selain memperbarui status perjalanan seperti yang Anda lakukan untuk perjalanan satu tujuan, Anda juga harus memperbarui hal berikut setiap kali kendaraan Anda mencapai tujuan perantara:

• intermediateDestinationIndex
• intermediateDestinationsVersion

Untuk melakukannya, gunakan nilai berikut dari enumerasi TripStatus.

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

Catatan: Perjalanan harus bertransisi melalui ENROUTE_TO_INTERMEDIATE_DESTINATION dan ARRIVED_AT_INTERMEDIATE_DESTINATION sekali untuk setiap tujuan perantara.

Contoh perjalanan dengan tujuan perantara

Berikut ini cara membuat perjalanan multi-tujuan yang telah melewati titik penjemputan, dan sekarang sedang dalam perjalanan ke tujuan perantara pertamanya.

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

Langkah berikutnya

• Membuat perjalanan berturut-turut
• Menyiapkan Driver SDK