Fleet Engine On-demand Rides and Deliveries API memungkinkan Anda mengelola perjalanan dan status kendaraan untuk aplikasi Perjalanan dan Progres Pesanan Anda. Library ini menangani transaksi antara Driver SDK, Consumer SDK, dan layanan backend Anda, yang dapat berkomunikasi dengan Fleet Engine dengan melakukan panggilan gRPC atau REST.
Prasyarat
Untuk pengembangan, pastikan Anda menginstal Cloud SDK (gcloud) dan diautentikasi ke project Anda.
shell
gcloud auth login
Anda akan melihat pesan berhasil, seperti:
You are now logged in as [my-user@example.com].
Your current project is [project-id]. You ...
Pastikan API Fleet Engine Solusi Transportasi dan Pengiriman On-demand dikonfigurasi dengan benar.
shell
gcloud --project=project-id services enable fleetengine.googleapis.com
Jika perintah ini menghasilkan error, hubungi administrator project dan perwakilan dukungan Google Anda untuk mendapatkan akses.
Logging
Fleet Engine dapat menulis pesan log tentang panggilan API yang diterimanya ke dalam log platform Google Cloud. Baca dokumentasi Cloud Logging untuk mengetahui ringkasan cara membaca dan menganalisis log.
Logging mungkin tidak diaktifkan secara default untuk project yang dibuat sebelum 10 Februari 2022. Baca dokumentasi logging untuk mengetahui detail selengkapnya.
Library Klien
Kami menerbitkan library klien dalam beberapa bahasa pemrograman yang umum. Library ini akan membantu memberikan pengalaman developer yang lebih baik dibandingkan REST atau gRPC mentah. Untuk mengetahui petunjuk cara mendapatkan library klien untuk aplikasi server Anda, lihat Library Klien.
Contoh Java dalam dokumentasi ini mengasumsikan bahwa Anda telah memahami gRPC.
Autentikasi dan Otorisasi
Anda dapat mengonfigurasi kemampuan yang diberikan oleh Progres Perjalanan dan Pesanan melalui Konsol Google Cloud. API dan SDK ini memerlukan penggunaan Token Web JSON yang telah ditandatangani menggunakan akun layanan yang dibuat dari Konsol Cloud.
Penyiapan project cloud
Untuk menyiapkan project cloud, buat project terlebih dahulu, lalu buat akun layanan.
Untuk membuat project Google Cloud:
- Membuat Project Google Cloud menggunakan Konsol Google Cloud.
- Dengan menggunakan Dasbor API & Layanan, aktifkan Local Rides and Deliveries API.
Akun layanan dikaitkan dengan satu atau beberapa peran. Token ini digunakan untuk membuat Token Web JSON yang memberikan berbagai kumpulan izin, bergantung pada perannya. Biasanya, untuk mengurangi kemungkinan penyalahgunaan, Anda dapat membuat beberapa akun layanan, masing-masing dengan serangkaian peran minimum yang diperlukan.
Progres Perjalanan dan Pesanan menggunakan peran berikut:
Peran | Deskripsi |
---|---|
Pengguna Fleet Engine Consumer SDK
roles/fleetengine.consumerSdkUser |
Memberikan izin untuk menelusuri kendaraan dan mengambil informasi tentang kendaraan dan perjalanan. Token yang dibuat oleh akun layanan dengan peran ini biasanya digunakan dari perangkat seluler aplikasi transportasi online atau pengiriman Anda. |
Pengguna SDK Driver Fleet Engine
roles/fleetengine.driverSdkUser |
Memberikan izin untuk memperbarui lokasi dan rute kendaraan serta mengambil informasi tentang kendaraan dan perjalanan. Token yang dibuat oleh akun layanan dengan peran ini biasanya digunakan dari perangkat seluler aplikasi transportasi online atau pengemudi pengiriman Anda. |
Admin Fleet Engine On-demand
roles/fleetengine.ondemandAdmin |
Memberikan izin baca dan tulis untuk semua resource kendaraan dan perjalanan. Kepala sekolah dengan peran ini tidak perlu menggunakan JWT dan sebaiknya menggunakan Kredensial Default Aplikasi. Klaim JWT kustom akan diabaikan. Peran ini harus dibatasi untuk lingkungan tepercaya (backend pelanggan). |
roles/fleetengine.serviceSuperUser |
Memberikan izin untuk semua API kendaraan dan perjalanan. Token yang dibuat oleh akun layanan dengan peran ini biasanya digunakan dari server backend Anda. Peran ini tidak digunakan lagi. Pilih
roles/fleetengine.ondemandAdmin sebagai gantinya. |
Misalnya, buat akun layanan untuk ketiga peran tersebut dan tetapkan perannya masing-masing.
gcloud --project=project-id iam service-accounts create fleet-engine-consumer-sdk gcloud projects add-iam-policy-binding project-id \ --member=serviceAccount:fleet-engine-consumer-sdk@project-id.iam.gserviceaccount.com \ --role=roles/fleetengine.consumerSdkUser gcloud --project=project-id iam service-accounts create fleet-engine-driver-sdk gcloud projects add-iam-policy-binding project-id \ --member=serviceAccount:fleet-engine-driver-sdk@project-id.iam.gserviceaccount.com \ --role=roles/fleetengine.driverSdkUser gcloud --project=project-id iam service-accounts create fleet-engine-su gcloud projects add-iam-policy-binding project-id \ --member=serviceAccount:fleet-engine-su@project-id.iam.gserviceaccount.com \ --role=roles/fleetengine.serviceSuperUser
Driver dan Consumer SDK dibuat berdasarkan peran standar ini.
Atau, Anda dapat membuat peran khusus yang memungkinkan kumpulan izin arbitrer untuk digabungkan. SDK Driver dan Konsumen akan menampilkan pesan error setiap kali izin yang diperlukan tidak ada. Oleh karena itu, sebaiknya gunakan kumpulan peran standar yang ditampilkan di atas dan jangan menggunakan peran khusus.
Demi kemudahan, jika Anda perlu membuat token JWT untuk klien yang tidak tepercaya, menambahkan pengguna ke Service Account Token Creator Role akan memungkinkan mereka membuat token dengan alat command line gcloud.
gcloud projects add-iam-policy-binding project-id \
--member=user:my-user@example.com \
--role=roles/iam.serviceAccountTokenCreator
my-user@example.com
adalah email yang digunakan untuk melakukan autentikasi dengan gcloud (gcloud auth list
--format='value(account)'
).
Library Auth Fleet Engine
Fleet Engine menggunakan Token Web JSON (JWT) untuk membatasi akses ke Fleet Engine API. Library Auth Fleet Engine baru, tersedia di GitHub, menyederhanakan pembuatan JWT Fleet Engine dan menandatanganinya dengan aman.
Library ini memberikan manfaat berikut:
- Menyederhanakan proses pembuatan Token Fleet Engine.
- Menyediakan mekanisme penandatanganan token selain menggunakan file kredensial (seperti meniru identitas akun layanan.)
- Melampirkan token yang ditandatangani ke permintaan keluar yang dibuat dari stub gRPC atau klien GAPIC.
Membuat Token Web JSON (JWT) untuk otorisasi
Jika tidak menggunakan Library Auth Fleet Engine, Token Web JSON (JWT) harus dibuat langsung dalam codebase Anda. Ini mengharuskan Anda memiliki pemahaman mendalam tentang JWT dan hubungannya dengan Fleet Engine. Inilah alasan kami SANGAT merekomendasikan penggunaan Library Auth Fleet Engine.
Dalam Fleet Engine, JSON Web Token (JWT) menyediakan autentikasi jangka pendek dan memastikan bahwa perangkat hanya dapat memodifikasi kendaraan, perjalanan, atau tugas yang diizinkan. JWT berisi header dan bagian klaim. Bagian header berisi informasi seperti kunci pribadi yang akan digunakan (diperoleh dari akun layanan) dan algoritma enkripsi. Bagian klaim berisi informasi seperti waktu pembuatan token, waktu aktif token, layanan yang aksesnya diklaim, dan informasi otorisasi lainnya untuk mencakup akses ke bawah; misalnya, ID kendaraan.
Bagian header JWT berisi kolom-kolom berikut:
Kolom | Deskripsi |
---|---|
alg | Algoritma yang akan digunakan. `RS256`. |
typ | Jenis token. `JWT`. |
anak | ID kunci pribadi akun layanan Anda. Anda dapat menemukan nilai ini di kolom `private_key_id` pada file JSON akun layanan Anda. Pastikan untuk menggunakan kunci dari akun layanan dengan tingkat izin yang benar. |
Bagian klaim JWT berisi kolom-kolom berikut:
Kolom | Deskripsi |
---|---|
iss | Alamat email akun layanan Anda. |
sub | Alamat email akun layanan Anda. |
aud | SERVICE_NAME akun layanan Anda, dalam hal ini https://fleetengine.googleapis.com/ |
Iat | Stempel waktu saat token dibuat, yang ditentukan dalam detik yang berlalu sejak 00:00:00 UTC, 1 Januari 1970. Tunggu 10 menit untuk kemiringan. Jika stempel waktu terlalu lampau atau di masa mendatang, server mungkin melaporkan error. |
exp | Stempel waktu saat token berakhir, yang ditentukan dalam detik yang berlalu sejak 1 Januari 1970 pukul 00.00.00 UTC. Permintaan akan gagal jika stempel waktu lebih dari satu jam pada masa mendatang. |
authorization | Bergantung pada kasus penggunaannya, dapat berisi `vehicleid` atau `tripid`. |
Pembuatan token JWT mengacu pada proses penandatanganannya. Untuk petunjuk dan contoh kode cara membuat dan menandatangani JWT, lihat Otorisasi akun layanan tanpa OAuth. Selanjutnya, Anda dapat melampirkan token yang ditandatangani ke panggilan gRPC atau metode lain yang digunakan untuk mengakses Fleet Engine.
Klaim JWT
Saat membuat payload JWT, tambahkan klaim tambahan di bagian otorisasi dengan kunci vehicleid
atau tripid
yang disetel ke nilai ID kendaraan atau ID perjalanan yang menjadi tujuan panggilan.
Driver SDK selalu menggunakan klaim vehicleid
, baik saat beroperasi dalam
perjalanan atau kendaraan. Backend Fleet Engine memastikan bahwa kendaraan
dikaitkan dengan perjalanan yang diminta sebelum melakukan modifikasi.
Consumer SDK selalu menggunakan klaim tripid
.
Penyedia Transportasi Online atau Pengiriman harus menggunakan vehicleid
atau tripid
dengan tanda "*" agar cocok dengan semua Kendaraan dan Perjalanan. Perhatikan bahwa JWT dapat berisi kedua token, meskipun tidak diperlukan, yang dapat menyederhanakan implementasi penandatanganan token.
Kasus Penggunaan JWT
Berikut adalah contoh token untuk Server penyedia:
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_provider_service_account"
}
.
{
"iss": "provider@yourgcpproject.iam.gserviceaccount.com",
"sub": "provider@yourgcpproject.iam.gserviceaccount.com",
"aud": "https://fleetengine.googleapis.com/",
"iat": 1511900000,
"exp": 1511903600,
"authorization": {
"vehicleid": "*",
"tripid": "*"
}
}
Berikut adalah contoh token untuk Consumer app:
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_consumer_service_account"
}
.
{
"iss": "consumer@yourgcpproject.iam.gserviceaccount.com",
"sub": "consumer@yourgcpproject.iam.gserviceaccount.com",
"aud": "https://fleetengine.googleapis.com/",
"iat": 1511900000,
"exp": 1511903600,
"authorization": {
"tripid": "trip_54321"
}
}
Berikut adalah contoh token untuk Aplikasi pengemudi:
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_driver_service_account"
}
.
{
"iss": "driver@yourgcpproject.iam.gserviceaccount.com",
"sub": "driver@yourgcpproject.iam.gserviceaccount.com",
"aud": "https://fleetengine.googleapis.com/",
"iat": 1511900000,
"exp": 1511903600,
"authorization": {
"vehicleid": "driver_12345"
}
}
- Untuk kolom
kid
di header, tentukan ID kunci pribadi akun layanan Anda. Anda dapat menemukan nilai ini di kolomprivate_key_id
pada file JSON akun layanan Anda. - Untuk kolom
iss
dansub
, tentukan alamat email akun layanan Anda. Anda dapat menemukan nilai ini di kolomclient_email
pada file JSON akun layanan Anda. - Untuk kolom
aud
, tentukan https://SERVICE_NAME/. - Untuk kolom
iat
, gunakan stempel waktu saat token dibuat, yang ditentukan sebagai detik yang berlalu sejak 00:00:00 UTC, 1 Januari 1970. Tunggu 10 menit untuk kemiringan. Jika stempel waktu terlalu lampau, atau di masa mendatang, server mungkin melaporkan error. - Untuk kolom
exp
, gunakan stempel waktu saat token berakhir, yang ditentukan sebagai detik sejak 00:00:00 UTC, 1 Januari 1970. Nilai maksimum yang diizinkan adalahiat
+ 3600.
Saat menandatangani JWT untuk diteruskan ke perangkat seluler, pastikan Anda menggunakan akun layanan untuk peran Driver atau Consumer SDK. Jika tidak, perangkat seluler akan memiliki kemampuan untuk mengubah status yang seharusnya tidak dimiliki.
Selain itu, saat menandatangani JWT yang akan digunakan untuk panggilan dengan hak istimewa, pastikan menggunakan akun layanan dengan peran Super User. Jika tidak, operasi akan gagal.
Membuat JWT untuk pengujian
Membuat token dari terminal dapat membantu saat pengujian.
Untuk mengikuti langkah-langkah ini, akun pengguna Anda harus memiliki peran Service Account Token Creator:
gcloud projects add-iam-policy-binding project-id \
--member=user:my-user@example.com \
--role=roles/iam.serviceAccountTokenCreator
Buat file baru bernama unsigned_token.json
dengan konten di bawah ini. Properti iat
adalah waktu saat ini dalam jumlah detik setelah epoch, yang dapat
diambil dengan menjalankan date +%s
di terminal Anda. Properti exp
adalah
waktu habis masa berlaku dalam jumlah detik setelah epoch, yang dapat dihitung dengan
menambahkan 3600 ke iat
. Waktu habis masa berlaku tidak boleh lebih dari satu jam di
masa mendatang.
{ "aud": "https://fleetengine.googleapis.com/", "iss": "super-user-service-account@project-id.iam.gserviceaccount.com", "sub": "super-user-service-account@project-id.iam.gserviceaccount.com", "iat": iat, "exp": exp, "authorization": { "vehicleid": "*", "tripid": "*" } }
Kemudian, jalankan perintah gcloud berikut untuk menandatangani token atas nama akun layanan Super User Anda:
gcloud beta iam service-accounts sign-jwt --iam-account=super-user-service-account@project-id.iam.gserviceaccount.com unsigned_token.json signed_token.jwt
JWT berenkode Base64 yang ditandatangani kini seharusnya disimpan dalam file
signed_token.jwt
. Token berlaku untuk satu jam ke depan.
Sekarang, Anda dapat menguji token dengan menjalankan perintah curl
terhadap endpoint REST List Vehicles:
curl -X GET "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles" -H "Authorization: Bearer $(cat signed_token.jwt)"
Kendaraan dan siklus prosesnya
Kendaraan adalah entity yang mewakili pasangan pengemudi-kendaraan. Saat ini, Pengemudi dan Kendaraan tidak dapat dilacak secara terpisah. Penyedia Transportasi Online atau Pengiriman membuat Kendaraan menggunakan ID Penyedia (yang harus sama dengan Project ID Project Google Cloud yang berisi akun layanan yang digunakan untuk memanggil API Fleet Engine) dan ID Kendaraan milik Penyedia Transportasi Umum atau Pengiriman.
Kendaraan yang belum diupdate melalui UpdateVehicle
setelah tujuh hari akan
otomatis dihapus, dan perjalanan yang ditetapkan, jika ada, akan ditandai sebagai
tidak ditetapkan. Pendekatan yang direkomendasikan untuk menjaga kendaraan tetap tersedia
di Fleet Engine adalah memperbarui lokasinya secara berkala. Pembaruan pada sebagian besar
kolom lain dalam entity Vehicle
juga akan memperpanjang masa berlakunya, asalkan
nilai kolom baru berbeda dengan yang sudah ada.
CATATAN: Beberapa kolom pada entity Vehicle
seperti device_settings
sepenuhnya merupakan informasi
debug yang tidak dipertahankan oleh Fleet Engine. Memperbaruinya tidak
memperpanjang masa pakai entity Vehicle
.
Memanggil CreateVehicle
dengan
pasangan ID Penyedia/ID Kendaraan yang sudah ada merupakan error. Kasus kendaraan yang
sering tidak diupdate dapat ditangani dengan dua cara: sering memanggil
CreateVehicle
dengan pasangan ID Penyedia/ID Kendaraan yang diharapkan dan menghapus
error jika Kendaraan sudah ada; atau, memanggil CreateVehicle
setelah
UpdateVehicle
akan menampilkan error NOT_FOUND
.
Pembaruan lokasi kendaraan
Untuk performa terbaik dengan Fleet Engine, berikan aliran data pembaruan lokasi kendaraan. Gunakan salah satu cara berikut untuk memberikan update ini:
- Gunakan Driver SDK - Android, iOS - opsi paling sederhana.
- Gunakan kode kustom -- berguna jika lokasi di-relai melalui backend, atau jika Anda menggunakan perangkat selain Android atau iOS.
Jenis kendaraan
Entity Vehicle berisi kolom wajib VehicleType
, yang berisi
enum Category
yang dapat ditentukan sebagai AUTO
, TAXI
, TRUCK
,
TWO_WHEELER
, BICYCLE
, atau PEDESTRIAN
. Jenis kendaraan dapat berfungsi sebagai kriteria filter di SearchVehicles
dan ListVehicles
.
Semua pemilihan rute untuk kendaraan akan menggunakan RouteTravelMode
yang sesuai jika kategorinya ditetapkan ke AUTO
, TWO_WHEELER
, BICYCLE
, atau PEDESTRIAN
.
Jika kategori ditetapkan ke TAXI
atau TRUCK
, perutean diperlakukan sama seperti
mode AUTO
.
Atribut kendaraan
Entity Vehicle berisi kolom berulang, yaitu VehicleAttribute
. Atribut ini tidak ditafsirkan oleh Fleet Engine. SearchVehicles
API menyertakan kolom untuk mewajibkan Vehicles
yang cocok harus berisi semua
atribut disertakan yang ditetapkan ke nilai yang ditentukan.
Perhatikan bahwa kolom atribut merupakan tambahan untuk beberapa kolom lain yang didukung dalam pesan Vehicle
, seperti vehicle_type
dan supported_trip_types
.
Titik jalan kendaraan yang tersisa
Entity Kendaraan berisi kolom berulang TripWaypoint
(RPC | REST),
yang disebut waypoints
(RPC | REST).
Kolom ini menyertakan titik jalan yang tersisa dalam perjalanan, sesuai urutan
kendaraan mencapainya. Fleet Engine menghitung kolom ini saat perjalanan
ditetapkan ke kendaraan, dan memperbaruinya saat perjalanan mengubah statusnya.
Titik jalan ini dapat diidentifikasi dengan kolom TripId
dan kolom WaypointType
.
Memperluas kelayakan kendaraan untuk kecocokan
Biasanya, layanan Transportasi Online atau Penyedia Pesan Antar bertanggung jawab untuk mencocokkan permintaan
perjalanan dengan kendaraan. Layanan dapat menggunakan atribut kendaraan untuk menyertakan
kendaraan dalam jumlah penelusuran yang lebih besar. Misalnya, penyedia dapat menerapkan
kumpulan ke atribut yang sesuai dengan tingkat keuntungan atau kemampuan yang diberikan oleh
kendaraan. Misalnya, tiga tingkat dapat berupa kumpulan atribut dengan nilai boolean: is_bronze_level
, is_silver_level
, dan is_gold_level
. Sebuah kendaraan dapat memenuhi syarat untuk ketiganya. Saat Fleet Engine menerima permintaan untuk
perjalanan yang memerlukan kemampuan level silver, penelusuran akan menyertakan kendaraan tersebut.
Menggunakan atribut dengan cara ini mencakup kendaraan yang menawarkan berbagai kemampuan.
Ada dua cara untuk memperbarui atribut kendaraan. Salah satunya adalah UpdateVehicle
API. Saat menggunakan API ini, seluruh kumpulan Atribut Kendaraan akan ditetapkan ke nilai. Tidak mungkin hanya memperbarui satu atribut.
Metode lainnya adalah UpdateVehicleAttributes
API. Metode ini hanya memerlukan atribut untuk diupdate. Atribut yang disertakan dalam permintaan akan
ditetapkan ke nilai baru atau ditambahkan; atribut yang belum ditetapkan tidak akan diubah.
PETUNJUK: Membuat Kendaraan
Entitas Vehicle
harus dibuat untuk setiap Kendaraan agar dapat dilacak di fleet.
Gunakan endpoint CreateVehicle
dengan CreateVehicleRequest
untuk membuat
Kendaraan.
provider_id
dari Vehicle
harus berupa Project ID (misalnya my-on-demand project) dari Project Google Cloud yang berisi Akun Layanan yang akan digunakan untuk memanggil Fleet Engine. Perlu diperhatikan bahwa meskipun
beberapa akun layanan dapat mengakses Fleet Engine untuk Penyedia Transportasi Online atau Pengiriman yang sama, Fleet Engine saat ini tidak mendukung akun layanan dari
beberapa Project Google Cloud yang mengakses Vehicles
yang sama.
Vehicle
dapat dibuat dalam status OFFLINE
atau ONLINE
. Jika ONLINE
dibuat, kueri tersebut dapat segera ditampilkan sebagai respons terhadap kueri SearchVehicles
.
last_location
awal dapat disertakan dalam panggilan CreateVehicle
.
Meskipun diizinkan, Vehicle
tidak boleh dibuat dalam status ONLINE
tanpa
last_location
.
Lihat Jenis Kendaraan untuk mengetahui detail tentang kolom jenis kendaraan.
Lihat Atribut Kendaraan untuk mengetahui detail tentang kolom atribut.
Nilai yang ditampilkan dari CreateVehicle
adalah entity Vehicle
yang dibuat.
Contoh
shell
curl -X POST \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles?vehicleId=vid-8241890" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"vehicleState": "OFFLINE",
"supportedTripTypes": ["EXCLUSIVE"],
"maximumCapacity": 4,
"vehicleType": {"category": "AUTO"},
"attributes": [{"key": "on_trip", "value": "false"}]
}
EOM
Lihat referensi providers.vehicles.create.
Java
static final String PROJECT_ID = "project-id";
VehicleServiceBlockingStub vehicleService =
VehicleService.newBlockingStub(channel);
String parent = "providers/" + PROJECT_ID;
Vehicle vehicle = Vehicle.newBuilder()
.setVehicleState(VehicleState.OFFLINE) // Initial state
.addSupportedTripTypes(TripType.EXCLUSIVE)
.setMaximumCapacity(4)
.setVehicleType(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
.addAttributes(VehicleAttribute.newBuilder()
.setKey("on_trip").setValue("false")) // Opaque to the Fleet Engine
// Add .setBackToBackEnabled(true) to make this vehicle eligible for trip
// matching while even if it is on a trip. By default this is disabled.
.build();
CreateVehicleRequest createVehicleRequest =
CreateVehicleRequest.newBuilder() // no need for the header
.setParent(parent)
.setVehicleId("vid-8241890") // Vehicle ID assigned by Rideshare or Delivery Provider
.setVehicle(vehicle) // Initial state
.build();
// In this case, the Vehicle is being created in the OFFLINE state and
// no initial position is being provided. When the Driver App checks
// in with the Rideshare or Delivery Provider, the state can be set to ONLINE and
// the Driver App will update the Vehicle Location.
try {
Vehicle createdVehicle =
vehicleService.createVehicle(createVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
// If no Exception, Vehicle created successfully.
Log platform Google Cloud untuk pembuatan Kendaraan
Fleet Engine API menulis entri log melalui log platform Google Cloud saat panggilan ke endpoint CreateVehicle
diterima. Entri log ini menyertakan
informasi tentang nilai dalam permintaan CreateVehicle
. Jika panggilan
berhasil, informasi tentang Vehicle
yang ditampilkan juga akan disertakan.
shell
gcloud --project=project-id logging read --freshness=1h '
jsonPayload.request.vehicleId="vid-8241890"
jsonPayload.@type="type.googleapis.com/maps.fleetengine.v1.CreateVehicleLog"
'
Harus mencetak data yang mirip dengan berikut ini:
---
insertId: c2cf4d3a180251c1bdb892137c14f022
jsonPayload:
'@type': type.googleapis.com/maps.fleetengine.v1.CreateVehicleLog
request:
vehicle:
attributes:
- key: on_trip
value: 'false'
maximumCapacity: 4
state: VEHICLE_STATE_OFFLINE
supportedTrips:
- EXCLUSIVE_TRIP
vehicleType:
vehicleCategory: AUTO
vehicleId: vid-8241890
response:
attributes:
- key: on_trip
value: 'false'
availableCapacity: 4
currentRouteSegmentHandle: AdSiwAwCO9gZ7Pw5UZZimOXOo41cJTjg/r3SuwVPQmuuaV0sU3+3UCY+z53Cl9i6mWHLoCKbBt9Vsj5PMRgOJ8zX
maximumCapacity: 4
name: providers/project-id/vehicles/vid-8241890
state: VEHICLE_STATE_OFFLINE
supportedTrips:
- EXCLUSIVE_TRIP
vehicleType:
vehicleCategory: AUTO
labels:
vehicle_id: vid-8241890
logName: projects/project-id/logs/fleetengine.googleapis.com%2Fcreate_vehicle
receiveTimestamp: '2021-09-22T03:25:16.361159871Z'
resource:
labels:
location: global
resource_container: projects/project-id
type: fleetengine.googleapis.com/Fleet
timestamp: '2021-09-22T03:25:15.724998Z'
Notifikasi Cloud Pub/Sub untuk pembuatan Kendaraan
Fleet Engine API memublikasikan notifikasi melalui Cloud Pub/Sub saat kendaraan baru dibuat. Untuk menerima notifikasi ini, ikuti petunjuk di sini.
CARANYA: Perbarui lokasi Kendaraan
Jika tidak menggunakan Driver SDK untuk memperbarui lokasi kendaraan, Anda dapat melakukan panggilan langsung ke Fleet Engine dengan lokasi kendaraan. Untuk semua kendaraan yang aktif, Fleet Engine mengharapkan pembaruan lokasi setidaknya sekali setiap menit dan paling sekali setiap 5 detik. Update ini hanya memerlukan hak istimewa Pengguna Fleet Engine Driver SDK.
Contoh
shell
curl -X PUT \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=last_location" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"supplementalLocation": {"latitude": 12.1, "longitude": 14.5},
"supplementalLocationTime": "$(date -u --iso-8601=seconds)",
"supplementalLocationSensor": "CUSTOMER_SUPPLIED_LOCATION",
"supplementalLocationAccuracy": 15
}
EOM
Lihat referensi providers.vehicles.update.
Java
static final String PROJECT_ID = "project-id";
static final String VEHICLE_ID = "vid-8241890";
VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);
String vehicleName = "providers/" + PROJECT_ID + "/vehicles/" + VEHICLE_ID;
Vehicle updatedVehicle = Vehicle.newBuilder()
.setLastLocation(VehicleLocation.newBuilder()
.setSupplementalLocation(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863))
.setSupplementalLocationTime(now())
.setSupplementalLocationSensor(LocationSensor.CUSTOMER_SUPPLIED_LOCATION)
.setSupplementalLocationAccuracy(DoubleValue.of(15.0))) // Optional)
.build();
UpdateVehicleRequest updateVehicleRequest = UpdateVehicleRequest.newBuilder()
.setName(vehicleName)
.setVehicle(updatedVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("last_location"))
.build();
try {
Vehicle updatedVehicle =
vehicleService.updateVehicle(updateVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
// Most implementations will call CreateVehicle in this case
break;
case PERMISSION_DENIED:
break;
}
return;
}
// If no Exception, Vehicle updated successfully.
CARANYA: Perbarui kolom Kendaraan lainnya
Pembaruan pada atribut lain dari status Kendaraan lebih jarang terjadi daripada
pembaruan posisi. Update pada atribut selain last_location
memerlukan
hak istimewa Pengguna Super Flet Engine.
UpdateVehicleRequest
menyertakan update_mask
untuk menunjukkan kolom mana yang akan
diperbarui. Perilaku kolom ini seperti dalam dokumentasi Protobuf untuk mask kolom.
Seperti yang tercantum dalam Atribut Kendaraan, memperbarui
kolom attributes
mengharuskan penulisan semua atribut yang akan dipertahankan. Anda
tidak dapat hanya memperbarui nilai satu pasangan nilai kunci dalam sebuah
panggilan UpdateVehicle
. Untuk memperbarui nilai atribut tertentu, UpdateVehicleAttributes
API dapat digunakan.
Contoh
Contoh ini mengaktifkan back_to_back
.
shell
curl -X PUT \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=vehicle_state,attributes,back_to_back_enabled" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"vehicleState": "ONLINE",
"attributes": [
{"key": "on_trip", "value": "true"},
{"key": "cash_only", "value": "false"}
],
"backToBackEnabled": true
}
EOM
Lihat referensi providers.vehicles.update.
Java
static final String PROJECT_ID = "project-id";
static final String VEHICLE_ID = "vid-8241890";
VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);
String vehicleName = "providers/" + PROJECT_ID + "/vehicles/" + VEHICLE_ID;
Vehicle updatedVehicle = Vehicle.newBuilder()
.setVehicleState(VehicleState.ONLINE)
.addAllAttributes(ImmutableList.of(
VehicleAttribute.newBuilder().setKey("on_trip").setValue("true").build(),
VehicleAttribute.newBuilder().setKey("cash_only").setValue("false").build()))
.setBackToBackEnabled(true)
.build();
UpdateVehicleRequest updateVehicleRequest = UpdateVehicleRequest.newBuilder()
.setName(vehicleName)
.setVehicle(updatedVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("vehicle_state")
.addPaths("attributes")
.addPaths("back_to_back_enabled"))
.build();
// Attributes and vehicle state are being updated, so both are
// included in the field mask. Note that of on_trip were
// not being updated, but rather cash_only was being changed,
// the desired value of "on_trip" would still need to be written
// as the attributes are completely replaced in an update operation.
try {
Vehicle updatedVehicle =
vehicleService.updateVehicle(updateVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
// Most implementations will call CreateVehicle in this case
break;
case PERMISSION_DENIED:
break;
}
return;
}
// If no Exception, Vehicle updated successfully.
Log platform Google Cloud untuk Update Kendaraan
Fleet Engine API menulis entri log melalui log platform Google Cloud saat panggilan ke endpoint UpdateVehicle
diterima. Entri log ini menyertakan
informasi tentang nilai dalam permintaan UpdateVehicle
. Jika panggilan
berhasil, informasi tentang Vehicle
yang ditampilkan juga akan disertakan.
shell
gcloud --project=project-id logging read --freshness=1h '
jsonPayload.request.vehicleId="vid-8241890"
jsonPayload.@type="type.googleapis.com/maps.fleetengine.v1.UpdateVehicleLog"
'
Notifikasi Cloud Pub/Sub untuk update Kendaraan
Fleet Engine API memublikasikan notifikasi melalui Cloud Pub/Sub saat kendaraan yang ada diupdate. Untuk menerima notifikasi ini, ikuti petunjuk di sini.
PETUNJUK: Telusuri kendaraan
Fleet Engine mendukung pencarian kendaraan. SearchVehicles
API memungkinkan Anda menemukan pengemudi terdekat yang tersedia dan paling sesuai dengan tugas seperti
menyalurkan angkutan atau permintaan pesan antar. SearchVehicles
API menampilkan
daftar peringkat pengemudi yang mencocokkan atribut tugas dengan atribut kendaraan di
armada Anda. Untuk informasi selengkapnya, lihat
Menemukan pengemudi terdekat.
Contoh
Saat menelusuri kendaraan yang tersedia, Fleet Engine mengecualikan kendaraan yang sedang dalam perjalanan aktif secara default. Layanan Transportasi Online atau Penyedia Pesan Antar harus menyertakannya secara eksplisit dalam permintaan penelusuran. Contoh berikut menunjukkan cara menyertakan kendaraan tersebut dalam penelusuran kendaraan yang cocok dengan perjalanan dari Grand Indonesia East Mall ke Balai Sidang Jakarta Convention Center.
shell
Pertama, perbarui lokasi kendaraan yang kita buat pada langkah sebelumnya agar memenuhi syarat. Di dunia nyata, hal ini akan dilakukan oleh Driver SDK yang berjalan pada perangkat Android atau iOS di dalam kendaraan.
curl -X PUT \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=last_location,attributes" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"lastLocation": {
"updateTime": "$( date -u +"%Y-%m-%dT%H:%M:%SZ" )",
"location": {
"latitude": "-6.195139",
"longitude": "106.820826"
}
},
"attributes": [{"key": "on_trip", "value": "false"}]
}
EOM
Melakukan penelusuran akan menghasilkan setidaknya kendaraan tersebut.
curl -X POST \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles:search" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"pickupPoint": {
"point": {"latitude": "-6.195139", "longitude": "106.820826"}
},
"dropoffPoint": {
"point": {"latitude": "-6.1275", "longitude": "106.6537"}
},
"pickupRadiusMeters": 2000,
"count": 10,
"minimumCapacity": 2,
"tripTypes": ["EXCLUSIVE"],
"vehicleTypes": [{"category": "AUTO"}],
"filter": "attributes.on_trip=\"false\"",
"orderBy": "PICKUP_POINT_ETA",
"includeBackToBack": true
}
EOM
Lihat referensi providers.vehicles.search.
Java
static final String PROJECT_ID = "project-id";
VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);
String parent = "providers/" + PROJECT_ID;
SearchVehiclesRequest searchVehiclesRequest = SearchVehiclesRequest.newBuilder()
.setParent(parent)
.setPickupPoint( // Grand Indonesia East Mall
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setDropoffPoint( // Balai Sidang Jakarta Convention Center
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.213796).setLongitude(106.807195)))
.setPickupRadiusMeters(2000)
.setCount(10)
.setMinimumCapacity(2)
.addTripTypes(TripType.EXCLUSIVE)
.addVehicleTypes(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
.setFilter("attributes.on_trip=\"false\"")
.setOrderBy(VehicleMatchOrder.PICKUP_POINT_ETA)
.setIncludeBackToBack(true) // Fleet Engine includes vehicles that are en route.
.build();
// Error handling
// If matches are returned and the authentication passed, the request completed
// successfully
try {
SearchVehiclesResponse searchVehiclesResponse =
vehicleService.searchVehicles(searchVehiclesRequest);
// Search results: Each vehicle match contains a vehicle entity and information
// about the distance and ETA to the pickup point and dropoff point.
List<VehicleMatch> vehicleMatches = searchVehiclesResponse.getMatchesList();
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
Kueri pemfilteran kendaraan
SearchVehicles
dan ListVehicles
mendukung pemfilteran pada atribut kendaraan
menggunakan kueri filter. Untuk sintaksis kueri filter, lihat
AIP-160 untuk mengetahui contohnya.
Perhatikan bahwa kueri filter HANYA mendukung pemfilteran pada atribut kendaraan, dan tidak dapat digunakan untuk kolom lain. Kueri filter berfungsi sebagai klausa AND
dengan batasan lain, seperti minimum_capacity
atau vehicle_types
dalam
SearchVehiclesRequest
.
PETUNJUK: Buat daftar kendaraan
SearchVehicles
dioptimalkan untuk menemukan kendaraan dalam jumlah kecil sesuai urutan
dengan sangat cepat dan terutama digunakan untuk menemukan pengemudi terdekat yang paling sesuai
untuk suatu tugas. Namun, terkadang Anda ingin menemukan semua kendaraan yang memenuhi beberapa
kriteria meskipun paging melalui hasil penelusuran diperlukan. ListVehicles
dirancang untuk kasus penggunaan tersebut.
ListVehicles
API memungkinkan Anda menemukan semua kendaraan yang memenuhi beberapa opsi
permintaan tertentu. ListVehicles
API menampilkan daftar kendaraan yang diberi nomor halaman dalam project yang sesuai dengan beberapa persyaratan.
Untuk memfilter atribut kendaraan, lihat Kueri pemfilteran kendaraan.
Contoh
Contoh ini melakukan pemfilteran pada vehicle_type
dan atribut menggunakan
string filter
.
shell
curl -X POST \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles:list" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"vehicleTypes": [{"category": "AUTO"}],
"filter": "attributes.on_trip=\"false\"",
}
EOM
Lihat referensi providers.vehicles.list.
Java
static final String PROJECT_ID = "project-id";
VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);
String parent = "providers/" + PROJECT_ID;
ListVehiclesRequest listVehiclesRequest = ListVehiclesRequest.newBuilder()
.setParent(parent)
.addTripTypes(TripType.EXCLUSIVE)
.addVehicleTypes(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
.setFilter("attributes.on_trip=\"false\"")
.setIncludeBackToBack(true) // Fleet Engine includes vehicles that are en route.
.build();
// Error handling
// If matches are returned and the authentication passed, the request completed
// successfully
try {
ListVehiclesResponse listVehiclesResponse =
vehicleService.listVehicles(listVehiclesRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
Perjalanan dan siklus prosesnya
Trip API dan siklus proses mirip dengan Vehicle API dan siklus proses.
Penyedia Rideshare bertanggung jawab membuat perjalanan menggunakan antarmuka
Fleet Engine. Fleet Engine menyediakan layanan RPC,
TripService
, dan resource REST, provider.trips
. Antarmuka ini memungkinkan pembuatan entitas Perjalanan, permintaan informasi, fungsi
penelusuran, dan kemampuan mengupdate.
Trip
memiliki kolom status untuk melacak progresnya selama siklus proses.
Nilai akan berpindah dari NEW
ke COMPLETE
plus CANCELED
dan UNKNOWN_TRIP_STATUS
. Lihat trip_status
untuk RPC
atau TripStatus untuk REST.
NEW
ENROUTE_TO_PICKUP
ARRIVED_AT_PICKUP
ENROUTE_TO_INTERMEDIATE_DESTINATION
ARRIVED_AT_INTERMEDIATE_DESTINATION
ENROUTE_TO_DROPOFF
COMPLETE
Layanan Anda dapat memperbarui perjalanan ke CANCELED
dari salah satu status ini.
Saat layanan Anda membuat perjalanan, mesin akan menyetel status sebagai NEW
. vehicle_id
bersifat opsional. Seperti kendaraan, layanan akan otomatis menghapus perjalanan yang belum ditetapkan setelah tujuh hari tanpa pembaruan. Jika layanan Anda mencoba membuat perjalanan dengan ID yang sudah ada, pesan error akan ditampilkan. Perjalanan dianggap 'aktif' jika
statusnya selain COMPLETE
atau CANCELED
. Perbedaan ini
penting di kolom active_trips
di entity Kendaraan dan SearchTripsRequest
.
Layanan Anda hanya dapat mengubah vehicle_id
yang ditetapkan ke sebuah perjalanan saat perjalanan tersebut aktif. Misalnya, Anda akan melakukannya saat pengemudi membatalkan perjalanan saat sedang dalam
rute dan perjalanan tersebut ditetapkan ulang ke kendaraan lain.
Status ini penting saat menerapkan dukungan perjalanan back-to-back. Dukungan ini memungkinkan Penyedia menetapkan perjalanan baru ke Kendaraan saat Kendaraan tersebut sedang dalam Perjalanan aktif. Kode untuk membuat Perjalanan back-to-back sama dengan perjalanan tunggal dan menggunakan ID kendaraan yang sama. Fleet Engine menambahkan asal dan tujuan perjalanan baru ke titik jalan kendaraan. Untuk informasi selengkapnya tentang perjalanan bolak-balik, lihat Membuat perjalanan Multi-titik jalan.
Titik jalan perjalanan yang tersisa
Entity Perjalanan berisi kolom berulang TripWaypoint
(RPC | REST), yang disebut remainingWaypoints
(RPC | REST).
Kolom ini menyertakan semua titik jalan yang akan perlu dilalui kendaraan secara berurutan sebelum titik penurunan terakhir perjalanan ini. Layanan ini menghitung dari
Titik jalan kendaraan yang tersisa.
Dalam kasus penggunaan Back-to-back dan Carpool, daftar ini berisi titik jalan dari
perjalanan lain yang akan dilintasi sebelum perjalanan ini, tetapi tidak termasuk titik jalan
setelah perjalanan ini. Titik jalan dalam daftar dapat diidentifikasi dengan TripId
dan WaypointType
.
Hubungan antara status perjalanan dan Titik jalan kendaraan yang tersisa
Titik jalan kendaraan yang tersisa (RPC | REST) akan
diperbarui saat Fleet Engine menerima permintaan perubahan status perjalanan. Titik jalan sebelumnya akan dihapus dari daftar titik jalan Kendaraan yang tersisa saat tripStatus
(RPC | REST) diubah dari status lain menjadi ENROUTE_TO_XXX. Artinya, jika
status perjalanan diubah dari ENROUTE_TO_PICKUP menjadi ARRIVED_AT_PICKUP, titik pengambilan
perjalanan akan tetap berada di daftar titik jalan lainnya di Kendaraan, tetapi saat status
perjalanan diubah menjadi ENROUTE_TO_INTERMEDIATE_DIRECTION atau ENROUTE_TO_DROPOFF, titik pengambilan yang tersisa akan dihapus dari kendaraan tersebut.
Hal ini juga berlaku untuk ARRIVED_AT_INTERMEDIATE_DESTINATION dan ENROUTE_TO_INTERMDEDIATE_DESTINATION. Saat ARRIVED_AT_INTERMEDIATE_DESTINATION, tujuan perantara saat ini tidak akan dihapus dari daftar titik jalan yang tersisa di Kendaraan hingga kendaraan melaporkan bahwa tujuan tersebut mengarah ke titik jalan berikutnya.
Jika status perjalanan diubah menjadi COMPLETED
, tidak ada titik jalan dari perjalanan ini yang akan berada di daftar titik jalan Kendaraan yang tersisa.
CARANYA: Buat perjalanan
Entitas Trip
harus dibuat agar setiap permintaan perjalanan dapat dilacak dan dicocokkan dengan Kendaraan di armada. Gunakan endpoint CreateTrip
dengan CreateTripRequest
untuk membuat Perjalanan.
Atribut berikut diperlukan untuk membuat perjalanan:
parent
- String yang menyertakan ID Penyedia yang dibuat saat Project Google Cloud dibuat.trip_id
- String yang dibuat oleh Penyedia Transportasi Online.trip
- Penampung dengan metadata dasar yang menjelaskan perjalanan.trip_type
- Enum yang mewakili apakah perjalanan mungkin memiliki penumpang lain dari asal dan tujuan yang berbeda di dalam kendaraan yang sama (SHARED
) atau hanya satu pihak (EXCLUSIVE
).pickup_point
- TerminalLocation yang mewakili titik asal untuk perjalanan. Lihat referensi RPC atau referensi REST
Saat membuat perjalanan, Anda dapat memberikan number_of_passengers
, dropoff_point
,
dan vehicle_id
. Meskipun tidak wajib, kolom ini akan dipertahankan jika Anda memberikannya. Semua kolom Perjalanan lainnya akan diabaikan. Misalnya, semua perjalanan
dimulai dengan trip_status
dari NEW
meskipun Anda meneruskan trip_status
dari
CANCELED
dalam permintaan pembuatan.
Contoh
Contoh berikut membuat perjalanan ke Grand Indonesia East Mall. Perjalanan ini bersifat eksklusif
untuk dua penumpang. provider_id
dari Trip
harus sama dengan Project ID. Dalam contoh, Penyedia Rideshare membuat Project Google Cloud, project-id. Project ini harus memiliki Akun Layanan yang digunakan untuk memanggil Fleet Engine. Status perjalanan adalah NEW
.
Kemudian, setelah layanan cocok dengan perjalanan ke kendaraan, layanan dapat memanggil
UpdateTrip
dan mengubah vehicle_id
saat perjalanan ditetapkan ke kendaraan.
shell
curl -X POST \
"https://fleetengine.googleapis.com/v1/providers/project-id/trips?tripId=tid-1f97" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"tripType": "EXCLUSIVE",
"numberOfPassengers": 2,
"pickupPoint": {
"point": {"latitude": "-6.195139", "longitude": "106.820826"}
},
"dropoffPoint": {
"point": {"latitude": "-6.1275", "longitude": "106.6537"}
}
}
EOM
Lihat referensi providers.trips.create.
Java
static final String PROJECT_ID = "project-id";
TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);
String parent = "providers/" + PROJECT_ID;
Trip trip = Trip.newBuilder()
.setTripType(TripType.EXCLUSIVE) // Use TripType.SHARED for carpooling
.setPickupPoint( // Grand Indonesia East Mall
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
// Provide the number of passengers if available.
.setNumberOfPassengers(2)
// Provide the drop-off point if available.
.setDropoffPoint(
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.1275).setLongitude(106.6537)))
.build();
CreateTripRequest createTripRequest =
CreateTripRequest.newBuilder() // no need for the header
.setParent(parent)
.setTripId("tid-1f97") // Trip ID assigned by the Provider
.setTrip(trip) // Initial state
.build();
// Error handling
// If Fleet Engine does not have trip with that id and the credentials of the
// requestor pass, the service creates the trip successfully.
try {
Trip createdTrip =
tripService.createTrip(createTripRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
Log platform Google Cloud untuk Pembuatan Perjalanan
Fleet Engine API menulis entri log menggunakan log platform Google Cloud saat panggilan ke endpoint CreateTrip
diterima. Entri log ini menyertakan
informasi tentang nilai dalam permintaan CreateTrip
. Jika panggilan
berhasil, informasi tentang Trip
yang ditampilkan juga akan disertakan.
CARANYA: Memperbarui perjalanan
Entitas Perjalanan berisi kolom yang memungkinkan pelacakan oleh layanan dan untuk
melaporkan progres perjalanan oleh Driver SDK dan ke
Consumer SDK. Untuk memperbarui properti, gunakan pesan UpdateTripRequest
. Tindakan ini akan memperbarui kolom Perjalanan sesuai dengan field_mask
permintaan.
Lihat UpdateTripRequest.
Penyedia Rideshare bertanggung jawab untuk memperbarui atribut berikut:
- Status perjalanan.
- ID Kendaraan. Baik pada saat pembuatan, maupun setelah mencocokkan kendaraan dengan perjalanan.
- Perubahan pada penjemputan, penurunan, atau titik jalan.
Fleet Engine otomatis memperbarui kolom berikut saat menggunakan fitur Berbagi Perjalanan melalui Driver SDK atau Consumer SDK:
- Rute
- PWT
- Jarak yang tersisa
- Lokasi kendaraan
- Titik jalan lainnya
Lihat Trip
di RPC atau
Resource.Trip
di REST.
Log platform Google Cloud untuk Info Terbaru Perjalanan
Fleet Engine API menulis entri log menggunakan log platform Google Cloud saat panggilan ke endpoint UpdateTrip
diterima. Entri log ini menyertakan
informasi tentang nilai dalam permintaan UpdateTrip
. Jika panggilan berhasil,
informasi tentang Trip
yang ditampilkan juga akan disertakan.
CARA KERJA: Perjalanan penelusuran
Fleet Engine mendukung penelusuran perjalanan. Seperti disebutkan sebelumnya, Perjalanan
otomatis dihapus setelah tujuh hari, sehingga SearchTrips
tidak
mengekspos histori lengkap semua Perjalanan.
Meskipun SearchTrips
adalah API fleksibel, daftar di bawah mempertimbangkan dua kasus penggunaan.
Menentukan Perjalanan Aktif Kendaraan -- Penyedia dapat menentukan perjalanan kendaraan yang sedang aktif. Dalam
SearchTripsRequest
,vehicle_id
ditetapkan ke kendaraan yang dipertimbangkan danactive_trips_only
harus ditetapkan ketrue
.Merekonsiliasi Penyedia dan Status Fleet Engine -- Penyedia dapat menggunakan
SearchTrips
untuk memastikan status Perjalanan mereka dan status Fleet Engine sesuai. Hal ini sangat penting untuk TripStatus. Jika status perjalanan yang ditetapkan ke Kendaraan tidak ditetapkan dengan benar keCOMPLETE
atauCANCELED
, Kendaraan tidak akan disertakan olehSearchVehicles
.
Untuk menggunakan SearchTrips
dengan cara ini, kosongkan vehicle_id
, tetapkan active_trips_only
ke true
, dan setel minimum_staleness
ke waktu yang lebih lama dari sebagian besar durasi perjalanan.
Misalnya, Anda dapat menggunakan satu jam. Hasilnya mencakup Perjalanan yang tidak
SELESAI atau DIBATALKAN, dan belum diperbarui selama lebih dari satu jam. Penyedia
harus memeriksa Perjalanan ini untuk memastikan statusnya di Fleet Engine
diperbarui dengan benar.
Pemecahan masalah
Dalam kasus Error DEADLINE_EXCEEDED
, status Fleet Engine tidak diketahui. Penyedia harus memanggil CreateTrip
lagi, yang akan menampilkan
201 (CREATED) atau 409 (CONFLICT). Dalam kasus yang terakhir, permintaan sebelumnya berhasil
sebelum DEADLINE_EXCEEDED
. Lihat panduan Consumer API untuk mengetahui informasi selengkapnya
tentang cara menangani error perjalanan: Android
atau iOS.
Dukungan perjalanan Carpool
Anda dapat menetapkan beberapa perjalanan SHARED
ke kendaraan yang mendukung TripType.SHARED
.
Anda perlu menentukan urutan semua titik jalan yang belum dilewati untuk semua Perjalanan yang ditetapkan ke
Kendaraan dalam perjalanan bersama ini melalui Trip.vehicle_waypoints
saat Anda menetapkan
vehicle_id
untuk perjalanan bersama (dalam permintaan CreateTrip
atau UpdateTrip
).
Lihat vehicle_waypoints
untuk RPC
atau vehicleWaypoints
untuk REST.
Dukungan beberapa tujuan
Mengidentifikasi tujuan perantara
Kolom intermediateDestinations
dan kolom intermediateDestinationIndex
di Perjalanan (RPC | REST)
digabungkan untuk menunjukkan tujuan.
Memperbarui tujuan perantara
Anda dapat memperbarui tujuan perantara melalui UpdateTrip
. Saat memperbarui
tujuan perantara, Anda harus memberikan daftar lengkap tujuan perantara,
termasuk tujuan yang telah dikunjungi, bukan hanya yang baru
ditambahkan atau yang akan diubah.
Saat intermediateDestinationIndex
mengarah ke indeks setelah posisi
tujuan perantara yang baru ditambahkan/diubah, tujuan perantara yang baru/diperbarui
tidak akan ditambahkan ke waypoints
Kendaraan atau remainingWaypoints
Perjalanan.
Alasannya adalah setiap tujuan perantara sebelum intermediateDestinationIndex
dianggap sebagai telah dikunjungi.
Perubahan status perjalanan
Kolom intermediateDestinationsVersion
di (RPC | REST)
diperlukan dalam permintaan pembaruan status Perjalanan yang dikirim ke Fleet Engine untuk menunjukkan
tujuan perantara telah lulus. Tujuan perantara yang ditargetkan
ditentukan melalui kolom intermediateDestinationIndex
.
Jika tripStatus
(RPC | REST) adalah ENROUTE_TO_INTERMEDIATE_DESTINATION, angka antara
[0..N-1] menunjukkan tujuan perantara mana yang akan dilewati kendaraan berikutnya.
Jika tripStatus
adalah ARRIVED_AT_INTERMEDIATE_DESTINATION, angka antara
[0..N-1] menunjukkan tujuan perantara mana kendaraan berada.
Contoh
Contoh kode berikut menunjukkan cara memperbarui status perjalanan untuk perjalanan ke tujuan perantara pertamanya, dengan asumsi bahwa Anda telah membuat perjalanan multi-tujuan dan perjalanan tersebut telah melewati titik penjemputannya.
Java
static final String PROJECT_ID = "project-id";
static final String TRIP_ID = "multi-destination-trip-A";
String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_ID;
Trip trip = …; // Fetch trip object from FleetEngine or your storage.
TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);
// Trip settings to update.
Trip trip = Trip.newBuilder()
// Trip status cannot go back to a previous status once it is passed
.setTripStatus(TripStatus.ENROUTE_TO_INTERMEDIATE_DESTINATION)
// Enrouting to the first intermediate destination.
.setIntermediateDestinationIndex(0)
// intermediate_destinations_version MUST be provided to ensure you
// have the same picture on intermediate destinations list as FleetEngine has.
.setIntermediateDestinationsVersion(
trip.getIntermediateDestinationsVersion())
.build();
// 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: // Trip does not exist.
break;
case FAILED_PRECONDITION: // The given trip status is invalid, or the
// intermediate_destinations_version
// doesn’t match FleetEngine’s.
break;
case PERMISSION_DENIED:
break;
}
return;
}
CARANYA: Berlangganan pesan notifikasi dari Fleet Engine API
Fleet Engine API menggunakan Google Cloud Pub/Sub untuk memublikasikan notifikasi mengenai topik yang dibuat oleh Project Google Cloud konsumen. Pub/Sub tidak diaktifkan secara default untuk Fleet Engine di project Google Cloud Anda. Ajukan kasus dukungan atau hubungi Customer Engineer Anda untuk mengaktifkan Pub/Sub.
Untuk membuat topik di Project Cloud, ikuti petunjuk ini. ID topik harus 'fleet_engine_notifications'.
Topik harus dibuat di project Cloud yang sama dengan yang memanggil Fleet Engine API.
Setelah topik dibuat, Anda harus memberi izin Fleet Engine API
untuk memublikasikan topik tersebut. Untuk melakukannya, klik topik yang
baru saja dibuat dan tambahkan izin baru. Anda mungkin harus mengklik TAMPILKAN Panel INFO untuk membuka editor izin.
Akun utama harus geo-fleet-engine@system.gserviceaccount.com
dan perannya harus Pub/Sub publisher
.
Untuk menyiapkan Project Cloud agar berlangganan notifikasi, ikuti petunjuk ini
Fleet Engine API akan memublikasikan setiap notifikasi dalam dua format data
yang berbeda, yaitu protobuf
dan
json
. Format data untuk setiap notifikasi ditunjukkan dalam atribut PubsubMessage dengan kunci sebagai data_format
dan nilainya sebagai protobuf
atau json
.
Skema notifikasi:
Protobuf
// A batch of notifications that is published by the Fleet Engine service using
// Cloud Pub/Sub in a single PubsubMessage.
message BatchNotification {
// Required. At least one notification must exist.
// List of notifications containing information related to changes in
// Fleet Engine data.
repeated Notification notifications = 1;
}
// A notification related to changes in Fleet Engine data.
// The data provides additional information specific to the type of the
// notification.
message Notification {
// Required. At least one type must exist.
// Type of notification.
oneof type {
// Notification related to changes in vehicle data.
VehicleNotification vehicle_notification = 1;
}
}
// Notification sent when a new vehicle was created.
message CreateVehicleNotification {
// Required.
// Vehicle must contain all fields that were set when it was created.
Vehicle vehicle = 1;
}
// Notification sent when an existing vehicle is updated.
message UpdateVehicleNotification {
// Required.
// Vehicle must only contain name and fields that are present in the
// field_mask field below.
Vehicle vehicle = 1;
// Required.
// Contains vehicle field paths that were specifically requested
// by the Provider.
google.protobuf.FieldMask field_mask = 2;
}
// Notification related to changes in vehicle data.
message VehicleNotification {
// Required. At least one type must be set.
// Type of notification.
oneof type {
// Notification sent when a new vehicle was created.
CreateVehicleNotification create_notification = 1;
// Notification sent when an existing vehicle is updated.
UpdateVehicleNotification update_notification = 2;
}
}
JSON
BatchNotification: {
"description": "A batch of notifications that is published by the Fleet Engine service using Cloud Pub/Sub in a single PubsubMessage.",
"type": "object",
"required": ["notifications"],
"properties": {
"notifications": {
"description": "At least one notification must exist. List of notifications containing information related to changes in Fleet Engine data.",
"type": "Notification[]"
}
}
}
Notification: {
"description": "A notification related to changes in Fleet Engine data. The data provides additional information specific to the type of the notification.",
"type": "object",
"properties": {
"vehicleNotification": {
"description": "Notification related to changes in vehicle data.",
"type": "VehicleNotification"
}
}
}
VehicleNotification: {
"description": "Notification related to changes in vehicle data.",
"type": "object",
"properties": {
"createNotification": {
"description": "Notification sent when a new vehicle was created.",
"type": "CreateVehicleNotification"
},
"updateNotification": {
"description": "Notification sent when an existing vehicle is updated.",
"type": "UpdateVehicleNotification"
}
}
}
CreateVehicleNotification: {
"description": "Notification sent when a new vehicle was created.",
"type": "object",
"required": ["vehicle"],
"properties": {
"vehicle": {
"description": "Vehicle must contain all fields that were set when it was created.",
"type": "Vehicle"
}
}
}
UpdateVehicleNotification: {
"description": "Notification sent when an existing vehicle is updated.",
"type": "object",
"required": ["vehicle", "fieldMask"],
"properties": {
"vehicle": {
"description": "Vehicle must only contain name and fields that are present in the fieldMask field below.",
"type": "Vehicle"
},
"fieldMask": {
"description": "Contains vehicle field paths that were specifically requested by the Provider.",
"type": "FieldMask"
}
}
}