Perjalanan on-demand

Dokumen ini menjelaskan layanan perjalanan on demand di Fleet Engine. Bagian ini mengasumsikan bahwa Anda telah membaca Apa itu Fleet Engine? dan mengetahui kemampuan layanan Fleet Engine tertentu yang Anda perlukan.

Saat membaca dokumentasi ini, perhatikan hal-hal berikut:

• Anda menetapkan perjalanan ke kendaraan sebagai cara untuk membuat model pengaitan dunia nyata antara perjalanan dan pengemudi yang menyelesaikan perjalanan tersebut. Baca Pengantar kendaraan untuk lebih memahami cara kerja kendaraan di Fleet Engine.
• Dokumen ini juga menjelaskan beberapa elemen kendaraan yang hanya berlaku untuk perjalanan on demand.
• Fleet Engine untuk perjalanan on demand menggunakan dua resource: Trip dan Vehicle. Fleet Engine menyediakan layanan gRPC dan antarmuka REST:
  • TripService: gRPC dan REST
  • VehicleService: gRPC dan REST
  • Untuk mempermudah, panduan ini menggunakan contoh gRPC.

Apa yang dimaksud dengan perjalanan on-demand?

Di Fleet Engine, perjalanan mewakili perjalanan on demand yang dapat mencapai berbagai sasaran transportasi. Misalnya:

• Orang: Mengangkut satu atau beberapa orang dari lokasi pengambilan ke lokasi pengantaran.
• Makanan dan barang: Mengambil satu atau beberapa pesanan makanan dari lokasi bisnis tertentu dan mengantarkan pesanan ini kepada satu atau beberapa penerima di lokasi mereka.

Elemen perjalanan

Ilustrasi berikut menunjukkan elemen dasar perjalanan: ID kendaraan yang ditetapkan, status perjalanan, dan titik perhentian perjalanan. Jenis titik jalan bervariasi bergantung pada tahap perjalanan: pengambilan, perantara, dan pengantaran. Dalam perjalanan apa pun, tujuan atau titik jalan perantara bersifat opsional. Dalam contoh gambar, kendaraan telah tiba di lokasi pengambilan

Model data untuk perjalanan

Saat backend Anda menetapkan perjalanan ke kendaraan, backend juga harus mengetahui perjalanan lain yang dijadwalkan untuk kendaraan tersebut. Oleh karena itu, diagram berikut mengilustrasikan model data resource Trip bersama dengan diagram untuk resource Vehicle terkait. Anda dapat meninjau kedua diagram untuk mempelajari hubungan antara kedua resource tersebut, dengan mempertimbangkan hal berikut:

• Perjalanan ditetapkan ke kendaraan berdasarkan ID.
• Asosiasi perjalanan-kendaraan bersifat many-to-one. Artinya, perjalanan tertentu mungkin merupakan satu-satunya perjalanan yang dijadwalkan untuk kendaraan, atau mungkin salah satu dari banyak perjalanan untuk kendaraan.
• Objek perjalanan berisi dua daftar titik jalan perjalanan, satu untuk perjalanan itu sendiri dan satu untuk kendaraan yang ditetapkan. Hal ini dijelaskan secara lebih detail dalam dokumen ini.
• Kendaraan on demand juga memiliki daftar titik perhentian perjalanan, yang dijelaskan lebih lengkap dalam dokumen ini.

Model data perjalanan

Model data kendaraan

Jenis perjalanan

Saat membuat perjalanan, layanan Anda dapat menetapkan kolom tripType sebagai salah satu dari hal berikut: EXCLUSIVE atau SHARED.

Catatan: Jenis perjalanan yang Anda tentukan hanya dapat ditetapkan ke kendaraan yang mendukung jenis perjalanan tersebut. Misalnya, Anda hanya dapat menetapkan perjalanan SHARED ke kendaraan dengan supported_trip_types ditetapkan ke SHARED. Lihat referensi untuk Layanan Kendaraan, gRPC, atau Rest.

Perjalanan eksklusif

Perjalanan eksklusif adalah perjalanan yang tidak tumpang-tindih dengan perjalanan lain, dan perjalanan yang diselesaikan kendaraan sebelum atau setelah perjalanan lain sesuai jadwalnya. Artinya, saat sistem Anda menetapkan perjalanan eksklusif, sistem hanya dapat menetapkannya ke kendaraan untuk diselesaikan secara berurutan, bukan secara serentak. Untuk menggambarkan, Anda dapat membuat perjalanan eksklusif dengan salah satu karakteristik berikut:

• Perjalanan dengan satu pengambilan dan satu pengantaran untuk kendaraan tanpa perjalanan lain dalam jadwalnya.
• Perjalanan dengan penjemputan, titik jalan tengah, dan pengantaran untuk kendaraan tanpa perjalanan lain dalam jadwalnya.
• Perjalanan dengan pengambilan dan pengantaran yang ditambahkan ke akhir perjalanan yang telah dijadwalkan untuk kendaraan. Dalam hal ini, setiap perjalanan eksklusif untuk perjalanan lainnya, tetapi perjalanan tersebut diurutkan secara berurutan. Selain itu, perjalanan tersebut dapat mencakup tujuan perantara jika diperlukan.

Catatan: Hanya perjalanan eksklusif yang dapat memiliki tujuan atau titik perantara. Lihat Jenis titik jalan perjalanan untuk mengetahui detailnya.

Perjalanan bersama

Perjalanan bersama adalah perjalanan yang dapat tumpang-tindih dengan pemesanan perjalanan lain. Untuk jenis perjalanan ini, sistem Anda dapat menetapkannya agar terjadi secara serentak dengan tujuan yang diselingi. Misalnya, pengantaran untuk satu perjalanan mungkin terjadi setelah penjemputan untuk perjalanan lain. Selain itu, perjalanan bersama tidak boleh menggunakan titik jalan perantara.

Biasanya, Anda akan menggunakan perjalanan bersama untuk salah satu skenario penggabungan bersama yang diilustrasikan di bagian Skenario perjalanan.

Titik jalan perjalanan

Untuk Google Maps, titik jalan adalah tempat di sepanjang rute, biasanya ditentukan oleh koordinat lintang/bujur. Untuk perjalanan on-demand, titik jalan diwakili oleh objek TripWaypoint, yang berisi informasi tambahan seperti berikut:

• ID perjalanan
• WaypointType, baik penjemputan, perantara, maupun pengantaran
• Informasi jalur dan jarak antara titik jalan perjalanan sebelumnya dan titik jalan saat ini
• Kondisi lalu lintas di sepanjang jalur ke titik jalan perjalanan
• Waktu perjalanan dan PWT ke titik jalan perjalanan

Eksperimental: Sebagai fitur eksperimental, Fleet Engine kini mendukung penggunaan ID Tempat bersama dengan atau sebagai pengganti lintang/bujur. Jika lokasi memiliki ID Tempat dan lintang-bujur, Fleet Engine akan menggunakan lintang-bujur untuk pemilihan rute, dan ID Tempat untuk masukan lokasi.

Lihat referensi:

• TripWaypoint: gRPC atau REST
• WaypointType: gRPC atau REST

Jenis titik jalan perjalanan

Titik jalan perjalanan ditentukan sehubungan dengan siklus proses umum perjalanan kendaraan:

• Titik pengambilan—Digunakan untuk asal atau awal perjalanan, seperti saat pengemudi mengambil pesanan makanan untuk pengiriman berikutnya, atau saat pengemudi mengambil penumpang untuk diantar nanti.
• Titik jalan tengah—Tujuan perantara yang dapat digunakan untuk berbagai tujuan, seperti saat pengemudi menurunkan satu penumpang dari pihak pemesanan yang sama, tetapi perjalanan itu sendiri belum selesai, karena masih ada penumpang lain. Titik jalan ini bersifat opsional dan hanya dapat digunakan untuk perjalanan eksklusif.
• Titik jalan penurunan penumpang—Digunakan untuk lokasi akhir perjalanan, seperti saat penumpang yang tersisa keluar dari kendaraan.

Daftar titik jalan perjalanan

Entity Trip menyertakan dua daftar titik jalan, yang masing-masing adalah kolom berulang dari jenis TripWaypoint. Satu daftar menjelaskan kolom yang diperlukan untuk perjalanan itu sendiri, dan daftar lainnya untuk menjelaskan semua titik jalan yang tersisa untuk kendaraan yang terkait dengan perjalanan. Hal ini memungkinkan Anda memiliki gambaran lengkap tentang semua elemen perjalanan: perjalanan dan seluruh perjalanan kendaraan.

• Titik jalan tersisa untuk kendaraan—Kolom yang disebut vehicle_waypoints. File ini berisi semua titik jalan yang tersisa untuk semua perjalanan yang ditetapkan ke kendaraan.
• Titik jalan tersisa untuk perjalanan—Kolom yang disebut remaining_waypoints. File ini berisi titik jalan yang harus dilalui kendaraan secara berurutan sebelum titik pengantaran akhir perjalanan. Lihat skenario di Skenario perjalanan.
  • Untuk perjalanan satu tujuan yang ditetapkan ke kendaraan tanpa perjalanan lain dalam jadwalnya, perjalanan ini hanya akan mencakup lokasi pengambilan dan penurunan, dengan asumsi kendaraan belum meninggalkan titik jalan pengambilan.
  • Untuk skenario perjalanan lain saat kendaraan juga dijadwalkan untuk perjalanan lain, titik jalan yang tersisa untuk perjalanan apa pun dalam itinerarinya akan menyertakan semua titik jalan dari perjalanan lain yang harus dilalui kendaraan sebelum mencapai titik jalan penurunan untuk perjalanan tersebut. Misalnya, dalam perjalanan berturut-turut saat kendaraan sedang dalam perjalanan ke tempat pengantaran untuk perjalanan A, titik jalan yang tersisa untuk perjalanan B akan menyertakan titik jalan pengantaran untuk perjalanan A. Fleet Engine menghitung informasi ini menggunakan kolom vehicle_waypoints.

Lihat referensi untuk entitas Trip: gRPC atau REST.

Skenario perjalanan

Diagram berikut mengilustrasikan berbagai skenario perjalanan yang didukung. Dalam skenario ini, hanya perjalanan gabungan bersama yang berjenis SHARED; semua yang lainnya adalah EXCLUSIVE. Diagram juga menunjukkan status perjalanan dan titik jalan yang tersisa untuk kendaraan yang melakukan perjalanan, konsep yang dijelaskan nanti dalam panduan ini.

Perjalanan satu tujuan

Perjalanan satu tujuan adalah perjalanan EXCLUSIVE dengan satu lokasi penjemputan dan satu lokasi pengantaran. Misalnya, pengemudi menjemput penumpang dari satu lokasi dan mengantarkannya ke lokasi lain; atau pengemudi mengambil pesanan pesan antar makanan dari restoran dan mengantarkannya kepada pelanggan.

Perjalanan multi-tujuan

Perjalanan multi-tujuan adalah perjalanan EXCLUSIVE yang berisi satu atau beberapa tujuan perantara antara lokasi penjemputan dan pengantaran. Misalnya, tiga pelanggan transportasi online memesan perjalanan bersama dari ponsel satu orang, tetapi masing-masing memiliki tujuan yang berbeda.

Perjalanan beruntun

Perjalanan berturut-turut adalah perjalanan EXCLUSIVE yang berisi serangkaian perjalanan independen yang terjadi satu demi satu. Setiap perjalanan dalam rantai dapat berupa satu atau beberapa tujuan. Dalam skenario ini, pengemudi berkomitmen untuk menjemput pelanggan lain sebelum menyelesaikan perjalanan saat ini.

Perjalanan ini hanya dapat ditetapkan ke kendaraan yang mengizinkan penjadwalan berturut-turut. Lihat referensi Vehicle REST, gRPC.

Perjalanan dengan fitur berbagi tumpangan

Perjalanan dengan fitur berbagi tumpangan berbeda dengan jenis perjalanan lainnya. Pertama, perjalanan tersebut harus berupa perjalanan SHARED, bukan EXCLUSIVE. Di sini, kendaraan menjalankan perjalanan secara serentak, bukan secara berurutan seperti perjalanan eksklusif. Meskipun perjalanan berbagi tumpangan memiliki perjalanan yang sama dengan perjalanan lain, perjalanan ini tidak membagikan informasi lokasi penjemputan dan pengantaran antar-perjalanan. Sebagai gantinya, setiap perjalanan adalah pemesanan eksklusif sehingga pengguna akhir yang memesan satu perjalanan tidak dapat melihat informasi penjemputan atau tujuan untuk perjalanan lain selain perjalanan mereka sendiri. Contoh:

• Layanan antar-jemput bandara menjemput berbagai pelanggan di tempat tinggal mereka dan menurunkan mereka di terminal bandara yang berbeda di sepanjang rute. Orang 2 mungkin menggunakan aplikasi konsumen Anda untuk melacak progres perjalanan, tetapi aplikasinya hanya menampilkan bagian perjalanannya, bukan tempat orang 1 dijemput, atau tempat orang 1 akan diturunkan, meskipun bagian perjalanan mereka tumpang-tindih.
  
• Seorang pengemudi pesan antar makanan mengambil tiga pesanan makanan dari restoran yang sama untuk dikirim ke tempat tinggal pelanggan yang berbeda. Dengan menggunakan aplikasi konsumen Anda, Orang 3 dapat melihat tempat dan waktu makanannya diambil serta melihat rute pengemudi, tetapi tidak dapat melihat lokasi pengantaran makanan untuk orang 1 dan 2.
  

Status perjalanan dan siklus prosesnya

Bagian ini menjelaskan status perjalanan dan dampaknya pada kendaraan serta berbagai skenario yang Anda temui saat menetapkan dan mengelola perjalanan on demand.

Perjalanan biasanya melalui berbagai status, mulai dari pembuatan hingga penyelesaian. Secara umum, perjalanan dapat aktif atau tidak aktif, bergantung pada statusnya. Status perjalanan memengaruhi berbagai skenario kasus penggunaan dengan Fleet Engine, serta kemampuan Anda untuk mengidentifikasi progres kendaraan selama perjalanan. Bagian lain dokumen ini membahas skenario tersebut.

Tabel berikut mencantumkan status perjalanan menurut jenis aktif dan tidak aktif.

Status perjalanan aktif	Status perjalanan tidak aktif
NEW UNKNOWN_TRIP_STATUS ENROUTE_TO_PICKUP ARRIVED_AT_PICKUP ENROUTE_TO_INTERMEDIATE_DESTINATION ARRIVED_AT_INTERMEDIATE_DESTINATION ENROUTE_TO_DROPOFF	COMPLETE CANCELED

Catatan: Untuk definisi status, lihat referensi gRPC atau REST.

Status perjalanan dan titik jalan kendaraan yang tersisa

Saat menetapkan perjalanan tambahan ke kendaraan yang sudah menjalankan perjalanan, Anda harus memahami hubungan antara titik jalan yang tersisa untuk kendaraan dan pengaruh status perjalanan terhadap titik jalan yang tersisa tersebut.

Misalnya, Anda dapat menetapkan permintaan transportasi online baru ke kendaraan yang hanya mendukung perjalanan eksklusif dan sedang menyelesaikan perjalanan. Dalam hal ini, Anda akan membuat model perjalanan sebagai perjalanan berturut-turut. Saat menetapkan perjalanan tersebut, sistem Anda harus memastikan bahwa titik jalan untuk perjalanan baru terjadi setelah titik jalan untuk perjalanan yang sedang berlangsung.

Selama perjalanan kendaraan, Fleet Engine akan menghapus titik jalan perjalanan sebelumnya dari daftar titik jalan yang tersisa di kendaraan hanya saat kendaraan melaporkan bahwa kendaraan sedang dalam perjalanan ke tujuan berikutnya atau telah selesai. Artinya, salah satu dari hal berikut:

• ENROUTE_TO_INTERMEDIATE_DESTINATION
• ENROUTE_TO_DROPOFF
• SELESAI

Saat status perjalanan berubah menjadi COMPLETED, Fleet Engine akan menghapus titik jalan akhir perjalanan dari daftar titik jalan yang tersisa di kendaraan.

Sebaliknya, perubahan status yang menunjukkan kedatangan di titik jalan biasanya tidak memengaruhi daftar titik jalan yang tersisa untuk kendaraan:

• ARRIVED_AT_PICKUP
• ARRIVED_AT_INTERMEDIATE_DESTINATION
• ARRIVED_AT_DROPOFF

Untuk mengilustrasikan dengan contoh perjalanan on demand: misalkan pengemudi menjemput pelanggan dari tempat tinggalnya, mengantarnya ke tempat yang ia tunggu pelanggan menyelesaikan tugas, lalu mengantar pelanggan kembali ke tempat tinggalnya. Saat pertama kali dibuat, perjalanan memiliki tiga titik jalan: PICKUP, INTERMEDIATE, dan DROPOFF. Tabel berikut mengilustrasikan hasil kueri untuk titik jalan yang tersisa di berbagai status perjalanan:

Status perjalanan	Titik jalan lainnya
ARRIVED_AT_PICKUP	PICKUP INTERMEDIATE DROPOFF
ENROUTE_TO_INTERMEDIATE_DESTINATION	PICKUP INTERMEDIATE DROPOFF
ARRIVED_AT_INTERMEDIATE_DESTINATION	PICKUP INTERMEDIATE DROPOFF
ENROUTE_TO_DROPOFF	PICKUP INTERMEDIATE DROPOFF
ARRIVED_AT_DROPOFF	PICKUP INTERMEDIATE DROPOFF
COMPLETE	PICKUP INTERMEDIATE DROPOFF

Persyaratan status untuk perjalanan yang ditetapkan ulang atau dibatalkan

Sebelum dapat melakukan tindakan berikut, Anda harus menetapkan status perjalanan ke NEW atau CANCELED.

• Saat mengubah penetapan kendaraan untuk perjalanan. Misalnya, jika pengemudi menolak penetapan kendaraan untuk perjalanan dan perlu ditetapkan ulang ke kendaraan lain.
• Saat menghapus penetapan kendaraan untuk perjalanan. Misalnya, jika pengemudi membatalkan perjalanan dalam perjalanan dan Anda ingin menghapus penetapan kendaraan, statusnya harus NEW atau CANCELED.

Hasil penelusuran berdasarkan status perjalanan

Saat Anda menggunakan layanan SearchTrips untuk kendaraan tertentu, layanan ini akan menampilkan daftar perjalanan aktif di SearchTripsResponse. Perjalanan aktif juga muncul di kolom active_trips entitas Vehicle. Lihat referensi SearchTripsResponse untuk mengetahui detailnya: gRPC atau REST.

Oleh karena itu, semua perjalanan dengan status aktif akan muncul di kolom active_trips, tetapi perjalanan yang telah selesai atau dibatalkan tidak akan muncul.

Langkah berikutnya

• Menyiapkan Fleet Engine
• Membuat kendaraan
• Membuat perjalanan on demand