Buat model aktivitas armada Anda untuk mil pertama dan terakhir pengiriman dengan Fleet Engine Deliveries API. Anda dapat menggunakan API ini menggunakan Driver SDK untuk Android dan iOS, atau secara langsung menggunakan panggilan gRPC atau REST HTTP.
Penyiapan awal
Anda mengonfigurasi Fleet Engine Deliveries API di Google Cloud Console.
Untuk informasi tentang langkah-langkah yang harus dilakukan dalam konsol dan cara membuat Token Web JSON untuk otorisasi, lihat Autentikasi dan otorisasi.
Untuk detail tentang cara menggunakan konsol, lihat Dokumentasi Konsol Google Cloud.
Memverifikasi penyiapan Anda
Setelah membuat akun layanan, pastikan penyiapan Anda sudah selesai dan Anda dapat membuat kendaraan pengiriman. Segera verifikasi konfigurasi Anda memastikan bahwa Anda telah mengatasi masalah otorisasi umum yang dapat timbul saat menyiapkan proyek Anda. Ada dua cara untuk memverifikasi konfigurasi Anda:
Uji dua bagian penting penyiapan Anda: penandatanganan token otorisasi dan pengiriman uji coba pembuatan kendaraan dengan Utilitas command line
gcloud
. Sebagai lihat detail Memverifikasi penyiapan kami.Uji konfigurasi Anda dengan Contoh Skrip Autentikasi Armada Mesin.
Library Klien
Untuk pengalaman developer yang lebih baik melalui gRPC atau REST mentah, gunakan library klien dalam beberapa bahasa pemrograman yang umum. Sebagai instruksi cara mendapatkan library klien untuk aplikasi server Anda, lihat Library Klien.
Contoh Java dalam dokumentasi ini mengasumsikan bahwa Anda sudah memahami gRPC.
Struktur data
Fleet Engine Deliveries API menggunakan dua struktur data untuk membuat model pengambilan dan pengiriman dari pengiriman:
- Kendaraan pengiriman yang digunakan untuk mengangkut kiriman.
- Tugas pengambilan dan pengiriman kiriman.
Anda juga menggunakan tugas untuk membuat model waktu istirahat bagi pengemudi dan perhentian terjadwal sepanjang hari.
Kendaraan pengiriman
Kendaraan pengiriman mengangkut kiriman dari depot ke lokasi pengiriman, dan dari lokasi penjemputan ke depot. Dalam kasus tertentu, mereka mungkin juga mengangkut pengiriman langsung dari lokasi pengambilan ke lokasi pengiriman.
Menggunakan Driver SDK untuk membuat objek DeliveryVehicle
di Fleet Engine
dan mengirim pembaruan lokasi untuk
pengiriman dan pelacakan armada.
DeliveryVehicle
.
Tugas
Untuk tindakan yang dilakukan kendaraan dalam sehari, Anda menetapkan tugas sesuai dengan jenis tindakan:
- Untuk pengambilan dan pengantaran, tetapkan Tugas pengiriman.
- Ketika pengemudi tidak dapat tersedia, seperti waktu istirahat yang diperlukan, menetapkan Tugas ketidaktersediaan.
- Untuk tugas non-mengemudi di drop box atau lokasi pelanggan, tetapkan Tugas perhentian terjadwal.
Setiap tugas yang Anda tetapkan harus memiliki ID tugas unik, tetapi tugas dapat berbagi tugas yang sama ID pelacakan. Saat Fleet Engine menghitung PWT jendela untuk setiap tugas, ia menggunakan semua tugas dan urutan di mana mereka dijadwalkan untuk membuat perkiraan. Untuk informasi lebih lanjut tentang ID tugas, lihat Panduan ID tugas.
Untuk membuat tugas di Fleet Engine, gunakan Task Manager Driver SDK.
Tugas pengiriman
Membuat tugas pengiriman untuk pengambilan dan pengantaran kiriman, dan sertakan informasi berikut:
- Lokasi pengambilan atau pengiriman.
- Nomor atau ID pelacakan.
- {i>Dwell time<i} untuk memperhitungkan waktu tambahan untuk menyelesaikan tugas, lihat untuk tempat parkir, atau berjalan ke lokasi penyerahan.
- ID tugas unik. Lihat Panduan ID Tugas.
Untuk informasi selengkapnya, lihat topik berikut:
Android
iOS
Tugas ketidaktersediaan
Tugas ketidaktersediaan mencakup jangka waktu saat kendaraan tidak tersedia penjemputan atau pengiriman, seperti istirahat untuk mengisi bahan bakar kendaraan atau pengemudi beristirahat.
Buat tugas ketidaktersediaan dengan informasi berikut:
- Lamanya jeda.
- (Opsional) Lokasi istirahat. Anda tidak perlu memberikan di lokasi tertentu, tetapi hal itu akan memberikan periode PWT yang lebih akurat sepanjang hari.
Untuk informasi selengkapnya, lihat topik berikut:
Android
iOS
Tugas perhentian terjadwal
Buat tugas perhentian terjadwal untuk membuat model perhentian yang diperlukan kendaraan pengiriman lakukan. Misalnya, buat tugas perhentian terjadwal untuk jadwal harian pengumpulan berhenti di lokasi tertentu, terlepas dari pengiriman lainnya atau pengambilan di lokasi yang sama. Anda juga dapat membuat tugas perhentian terjadwal untuk koleksi dari drop box atau untuk model transfer feeder-vehicle atau berhenti di pusat layanan dan titik servis.
Untuk informasi selengkapnya, lihat topik berikut:
Android
iOS
Panduan ID tugas
Saat Anda membuat ID tugas, ikuti panduan konten dan format berikut:
- Membuat ID tugas unik
- Jangan mengungkapkan informasi identitas pribadi (PII) atau menghapus data teks.
- Gunakan string Unicode yang valid.
- Gunakan 64 karakter atau kurang.
- Jangan sertakan salah satu karakter ASCII berikut: "/", ":", "\", "?", atau "#".
- Lakukan normalisasi sesuai dengan Formulir Normalisasi Unicode C.
Berikut adalah beberapa contoh ID Tugas yang baik:
- 566c33d9-2a31-4b6a-9cd4-80ba1a0c643b
- e4708eabcfa39bf2767c9546c9273f747b4626e8cc44e9630d50f6d129013d38
- NTA1YTliYWNkYmViMTI0ZmMzMWFmOWY2NzNkM2Jk
Tabel berikut menunjukkan contoh ID Tugas yang tidak didukung:
ID Tugas Tidak Didukung | Alasan |
---|---|
8/31/2019-20:48-46.70746,-130.10807,-85.17909,61.33680 | Melanggar persyaratan PII dan karakter: koma, titik, titik dua, dan garis miring. |
JohnDoe-577b484da26f-Cupertino-SantaCruz | Melanggar persyaratan PII. |
4R0oXLToF"112 Summer Dr. East Hartford, CT06118"577b484da26f8a | Melanggar persyaratan PII dan karakter: spasi kosong, koma, dan tanda kutip. Lebih dari 64 karakter. |
Referensi lainnya
Untuk melihat kolom tertentu yang terdapat dalam setiap data
lihat dokumentasi Referensi API untuk DeliveryVehicle
(gRPC, REST)
dan Task
(gRPC, REST).
Masa pakai kendaraan
Objek DeliveryVehicle
mewakili kendaraan pengiriman kilometer pertama atau terakhir.
Anda membuat objek DeliveryVehicle
menggunakan:
- Project ID dari project Google Cloud yang berisi akun layanan biasa digunakan untuk memanggil API Fleet Engine.
- ID kendaraan milik pelanggan.
Gunakan ID kendaraan yang unik untuk tiap kendaraan. Jangan gunakan ulang ID kendaraan kecuali jika tidak ada tugas aktif untuk kendaraan asli.
Fleet Engine otomatis menghapus objek DeliveryVehicle
yang belum
diperbarui menggunakan UpdateDeliveryVehicle
setelah tujuh hari. Rekomendasi
pendekatan untuk menjaga agar kendaraan tetap tersedia di Fleet Engine adalah dengan memperbarui lokasinya
dengan interval yang teratur. Pembaruan pada sebagian besar kolom lainnya di DeliveryVehicle
entitas juga akan memperpanjang umurnya, asalkan nilai kolom baru berbeda
dari yang lama.
Untuk melihat apakah kendaraan ada:
- Lakukan panggilan ke
UpdateDeliveryVehicle
. - Jika Anda mendapatkan error NOT_FOUND, panggil
CreateDeliveryVehicle
untuk membuat ulang kendaraan. Jika panggilan menampilkan kendaraan, panggilan masih dapat diperbarui.
Atribut kendaraan
Entity DeliveryVehicle
berisi kolom berulang berupa
DeliveryVehicleAttribute
. ListDeliveryVehicles
API menyertakan filter
yang dapat membatasi entitas DeliveryVehicle
yang ditampilkan ke entitas dengan
atribut yang ditentukan. DeliveryVehicleAttribute
tidak memengaruhi Fleet Engine
perilaku {i>routing<i}.
Jangan menyertakan informasi identitas pribadi (PII) atau informasi sensitif di atribut karena kolom ini mungkin dapat dilihat oleh pengguna.
Umur tugas
Anda dapat membuat, memperbarui, dan menjalankan kueri tugas di Fleet Engine dengan antarmuka gRPC atau REST Deliveries API.
Objek Task
memiliki kolom status untuk melacak progresnya
siklus hidupnya. Nilai dipindahkan dari OPEN ke CLOSED. Tugas baru dibuat
dalam status OPEN, yang menunjukkan bahwa:
- Tugas belum ditugaskan ke kendaraan pengiriman.
- Kendaraan pengiriman belum melewati perhentian kendaraan yang ditetapkan tugas.
Panduan tugas
Anda hanya dapat menetapkan tugas ke kendaraan jika kendaraan dalam status BUKA.
Anda membatalkan tugas dengan menghapusnya dari daftar perhentian kendaraan, yang akan menetapkan status tugas menjadi TUTUP secara otomatis.
Saat kendaraan tugas menyelesaikan penghentian kendaraan tugas:
Perbarui kolom hasil tugas ke SUCCESS atau FAILED.
Tentukan stempel waktu peristiwa.
Pustaka Pelacakan Armada JavaScript kemudian menunjukkan hasil tugas dan status tugas diatur ke {i>CLOSED<i} secara otomatis. Untuk informasi selengkapnya, lihat Lacak Armada Anda dengan library Pelacakan Armada JavaScript.
Seperti kendaraan, Fleet Engine menghapus tugas yang belum diperbarui setelah tujuh hari, dan jika Anda mencoba membuat tugas dengan ID yang sudah ada, maka akan menghasilkan {i>error<i}.
Catatan: Fleet Engine tidak mendukung penghapusan tugas secara eksplisit. Layanan otomatis menghapus tugas setelah tujuh hari tanpa pembaruan. Jika Anda ingin menyimpan data tugas lebih dari tujuh hari, Anda harus mengimplementasikan kemampuan itu sendiri.
Atribut tugas
Entity Task
berisi kolom berulang berupa
TaskAttribute
, yang dapat memiliki nilai dari salah satu dari 3 jenis berikut: string, angka
dan bool. ListTasks
API menyertakan kolom filter
yang dapat membatasi item yang ditampilkan
Task
entitas ke entitas dengan atribut yang ditentukan. Atribut tugas tidak
memengaruhi perilaku perutean Fleet Engine.
Jangan menyertakan informasi identitas pribadi (PII) atau informasi sensitif lainnya tambahan dalam atribut karena atribut ini dapat terlihat oleh pengguna.
Mengelola siklus proses kendaraan dan tugas
Pengingat: Sistem internal Anda bertindak sebagai sumber data tepercaya yang Fleet Engine Deliveries API meningkatkan untuk Anda.
Untuk mengelola siklus proses kendaraan dan tugas di sistem Anda, gunakan Fleet Engine Deliveries API untuk membuat, mengupdate, dan melacak kendaraan Anda beserta tugasnya.
Pada saat yang sama, aplikasi pengemudi berkomunikasi langsung ke Fleet Engine untuk memperbarui informasi rute dan lokasi perangkat. Model ini membuat Fleet Engine mengelola lokasi real-time secara efisien. Ini mengirimkan lokasi langsung ke pustaka pelacakan, yang kemudian dapat Anda gunakan untuk memberitahukan status konsumen pesanan mereka.
Misalnya, Anda memiliki skenario berikut:
- Pengemudi mendekati halte pengiriman. Aplikasi pengemudi mengirimkan lokasinya ke Fleet Engine.
- Fleet Engine mengirimkan lokasi perangkat ke pustaka pelacakan, yang digunakan aplikasi konsumen Anda untuk memberi tahu konsumen dekat dengan paket mereka.
- Setelah pengemudi menyelesaikan pengiriman, mereka akan mengklik "Pengiriman terkirim" pada aplikasi driver.
- "Pengiriman terkirim" tindakan mengirimkan informasi ke sistem backend Anda, yang melakukan langkah-langkah validasi dan verifikasi bisnis yang diperlukan.
- Sistem Anda mengonfirmasi bahwa tugas sebagai SUCCEEDED dan memperbarui Fleet Engine menggunakan Deliveries API.
Diagram berikut mengilustrasikan proses ini pada tingkat umum. Ini juga menunjukkan hubungan standar antara sistem Anda, klien, dan Fleet Engine.
Kelola token klien
Pembaruan lokasi berasal dari aplikasi pengemudi dan dikirim langsung ke Fleet Engine memerlukan token otorisasi. Berikut adalah pendekatan yang direkomendasikan untuk menangani update dari klien ke Fleet Engine:
Membuat token menggunakan Fleet Engine Delivery Untrusted Driver User peran akun layanan.
Berikan token cakupan terbatas ke aplikasi pengemudi. Cakupan ini hanya memungkinkan untuk memperbarui lokasi perangkat di Fleet Engine.
Pendekatan ini memastikan bahwa panggilan yang berasal dari perangkat seluler--dianggap di lingkungan yang kurang tepercaya--taatilah prinsip hak istimewa terendah.
Peran akun layanan lainnya
Jika Anda ingin mengizinkan aplikasi {i>driver<i} untuk melakukan Pembaruan Fleet Engine di luar yang dibatasi pada peran Pengemudi Tidak Tepercaya, seperti untuk pembaruan tugas tertentu, Anda dapat menggunakan peran {i>Trusted Driver<i}. Sebagai informasi tentang model yang menggunakan peran Trusted Driver, lihat Model Driver Tepercaya.
Untuk informasi selengkapnya tentang penggunaan peran driver yang tidak tepercaya dan tepercaya, lihat Penyiapan project cloud.
Membuat model hari kerja
Tabel berikut menjelaskan bagaimana hari kerja untuk pengemudi kilometer pertama atau terakhir mungkin terlihat seperti di perusahaan pengiriman dan logistik. Perusahaan Anda mungkin berbeda dalam detailnya, tetapi Anda dapat melihat bagaimana Anda dapat membuat model hari kerja.
Waktu | Aktivitas | Model |
---|---|---|
Dalam waktu 24 jam sejak awal hari | Petugas operator menugaskan pengiriman ke kendaraan atau rute pengiriman. | Anda dapat membuat tugas untuk pengiriman, pengambilan, istirahat, dan
orang lain di Fleet Engine. Misalnya, Anda dapat membuat
tugas pengambilan pengiriman,
tugas pengiriman,
ketidaktersediaan terjadwal, atau
perhentian terjadwal.
Menetapkan tugas ke kendaraan setelah serangkaian paket pengiriman dan urutan pengirimannya diselesaikan. |
Awal hari | Pengemudi memulai hari di depot dengan login ke aplikasi Driver. | Melakukan inisialisasi Delivery Driver API. Buat kendaraan pengiriman di Fleet Engine sesuai kebutuhan. |
Pengemudi memuat kiriman ke kendaraan pengiriman, memindai kiriman. | Jika tugas pengiriman pengiriman tidak dibuat sebelumnya, membuat tugas pengiriman pada saat pemindaian. | |
Pengemudi mengonfirmasi urutan tugas yang akan dilakukan. | Jika tidak dibuat sebelumnya, buatlah tugas pengambilan pengiriman, ketidaktersediaan terjadwal, dan perhentian terjadwal. | |
Pengemudi meninggalkan depot dan berkomitmen pada jumlah tugas berikutnya yang akan selesai. | Tetapkan semua tugas atau sebagian tugas ke kendaraan dengan melakukan pesanan penyelesaian proyek. | |
Pengemudi mengirim barang. | Setelah tiba di halte pengiriman, lakukan tindakan terkait ke kendaraan yang tiba di perhentian. Setelah mengirimkan kiriman, tutup tugas pengiriman dan, secara opsional, status pengiriman toko dan informasi meta lainnya. Setelah menyelesaikan semua tugas di perhentian dan sebelum mulai berkendara ke perhentian berikutnya, melakukan tindakan terkait kendaraan menyelesaikan perhentian dan kendaraan yang sedang dalam perjalanan ke perhentian berikutnya. | |
Pengemudi bertemu kendaraan pengumpan untuk mentransfer pengiriman tambahan ke kendaraan pengiriman. | Titik pertemuan untuk transfer antara kendaraan pengumpan dan pengiriman
harus dimodelkan sebagai perhentian terjadwal.
Setelah mentransfer dan memindai pengiriman, buat tugas pengiriman jika belum dibuat. Kemudian perbarui penyelesaian tugas pesanan dengan menetapkan tugas ke kendaraan dan memperbarui pengurutan tugas. |
|
Pengemudi menerima notifikasi permintaan pengambilan. | Setelah menerima permintaan pengambilan, membuat tugas pengambilan pengiriman. Kemudian perbarui eksekusi tugas pesanan dengan menetapkan tugas ke kendaraan dan memperbarui pengurutan tugas. | |
Siang | Pengemudi beristirahat makan siang. | Jika lokasi dikaitkan dengan tugas ketidaktersediaan, perlakukan hal tersebut seperti
tugas lain. Melakukan tindakan terkait kendaraan
tiba di perhentian,
kendaraan menyelesaikan perhentian
dan kendaraan yang sedang dalam perjalanan ke perhentian berikutnya.
Jika tidak, tindakan lebih lanjut tidak diperlukan sampai akhir jeda. Hapus tugas dengan mengonfirmasi tugas berikutnya dan tugas yang tersisa, dan memperbarui pengurutan tugas. |
Pengemudi mengambil kiriman. | Ini dimodelkan seperti perhentian pengiriman. Melakukan tindakan terkait ke kendaraan yang tiba di perhentian dan menutup tugas, dan, secara opsional, menyimpan status pengiriman dan informasi meta lainnya. Setelah menyelesaikan semua tugas di perhentian dan sebelum mulai mengemudi ke perhentian berikutnya, melakukan tindakan terkait kendaraan yang menyelesaikan perhentian dan kendaraan yang sedang dalam perjalanan ke perhentian berikutnya. Catatan: Untuk memastikan penagihan yang benar, semua pengambilan harus memiliki pengiriman tugas. Jika pengambilan akan diantar ke lokasi lain pada rute yang sama dengan pengemudi pada hari itu, sebaiknya modelkan tugas pengiriman itu sebagai tugas pengiriman lainnya di rute tersebut. Jika pengemudi membawa penjemputan kembali ke depot, sebaiknya buat tugas pengiriman di depot tujuan. | |
Pengemudi membuat jadwal perhentian untuk mengambil kiriman dari kotak barang. | Di sini dibuat modelnya sama seperti tempat penjemputan lainnya. Melakukan tindakan terkait ke kendaraan yang tiba di perhentian dan menutup tugas. Setelah selesai semua tugas di perhentian dan mulai berkendara ke perhentian berikutnya, melakukan tindakan yang terkait dengan kendaraan yang menyelesaikan perhentian dan kendaraan yang sedang dalam perjalanan ke perhentian berikutnya. | |
Pengemudi menerima notifikasi tentang pengiriman yang dialihkan ke lokasi alternatif. | Tetapkan status tugas pengiriman asli ke SELESAI dan buat yang baru pengiriman untuk lokasi pengiriman baru. Untuk informasi selengkapnya, lihat Mengubah rute pengiriman. | |
Pengemudi mencoba mengirimkan paket tetapi tidak dapat melakukannya. | Hal ini dimodelkan mirip dengan perhentian pengiriman yang berhasil, yang menandai tugas pengiriman telah selesai. Melakukan tindakan yang terkait dengan kendaraan yang tiba di perhentian. Sesudah pengiriman yang gagal, menutup tugas dan, jika perlu, status pengiriman toko dan informasi meta lainnya. Setelah menyelesaikan semua tugas di perhentian dan sebelum mulai mengemudi ke perhentian berikutnya, melakukan tindakan terkait kendaraan yang menyelesaikan perhentian dan kendaraan yang sedang dalam perjalanan ke perhentian berikutnya. | |
Pengemudi diberi tahu untuk menahan (tidak mengirimkan) kiriman. | Setelah notifikasi diterima dan dikonfirmasi, tetapkan status tugas ke COMPLETED. | |
Pengemudi diberi tahu untuk mengirimkan kiriman tertentu berikutnya, sehingga mengubah komitmen pesanan pengiriman. | Memperbarui urutan tugas. | |
Pengemudi memilih untuk mengantarkan pesanan secara tidak berurutan. | Memperbarui urutan tugas, lalu lanjutkan seperti biasa. | |
Pengemudi mengirimkan beberapa kiriman ke satu lokasi. | Model ini dibuat mirip dengan satu perhentian pengiriman. Setelah tiba di perhentian, lakukan tindakan yang terkait dengan kendaraan yang tiba di perhentian. Setelah mengirimkan setiap pengiriman, tutup setiap tugas dan, jika perlu, status pengiriman toko dan informasi meta lainnya. Setelah menyelesaikan semua tugas di perhentian dan sebelum mulai mengemudi ke perhentian berikutnya, melakukan tindakan terkait kendaraan yang menyelesaikan perhentian dan kendaraan yang sedang dalam perjalanan ke perhentian berikutnya. | |
Akhir hari | Pengemudi kembali ke depot. | Jika pengemudi kembali ke depot dengan mengangkut barang yang telah diambil Anda juga harus membuat dan menutup setiap paket sebagai tugas pengiriman untuk memastikan penagihan yang benar. Anda dapat melakukannya dengan membuat model depot seperti pengiriman lainnya. Jika depot tidak digunakan sebagai perhentian pengiriman, Anda masih dapat memilih memodelkan depot sebagai perhentian terjadwal. Pemodelan perhentian memungkinkan pengemudi Anda untuk melihat rute kembali ke depot dan memberikan visibilitas tentang perkiraan waktu mereka dari kedatangan. |
Cara kerja pembaruan lokasi
Untuk performa terbaik dengan Fleet Engine, sediakan aliran data kendaraan pembaruan lokasi. Gunakan salah satu cara berikut untuk memberikan update ini:
- Gunakan Driver SDK - Android, iOS -- opsi paling sederhana.
- Gunakan kode khusus -- berguna jika lokasi yang direlai melalui backend, atau jika Anda menggunakan perangkat selain Android atau iOS.
Terlepas dari cara Anda memberikan pembaruan lokasi kendaraan, backend Anda bertanggung jawab untuk memperbarui Fleet Engine saat ada kendaraan pengiriman untuk rute ke perhentian (termasuk depot) dan kapan tiba di perhentian. Fleet Engine tidak mendeteksi peristiwa ini secara otomatis.
Perhentian kendaraan dan lokasi pengiriman
Pemberhentian kendaraan adalah tempat kendaraan pengiriman menyelesaikan tugas pengiriman atau tugas lain. Ini bisa berupa titik akses seperti dok pemuatan atau lokasi yang diambil oleh jalan.
Lokasi pengiriman adalah lokasi pengantaran atau diangkat. Pergi ke dan dari lokasi pengiriman mungkin perlu berjalan beberapa saat dari halte kendaraan.
Misalnya, saat pengemudi mengantarkan pengiriman ke toko di sebuah mal, kendaraan pengiriman berhenti di tempat parkir mal dekat pintu masuk terdekat ke toko. Ini adalah perhentian kendaraan. Pengemudi kemudian berjalan dari halte kendaraan ke lokasi dalam mal di mana lokasi toko. Ini adalah lokasi pengiriman.
Untuk pengalaman pelacakan pengiriman terbaik bagi pengguna Anda, pertimbangkan cara pengiriman ditetapkan ke perhentian kendaraan dan perlu diingat bahwa jumlah perhentian kendaraan yang tersisa untuk tugas pengiriman dilaporkan kepada pengguna untuk membantu mereka melihat kemajuan pengiriman mereka.
Misalnya, jika seorang pengemudi melakukan banyak pengiriman ke satu gedung kantor, pertimbangkan untuk menetapkan semua tugas pengiriman ke satu perhentian kendaraan. Jika setiap tugas pengiriman ditugaskan ke pemberhentian kendaraannya sendiri, pengiriman pesanan pengalaman pelacakan akan kurang membantu pengguna Anda karena pelacakan hanya setelah kendaraan berada dalam sejumlah perhentian kendaraan yang terbatas sebelum tujuannya. Banyaknya penghentian kendaraan dalam waktu singkat tidak memberikan banyak waktu bagi pengguna untuk melacak kemajuan pengiriman mereka.
Menggunakan SDK seluler
Sebelum melakukan panggilan ke Driver SDK, pastikan untuk melakukan inisialisasi.
Melakukan inisialisasi Delivery Driver API
Sebelum menginisialisasi Delivery Driver API di Driver SDK, pastikan untuk melakukan inisialisasi Navigation SDK. Kemudian inisialisasi Delivery Driver API seperti ditunjukkan pada contoh berikut:
static final String PROVIDER_ID = "provider-1234";
static final String VEHICLE_ID = "vehicle-8241890";
NavigationApi.getNavigator(
this, // Activity.
new NavigatorListener() {
@Override
public void onNavigatorReady(Navigator navigator) {
DeliveryDriverApi.createInstance(DriverContext.builder(getApplication())
.setNavigator(navigator)
.setProviderId(PROVIDER_ID)
.setVehicleId(VEHICLE_ID)
.setAuthTokenFactory((context) -> "JWT") // AuthTokenFactory returns JWT for call context.
.setRoadSnappedLocationProvider(NavigationApi.getRoadSnappedLocationProvider(getApplication()))
.setNavigationTransactionRecorder(NavigationApi.getNavigationTransactionRecorder(getApplication()))
.setStatusListener((statusLevel,statusCode,statusMsg) -> // Optional, surfaces polling errors.
Log.d("TAG", String.format("New status update. %s, %s, %s", statusLevel, statusCode, statusMsg)))
.build));
}
@Override
public void onError(int errorCode) {
Log.e("TAG", String.format("Error loading Navigator instance: %s", errorCode));
}
});
Kasus penggunaan
Bagian ini menjelaskan cara menggunakan Deliveries API untuk membuat model kasus penggunaan umum.
ID entitas unik
Format dan nilai ID entity unik yang digunakan dalam panggilan REST adalah buram ke Fleet Engine. Hindari penggunaan ID yang bertambah otomatis, dan pastikan bahwa ID tidak berisi informasi identitas pribadi (PII), seperti nomor telepon pengemudi.
Buat kendaraan
Anda dapat membuat kendaraan dari Driver SDK atau dari lingkungan server menggunakan gRPC atau REST.
gRPC
Untuk membuat kendaraan baru, lakukan panggilan CreateDeliveryVehicle
ke Fleet Engine.
Gunakan objek CreateDeliveryVehicleRequest
untuk menentukan atribut
kendaraan pengiriman yang baru. Perhatikan bahwa nilai apa pun yang ditentukan untuk kolom Name
diabaikan per panduan API untuk ID yang ditentukan pengguna.
Anda harus menggunakan kolom DeliveryVehicleId
untuk menetapkan ID kendaraan.
Saat membuat DeliveryVehicle
, Anda dapat menentukan kolom ini secara opsional:
- Atribut
- LastLocation
- Jenis
Jangan tetapkan kolom lain. Jika Anda melakukannya, Fleet Engine akan menampilkan error
karena isian itu bersifat {i>read-only<i}
atau hanya dapat diperbarui dengan panggilan ke
UpdateDeliveryVehicle
.
Untuk membuat kendaraan tanpa menyetel kolom opsional, Anda dapat keluar dari halaman
Kolom DeliveryVehicle
tidak disetel di CreateDeliveryVehicleRequest
.
Contoh berikut menunjukkan cara menggunakan Library gRPC Java untuk membuat kendaraan:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890"; // Avoid auto-incrementing IDs.
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String parent = "providers/" + PROJECT_ID;
DeliveryVehicle vehicle = DeliveryVehicle.newBuilder()
.addAttributes(DeliveryVehicleAttribute.newBuilder()
.setKey("route_number").setValue("1")) // Opaque to the Fleet Engine
.build();
// Vehicle request
CreateDeliveryVehicleRequest createVehicleRequest =
CreateDeliveryVehicleRequest.newBuilder() // No need for the header
.setParent(parent)
.setDeliveryVehicleId(VEHICLE_ID) // Vehicle ID assigned by the Provider
.setDeliveryVehicle(vehicle)
.build();
// Error handling
// If Fleet Engine does not have vehicle with that ID and the credentials of the
// requestor pass, the service creates the vehicle successfully.
try {
DeliveryVehicle createdVehicle =
deliveryService.createDeliveryVehicle(createVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Untuk membuat kendaraan dari lingkungan server, lakukan panggilan REST HTTP
ke CreateDeliveryVehicle
:
POST https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles?deliveryVehicleId=<id>
<id> adalah ID unik untuk kendaraan pengiriman di armada Anda.
Header permintaan harus berisi kolom Authorization dengan nilai Bearer <token>, dengan <token> adalah token yang dikeluarkan oleh factory token Fleet Engine.
Isi POST mewakili entity DeliveryVehicle
yang akan dibuat. Anda dapat menentukan
kolom opsional berikut:
- attribut
- lastLocation
- jenis
Contoh perintah curl
:
# Set $JWT, $PROJECT_ID, and $VEHICLE_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?deliveryVehicleId=${VEHICLE_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"attributes": [{"key": "model", "value": "sedan"}],
"lastLocation": {"location": {"latitude": 12.1, "longitude": 14.5}}
}
EOM
Fleet Engine mengabaikan kolom name
dari entity DeliveryVehicle
sesuai panduan API untuk ID yang ditentukan pengguna.
Jangan tetapkan kolom lain. Jika Anda melakukannya, Fleet Engine akan menampilkan error
karena isian itu bersifat {i>read-only<i} atau
hanya dapat diperbarui menggunakan panggilan untuk
UpdateDeliveryVehicle
.
Untuk membuat kendaraan tanpa menyetel kolom apa pun, tinggalkan isi POST
kosong. Kendaraan yang baru dibuat kemudian
mengekstrak ID kendaraan dari
Parameter deliveryVehicleId
di URL POST.
Contoh perintah curl
:
# Set $JWT, $PROJECT_ID, and $VEHICLE_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?deliveryVehicleId=${VEHICLE_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}"
Membuat tugas pengambilan pengiriman
Anda dapat membuat tugas pengambilan pengiriman dari SDK Driver atau dari lingkungan server menggunakan gRPC atau REST.
gRPC
Contoh berikut menunjukkan cara menggunakan Library gRPC Java untuk membuat tugas pengambilan pengiriman:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
.setType(Task.Type.PICKUP)
.setState(Task.State.OPEN)
.setTrackingId("my-tracking-id")
.setPlannedLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setTaskDuration(
Duration.newBuilder().setSeconds(2 * 60))
.setTargetTimeWindow(
TimeWindow.newBuilder()
.setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
.setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
.addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
.addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
.addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
.build();
// Task request
CreateTaskRequest createTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header
.setParent(parent) // Avoid using auto-incrementing IDs for the taskId
.setTaskId("task-8241890") // Task ID assigned by the Provider
.setTask(task) // Initial state
.build();
// Error handling
// If Fleet Engine does not have a task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.
try {
Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Untuk membuat tugas pengambilan pengiriman dari lingkungan server, buat panggilan REST HTTP
ke CreateTask
:
`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`
<id> adalah ID unik untuk tugas. Tidak boleh berupa nomor pelacakan untuk pengiriman. Jika tidak memiliki ID tugas di sistem, Anda dapat membuat pengenal unik universal (UUID).
Header permintaan harus berisi kolom Authorization dengan nilai Bearer <token>, dengan <token> adalah token yang dikeluarkan oleh factory token Fleet Engine.
Isi permintaan harus berisi entity Task
:
Kolom wajib diisi:
Kolom Nilai jenis Type.PICKUP dengan status tersembunyi akhir State.OPEN trackingId Nomor atau ID yang Anda gunakan untuk melacak pengiriman. plannedLocation Lokasi tempat tugas akan diselesaikan, dalam hal ini lokasi pengambilan pengiriman. taskDuration Waktu yang diharapkan, dalam detik, yang diperlukan untuk mengambil kiriman di lokasi penjemputan. Kolom opsional:
Kolom Nilai targetTimeWindow Periode waktu saat tugas harus diselesaikan. Hal ini tidak mempengaruhi perilaku {i>routing<i}. attribut Daftar atribut Tugas kustom. Setiap atribut harus memiliki kunci unik.
Semua kolom lain dalam entity diabaikan untuk pembuatan. Lemparan Fleet Engine
pengecualian jika permintaan menyertakan deliveryVehicleId
yang ditetapkan. Anda menetapkan
tugas menggunakan UpdateDeliveryVehicleRequest
. Untuk informasi selengkapnya, lihat
Menetapkan tugas ke kendaraan dan UpdateDeliveryVehicleRequest.
Contoh perintah curl
:
# Set $JWT, $PROJECT_ID, $TRACKING_ID, and $TASK_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"type": "PICKUP",
"state": "OPEN",
"trackingId": "${TRACKING_ID}",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "90s",
"targetTimeWindow": {
"startTime": "2023-03-29T21:00:00Z",
"endTime": "2023-03-29T23:00:00Z"
}
}
EOM
Membuat tugas pengiriman pengiriman
Buat tugas pengiriman, baik dari SDK Driver atau dari lingkungan server menggunakan gRPC atau REST.
gRPC
Contoh berikut menunjukkan cara menggunakan Library gRPC Java untuk membuat tugas pengiriman:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
.setType(Task.Type.DELIVERY)
.setState(Task.State.OPEN)
.setTrackingId("my-tracking-id")
.setPlannedLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setTaskDuration(
Duration.newBuilder().setSeconds(2 * 60))
.setTargetTimeWindow(
TimeWindow.newBuilder()
.setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
.setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
.addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
.addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
.addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
.build();
// Task request
CreateTaskRequest createTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header
.setParent(parent) // Avoid using auto-incrementing IDs for the taskId
.setTaskId("task-8241890") // Task ID assigned by the Provider
.setTask(task) // Initial state
.build();
// Error handling
// If Fleet Engine does not have task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.
try {
Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Untuk membuat tugas pengiriman pengiriman dari lingkungan server menggunakan gRPC atau REST, buat panggilan REST HTTP
ke CreateTask
:
`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`
<id> adalah ID unik untuk tugas. Tidak boleh berupa nomor pelacakan untuk pengiriman. Jika tidak memiliki ID tugas di sistem, Anda dapat membuat pengenal unik universal (UUID).
Header permintaan harus berisi kolom Authorization dengan nilai Bearer <token>, dengan <token> adalah token yang dikeluarkan oleh factory token Fleet Engine.
Isi permintaan harus berisi entity Task
:
Kolom wajib diisi:
Kolom Nilai jenis Type.DELIVERY dengan status tersembunyi akhir State.OPEN trackingId Nomor atau ID yang Anda gunakan untuk melacak pengiriman. plannedLocation Lokasi tempat tugas akan diselesaikan, dalam hal ini lokasi pengiriman untuk pengiriman ini. taskDuration Waktu yang diharapkan, dalam detik, yang diperlukan untuk menurunkan kiriman di lokasi pengiriman. Kolom opsional:
Kolom Nilai targetTimeWindow Periode waktu saat tugas harus diselesaikan. Hal ini tidak mempengaruhi perilaku {i>routing<i}. attribut Daftar atribut Tugas kustom. Setiap atribut harus memiliki kunci unik.
Semua kolom lain dalam entity diabaikan untuk pembuatan. Lemparan Fleet Engine
pengecualian jika permintaan menyertakan deliveryKendaraanId yang ditetapkan. Anda menetapkan
tugas menggunakan UpdateDeliveryVehicleRequest
. Untuk informasi selengkapnya, lihat
Menetapkan tugas ke kendaraan dan UpdateDeliveryVehicleRequest.
Contoh perintah curl
:
# Set $JWT, $PROJECT_ID, $TRACKING_ID, and $TASK_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"type": "DELIVERY",
"state": "OPEN",
"trackingId": "${TRACKING_ID}",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "90s",
"targetTimeWindow": {
"startTime": "2023-03-29T21:00:00Z",
"endTime": "2023-03-29T23:00:00Z"
}
}
EOM
Buat Tugas Secara Kelompok
Anda dapat membuat batch tugas dari lingkungan server menggunakan gRPC atau REST.
gRPC
Contoh berikut menunjukkan cara menggunakan Library gRPC Java untuk membuat dua tugas, satu untuk pengantaran dan satu untuk pengambilan pada saat yang sama lokasi:
static final String PROJECT_ID = "my-delivery-co-gcp-project"; DeliveryServiceBlockingStub deliveryService = DeliveryServiceGrpc.newBlockingStub(channel); // Delivery Task settings Task deliveryTask = Task.newBuilder() .setType(Task.Type.DELIVERY) .setState(Task.State.OPEN) .setTrackingId("delivery-tracking-id") .setPlannedLocation( // Grand Indonesia East Mall LocationInfo.newBuilder().setPoint( LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826))) .setTaskDuration( Duration.newBuilder().setSeconds(2 * 60)) .build(); // Delivery Task request CreateTaskRequest createDeliveryTaskRequest = CreateTaskRequest.newBuilder() // No need for the header or parent fields .setTaskId("task-8312508") // Task ID assigned by the Provider .setTask(deliveryTask) // Initial state .build(); // Pickup Task settings Task pickupTask = Task.newBuilder() .setType(Task.Type.PICKUP) .setState(Task.State.OPEN) .setTrackingId("pickup-tracking-id") .setPlannedLocation( // Grand Indonesia East Mall LocationInfo.newBuilder().setPoint( LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826))) .setTaskDuration( Duration.newBuilder().setSeconds(2 * 60)) .build(); // Pickup Task request CreateTaskRequest createPickupTaskRequest = CreateTaskRequest.newBuilder() // No need for the header or parent fields .setTaskId("task-8241890") // Task ID assigned by the Provider .setTask(pickupTask) // Initial state .build(); // Batch Create Tasks settings String parent = "providers/" + PROJECT_ID; // Batch Create Tasks request BatchCreateTasksRequest batchCreateTasksRequest = BatchCreateTasksRequest.newBuilder() .setParent(parent) .addRequests(createDeliveryTaskRequest) .addRequests(createPickupTaskRequest) .build(); // Error handling // If Fleet Engine does not have any task(s) with these task ID(s) and the // credentials of the requestor pass, the service creates the task(s) // successfully. try { BatchCreateTasksResponse createdTasks = deliveryService.batchCreateTasks( batchCreateTasksRequest); } catch (StatusRuntimeException e) { Status s = e.getStatus(); switch (s.getCode()) { case ALREADY_EXISTS: break; case PERMISSION_DENIED: break; } return; }
REST
Untuk membuat tugas pengiriman dan pengambilan dari lingkungan server, buat
Panggilan REST HTTP ke BatchCreateTasks
:
POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks:batchCreate
Header permintaan harus berisi kolom Authorization dengan nilai Bearer <token>, dengan <token> adalah token yang dikeluarkan oleh factory token Fleet Engine.
Isi permintaan harus berisi entity BatchCreateTasksRequest
:
Kolom wajib diisi:
Kolom Nilai permintaan Array< CreateTasksRequest
>Kolom opsional:
Kolom Nilai header `DeliveryRequestHeader`
Setiap elemen CreateTasksRequest
di requests
harus lulus validasi yang sama
sebagai permintaan CreateTask
, dengan pengecualian bahwa parent
dan kolom header
bersifat opsional. Jika ditetapkan, penentu tersebut harus sama dengan
{i>field<i} masing-masing
di tingkat teratas BatchCreateTasksRequest
. Lihat
membuat tugas pengambilan pengiriman dan
membuat tugas pengiriman
untuk setiap aturan validasinya.
Untuk informasi selengkapnya, lihat dokumentasi Referensi API untuk BatchCreateTasks
(gRPC, REST).
Contoh perintah curl
:
# Set $JWT, $PROJECT_ID, $DELIVERY_TRACKING_ID, $DELIVERY_TASK_ID,
# $PICKUP_TRACKING_ID, and $PICKUP_TASK_ID in the local environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks:batchCreate" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"requests" : [
{
"taskId": "${DELIVERY_TASK_ID}",
"task" : {
"type": "DELIVERY",
"state": "OPEN",
"trackingId": "${DELIVERY_TRACKING_ID}",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "90s"
}
},
{
"taskId": "${PICKUP_TASK_ID}",
"task" : {
"type": "PICKUP",
"state": "OPEN",
"trackingId": "${PICKUP_TRACKING_ID}",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "90s"
}
}
]
}
EOM
Ketidaktersediaan terjadwal
Anda dapat membuat tugas yang menunjukkan ketidaktersediaan (misalnya, untuk pengemudi atau mengisi bahan bakar kendaraan) baik dari SDK Driver, atau dari lingkungan server menggunakan gRPC atau REST. Tugas ketidaktersediaan terjadwal tidak boleh disertakan ID pelacakan. Anda dapat memberikan lokasi secara opsional.
gRPC
Contoh berikut menunjukkan cara menggunakan Library gRPC Java untuk membuat tugas ketidaktersediaan:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
.setType(Task.Type.UNAVAILABLE)
.setState(Task.State.OPEN)
.setTaskDuration(
Duration.newBuilder().setSeconds(60 * 60)) // 1hr break
.build();
// Task request
CreateTaskRequest createTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header
.setParent(parent) // Avoid using auto-incrementing IDs for the taskId
.setTaskId("task-8241890") // Task ID assigned by the Provider
.setTask(task) // Initial state
.build();
// Error handling
// If Fleet Engine does not have task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.
try {
Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Untuk membuat tugas ketidaktersediaan dari lingkungan server, buat panggilan REST HTTP
ke CreateTask
:
`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`
<id> adalah ID unik untuk tugas. Jika Anda tidak memiliki ID tugas di sistem Anda, Anda dapat membuat pengenal tertentu (UUID).
Header permintaan harus berisi kolom Authorization dengan nilai Bearer <token>, dengan <token> adalah token yang dikeluarkan oleh factory token Fleet Engine.
Isi permintaan harus berisi entity Task
:
Kolom wajib diisi:
Kolom Nilai jenis Type.UNAVAILABLE dengan status tersembunyi akhir State.OPEN taskDuration Durasi jeda dalam detik. Kolom opsional:
Kolom Nilai plannedLocation Lokasi istirahat jika harus diambil di lokasi tertentu.
Semua kolom lain dalam entity diabaikan untuk pembuatan. Lemparan Fleet Engine
pengecualian jika permintaan menyertakan deliveryKendaraanId yang ditetapkan. Anda menetapkan
tugas menggunakan UpdateDeliveryVehicleRequest
. Untuk informasi selengkapnya, lihat
Menetapkan tugas ke kendaraan dan UpdateDeliveryVehicleRequest.
Contoh perintah curl
:
# Set $JWT, $PROJECT_ID, and $TASK_ID in the local environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"type": "UNAVAILABLE",
"state": "OPEN",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "300s"
}
EOM
Perhentian terjadwal
Anda dapat membuat tugas perhentian terjadwal baik dari SDK Driver, atau dari lingkungan server menggunakan gRPC atau REST. Tugas perhentian terjadwal mungkin tidak menyertakan pelacakan ke ID.
gRPC
Contoh berikut menunjukkan cara menggunakan Library gRPC Java untuk membuat tugas perhentian terjadwal:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
.setType(Task.Type.SCHEDULED_STOP)
.setState(Task.State.OPEN)
.setPlannedLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setTaskDuration(
Duration.newBuilder().setSeconds(2 * 60))
.build();
// Task request
CreateTaskRequest createTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header
.setParent(parent)
.setTaskId("task-8241890") // Task ID assigned by the Provider
.setTrip(task) // Initial state
.build();
// Error handling
// If Fleet Engine does not have task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.
try {
Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Untuk membuat tugas penghentian terjadwal dari lingkungan server, buat panggilan REST HTTP
ke CreateTask
:
`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`
<id> adalah ID unik untuk tugas. Jika Anda tidak memiliki ID tugas di sistem Anda, Anda dapat membuat pengenal unik universal (UUID).
Header permintaan harus berisi kolom Authorization dengan nilai Bearer <token>, dengan <token> adalah token yang dikeluarkan oleh factory token Fleet Engine.
Isi permintaan harus berisi entity Task
:
Kolom wajib diisi:
Kolom Nilai jenis Type.SCHEDULED_STOP dengan status tersembunyi akhir State.OPEN plannedLocation Lokasi perhentian. taskDuration Perkiraan panjang perhentian dalam hitungan detik. Kolom opsional:
- Tidak ada
Semua kolom lain dalam entity diabaikan untuk pembuatan. Lemparan Fleet Engine
pengecualian jika permintaan menyertakan deliveryKendaraanId yang ditetapkan. Anda menetapkan
tugas menggunakan UpdateDeliveryVehicleRequest
. Untuk informasi selengkapnya, lihat
Menetapkan tugas ke kendaraan dan UpdateDeliveryVehicleRequest.
Contoh perintah curl
:
# Set $JWT, $PROJECT_ID, and $TASK_ID in the local environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"type": "SCHEDULED_STOP",
"state": "OPEN",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "600s"
}
EOM
Setel periode waktu target
Periode waktu target adalah periode TimeWindow di mana tugas harus diselesaikan. Misalnya, jika Anda mengomunikasikan jangka waktu pengiriman ke penerima pengiriman, Anda dapat menggunakan target waktu tugas untuk mencatat periode waktu ini dan menghasilkan pemberitahuan atau menganalisis pasca-perjalanan performa terbaik menggunakan kolom ini.
Periode waktu target terdiri dari waktu mulai dan waktu berakhir serta dapat ditetapkan sesuai jenis tugas apa pun. Periode waktu target tidak memengaruhi pemilihan rute perilaku model.
gRPC
Contoh berikut menunjukkan cara menggunakan Library gRPC Java untuk menyetel periode waktu tugas:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
.setName(taskName)
.setTargetTimeWindow(
TimeWindow.newBuilder()
.setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
.setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
.build();
// Task request
UpdateTaskRequest updateTaskRequest =
UpdateTaskRequest.newBuilder() // No need for the header
.setTask(task)
.setUpdateMask(FieldMask.newBuilder().addPaths("targetTimeWindow"))
.build();
try {
Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Untuk menyetel jangka waktu tugas menggunakan HTTP, panggil UpdateTask
:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=targetTimeWindow`
<id> adalah ID unik untuk tugas.
Header permintaan harus berisi kolom Authorization dengan nilai Bearer <token>, dengan <token> adalah token yang dikeluarkan oleh factory token Fleet Engine.
Isi permintaan harus berisi entity Task
:
Kolom wajib diisi:
Kolom Nilai targetTimeWindow Periode waktu saat tugas harus diselesaikan. Setelan ini tidak memengaruhi perilaku perutean Kolom opsional:
- Tidak ada
Semua kolom lain dalam entity akan diabaikan untuk update.
Contoh perintah curl
:
# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=targetTimeWindow" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"targetTimeWindow": {
"startTime": "2023-03-29T21:00:00Z",
"endTime": "2023-03-29T23:00:00Z"
}
}
EOM
Setel konfigurasi visibilitas pelacakan tugas
Visibilitas data di library Shipment Tracking serta data tersebut
yang ditampilkan dari panggilan ke GetTaskTrackingInfo
dapat dikontrol di per tugas
dengan menetapkan
TaskTrackingViewConfig
pada tugas tersebut. Lihat
Tugas kendaraan aktif
untuk informasi selengkapnya. Hal ini dapat dilakukan saat membuat atau memperbarui
tugas Anda. Berikut adalah contoh pembaruan tugas dengan konfigurasi ini:
gRPC
Contoh berikut menunjukkan cara menggunakan Library gRPC Java untuk mengatur konfigurasi tampilan pelacakan tugas:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
.setName(taskName)
.setTaskTrackingViewConfig(
TaskTrackingViewConfig.newBuilder()
.setRoutePolylinePointsVisibility(
VisibilityOption.newBuilder().setRemainingStopCountThreshold(3))
.setEstimatedArrivalTimeVisibility(
VisibilityOption.newBuilder().remainingDrivingDistanceMetersThreshold(5000))
.setRemainingStopCountVisibility(
VisibilityOption.newBuilder().setNever(true)))
.build();
// Task request
UpdateTaskRequest updateTaskRequest =
UpdateTaskRequest.newBuilder() // No need for the header
.setTask(task)
.setUpdateMask(FieldMask.newBuilder().addPaths("taskTrackingViewConfig"))
.build();
try {
Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Untuk menetapkan jendela konfigurasi tampilan pelacakan tugas menggunakan HTTP, panggil UpdateTask
:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=taskTrackingViewConfig`
<id> adalah ID unik untuk tugas.
Header permintaan harus berisi kolom Authorization dengan nilai Bearer <token>, dengan <token> adalah token yang dikeluarkan oleh factory token Fleet Engine.
Isi permintaan harus berisi entity Task
:
Kolom wajib diisi:
Kolom Nilai taskTrackingViewConfig Konfigurasi untuk pelacakan tugas yang menentukan elemen data mana dapat dilihat oleh pengguna akhir dalam situasi apa. Kolom opsional:
- Tidak ada
Semua kolom lain dalam entity akan diabaikan untuk update.
Contoh perintah curl
:
# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=taskTrackingViewConfig" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"taskTrackingViewConfig": {
"routePolylinePointsVisibility": {
"remainingStopCountThreshold": 3
},
"estimatedArrivalTimeVisibility": {
"remainingDrivingDistanceMetersThreshold": 5000
},
"remainingStopCountVisibility": {
"never": true
}
}
}
EOM
Menetapkan tugas ke kendaraan
Anda menetapkan tugas ke kendaraan pengiriman dengan memperbarui pengurutan tugas untuk kendaraan. Pemesanan tugas untuk kendaraan ditentukan oleh daftar perhentian kendaraan untuk kendaraan pengiriman, dan Anda dapat menetapkan satu atau beberapa tugas ke setiap perhentian kendaraan. Untuk mengetahui detailnya, lihat Memperbarui urutan tugas.
Untuk mengubah pengiriman dari satu kendaraan ke kendaraan lainnya, tutup tugas asli lalu membuatnya kembali sebelum menetapkannya menjadi kendaraan baru. Jika Anda memperbarui tugas memesan untuk tugas yang sudah diberikan ke kendaraan lain, Anda akan mendapatkan pesan {i>error.<i}
Perbarui pengurutan tugas
Anda dapat memperbarui tugas pesanan yang ditetapkan ke kendaraan yang dilakukan dari tindakan SDK Driver, atau lingkungan server. Jangan gunakan kedua metode untuk menghindari merasingi kondisi dan mempertahankan satu sumber terpercaya.
Saat Anda memperbarui pengurutan tugas untuk kendaraan, update tersebut juga melakukan hal berikut:
- Menetapkan tugas yang baru untuk kendaraan.
- Menutup tugas apa pun yang sebelumnya ditetapkan ke kendaraan, tetapi tidak dilakukan dalam urutan yang telah diperbarui.
Untuk mengubah pengiriman dari satu kendaraan ke kendaraan lainnya, menutup tugas asli lalu membuatnya kembali sebelum menetapkannya menjadi kendaraan baru. Jika Anda memperbarui tugas memesan untuk tugas yang sudah diberikan ke kendaraan lain, Anda akan mendapatkan pesan {i>error.<i}
Anda dapat memperbarui pengurutan tugas kapan saja.
gRPC
Contoh berikut menunjukkan cara menggunakan Library gRPC Java untuk memperbarui pengurutan tugas untuk kendaraan tersebut:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
static final String TASK1_ID = "task-756390";
static final String TASK2_ID = "task-849263";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 1st stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.7749)
.setLongitude(122.4194)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
.setState(VehicleStop.State.NEW)))
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 2nd stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
.setState(VehicleStop.State.NEW)))
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryRequest =
UpdateDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(vehicleName)
.setDeliveryVehicle(deliveryVehicle)
.setUpdateMask(FieldMask.newBuilder().addPaths("remaining_vehicle_journey_segments"))
.build();
try {
DeliveryVehicle updatedDeliveryVehicle =
deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Guna memperbarui pengurutan tugas untuk kendaraan dari lingkungan server, lakukan panggilan REST HTTP
ke UpdateDeliveryVehicle
:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`
<id> adalah ID unik untuk kendaraan pengiriman di armada Anda yang urutan tugasnya ingin Anda perbarui. Ini adalah pengenal yang yang Anda tentukan saat membuat kendaraan.
Header permintaan harus berisi kolom Authorization dengan nilai Bearer <token>, dengan <token> adalah token yang dikeluarkan oleh factory token Fleet Engine.
Isi permintaan harus berisi entity DeliveryVehicle
:
Kolom wajib diisi:
Kolom Nilai remainingVehicleJourneySegments Daftar segmen perjalanan untuk tugas sesuai urutan pelaksanaannya. Tugas pertama dalam daftar akan dieksekusi terlebih dahulu. remainingVehicleJourneySegments[i].stop Perhentian untuk tugas i dalam daftar. remainingVehicleJourneySegments[i].stop.plannedLocation Lokasi yang direncanakan untuk perhentian. remainingVehicleJourneySegments[i].stop.tasks Daftar tugas yang akan dilakukan di perhentian kendaraan ini. remainingVehicleJourneySegments[i].stop.state State.NEW Kolom opsional:
- Tidak ada
Semua kolom lain dalam entity akan diabaikan untuk update.
Contoh perintah curl
:
# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"remainingVehicleJourneySegments": [
{
"stop": {
"state": "NEW",
"plannedLocation": {
"point": {
"latitude": 37.7749,
"longitude": -122.084061
}
},
"tasks": [
{
"taskId": "${TASK1_ID}"
}
]
}
},
{
"stop": {
"state": "NEW",
"plannedLocation": {
"point": {
"latitude": 37.3382,
"longitude": 121.8863
}
},
"tasks": [
{
"taskId": "${TASK2_ID}"
}
]
}
}
]
}
EOM
Kendaraan sedang dalam perjalanan ke perhentian berikutnya
Fleet Engine harus diberi tahu saat kendaraan berangkat dari perhentian atau mulai navigasi. Anda dapat memberi tahu Fleet Engine dari SDK Driver, atau dari lingkungan server menggunakan gRPC atau REST. Jangan gunakan kedua metode tersebut untuk menghindari race kondisi dan untuk mempertahankan satu sumber yang terpercaya.
gRPC
Contoh berikut menunjukkan cara menggunakan Library gRPC Java untuk memberi tahu Fleet Engine bahwa kendaraan sedang menuju ke perhentian berikutnya.
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
// Next stop marked as ENROUTE
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 1st stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.7749)
.setLongitude(122.4194)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
.setState(VehicleStop.State.ENROUTE)))
// All other stops marked as NEW
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 2nd stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
.setState(VehicleStop.State.NEW)))
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
UpdateDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(vehicleName)
.setDeliveryVehicle(deliveryVehicle)
.setUpdateMask(FieldMask.newBuilder().addPaths("remaining_vehicle_journey_segments"))
.build();
try {
DeliveryVehicle updatedDeliveryVehicle =
deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Untuk memberi tahu Fleet Engine bahwa kendaraan sedang menuju ke perhentian berikutnya dari
lingkungan server, lakukan panggilan REST HTTP ke UpdateDeliveryVehicle
:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`
<id> adalah ID unik untuk kendaraan pengiriman di armada Anda yang urutan tugasnya ingin Anda perbarui. Ini adalah pengenal yang yang Anda tentukan saat membuat kendaraan.
Header permintaan harus berisi kolom Authorization dengan nilai Bearer <token>, dengan <token> adalah token yang dikeluarkan oleh factory token Fleet Engine.
Isi permintaan harus berisi entity DeliveryVehicle
:
Kolom wajib diisi:
Kolom Nilai remainingVehicleJourneySegments Daftar perhentian kendaraan yang tersisa dengan negara bagiannya ditandai sebagai State.NEW. Perhentian pertama dalam daftar harus memiliki status yang ditandai sebagai State.ENROUTE. Kolom opsional:
- Tidak ada
Semua kolom lain dalam entity akan diabaikan untuk notifikasi.
Contoh perintah curl
:
# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"remainingVehicleJourneySegments": [
{
"stop": {
"state": "ENROUTE",
"plannedLocation": {
"point": {
"latitude": 37.7749,
"longitude": -122.084061
}
},
"tasks": [
{
"taskId": "${TASK1_ID}"
}
]
}
},
{
"stop": {
"state": "NEW",
"plannedLocation": {
"point": {
"latitude": 37.3382,
"longitude": 121.8863
}
},
"tasks": [
{
"taskId": "${TASK2_ID}"
}
]
}
}
]
}
EOM
Perbarui lokasi kendaraan
Jika tidak menggunakan Driver SDK untuk memperbarui lokasi kendaraan, Anda dapat membuat panggilan langsung ke Fleet Engine dengan lokasi kendaraan. Untuk setiap kendaraan aktif, Fleet Engine mengharapkan pembaruan lokasi setidaknya sekali setiap menit dan maksimal setiap 5 detik sekali.
gRPC
Contoh berikut menunjukkan cara menggunakan Library gRPC Java untuk memperbarui lokasi kendaraan di Fleet Engine:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle myDeliveryVehicle = DeliveryVehicle.newBuilder()
.setLastLocation(DeliveryVehicleLocation.newBuilder()
.setSupplementalLocation(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863))
.setSupplementalLocationTime(now())
.setSupplementalLocationSensor(DeliveryVehicleLocationSensor.CUSTOMER_SUPPLIED_LOCATION)
.setSupplementalLocationAccuracy(DoubleValue.of(15.0))) // Optional
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
UpdateDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(vehicleName)
.setDeliveryVehicle(myDeliveryVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("last_location"))
.build();
try {
DeliveryVehicle updatedDeliveryVehicle =
deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Untuk memperbarui lokasi kendaraan di Fleet Engine menggunakan HTTP REST, lakukan panggilan ke
UpdateDeliveryVehicle
:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=last_location`
<id> adalah ID unik untuk kendaraan pengiriman di perangkat atau perangkat yang ingin Anda perbarui lokasi. Ini adalah pengenal yang yang Anda tentukan saat membuat kendaraan.
Header permintaan harus berisi kolom Authorization dengan nilai Bearer <token>, dengan <token> adalah token yang dikeluarkan oleh factory token Fleet Engine.
Isi permintaan harus berisi entity DeliveryVehicle
:
Kolom wajib diisi:
Kolom Nilai lastLocation.supplementalLocation Lokasi kendaraan. lastLocation.supplementalLocationTime Stempel waktu terakhir yang diketahui saat kendaraan berada di lokasi ini. lastLocation.supplementalLocationSensor Harus diisi dengan CUSTOMER_SUPPLIED_LOCATION. Kolom opsional:
Kolom Nilai lastLocation.supplementalLocationAccuracy Akurasi lokasi yang diberikan, dalam meter.
Contoh perintah curl
:
# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"lastLocation": {
"supplementalLocation": {"latitude": 12.1, "longitude": 14.5},
"supplementalLocationTime": "$(date -u --iso-8601=seconds)",
"supplementalLocationSensor": "CUSTOMER_SUPPLIED_LOCATION",
"supplementalLocationAccuracy": 15
}
}
EOM
Kendaraan tiba di perhentian
Fleet Engine harus diberi tahu saat kendaraan tiba di perhentian. Anda dapat memberi tahu Fleet Engine baik dari SDK Driver, atau dari lingkungan server menggunakan gRPC atau REST. Jangan gunakan kedua metode tersebut untuk menghindari race kondisi dan untuk mempertahankan satu sumber yang terpercaya.
gRPC
Contoh berikut menunjukkan cara menggunakan Library gRPC Java untuk memberi tahu Fleet Engine bahwa kendaraan tiba di perhentian:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
// Marking the arrival at stop.
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.7749)
.setLongitude(122.4194)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
.setState(VehicleStop.State.ARRIVED)))
// All other remaining stops marked as NEW.
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 2nd stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
.setState(VehicleStop.State.NEW))) // Remaining stops must be NEW.
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
UpdateDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(vehicleName)
.setDeliveryVehicle(deliveryVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("remaining_vehicle_journey_segments"))
.build();
try {
DeliveryVehicle updatedDeliveryVehicle =
deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Untuk memberi tahu Fleet Engine tentang kedatangan kendaraan
di perhentian dari lingkungan server,
lakukan panggilan REST HTTP ke UpdateDeliveryVehicle
:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`
<id> adalah ID unik untuk kendaraan pengiriman di armada Anda yang urutan tugasnya ingin Anda perbarui. Ini adalah pengenal yang yang Anda tentukan saat membuat kendaraan.
Header permintaan harus berisi kolom Authorization dengan nilai Bearer <token>, dengan <token> adalah token yang dikeluarkan oleh factory token Fleet Engine.
Isi permintaan harus berisi entity DeliveryVehicle
:
Kolom wajib diisi:
Kolom Nilai remainingVehicleJourneySegments Perhentian yang telah Anda capai dengan statusnya ditetapkan sebagai {i>State.ARRIVED<i}, diikuti dengan daftar perhentian kendaraan yang tersisa dengan negara bagiannya ditandai sebagai State.NEW. Kolom opsional:
- Tidak ada
Semua kolom lain dalam entity akan diabaikan untuk update.
Contoh perintah curl
:
# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"remainingVehicleJourneySegments": [
{
"stop": {
"state": "ARRIVED",
"plannedLocation": {
"point": {
"latitude": 37.7749,
"longitude": -122.084061
}
},
"tasks": [
{
"taskId": "${TASK1_ID}"
}
]
}
},
{
"stop": {
"state": "NEW",
"plannedLocation": {
"point": {
"latitude": 37.3382,
"longitude": 121.8863
}
},
"tasks": [
{
"taskId": "${TASK2_ID}"
}
]
}
}
]
}
EOM
Kendaraan menyelesaikan perhentian
Fleet Engine harus diberi tahu saat kendaraan berhenti. Hal ini menyebabkan semua tugas yang terkait dengan perhentian agar ditetapkan ke status TUTUP. Anda dapat memberi tahu Fleet Engine dari SDK Driver, atau dari lingkungan server menggunakan gRPC atau REST. Jangan gunakan kedua metode tersebut untuk menghindari kondisi race dan untuk mempertahankan satu sumber tepercaya.
gRPC
Contoh berikut menunjukkan cara menggunakan Library gRPC Java untuk memberi tahu Fleet Engine bahwa kendaraan telah selesai berhenti.
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
// This stop has been completed and is commented out to indicate it
// should be removed from the list of vehicle journey segments.
// .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()
// .setStop(VehicleStop.newBuilder()
// .setPlannedLocation(LocationInfo.newBuilder()
// .setPoint(LatLng.newBuilder()
// .setLatitude(37.7749)
// .setLongitude(122.4194)))
// .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
// .setState(VehicleStop.State.ARRIVED)))
// All other remaining stops marked as NEW.
// The next stop could be marked as ENROUTE if the vehicle has begun
// its journey to the next stop.
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // Next stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
.setState(VehicleStop.State.NEW)))
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
UpdateDeliveryVehicleRequest.newBuilder() // no need for the header
.setName(vehicleName)
.setDeliveryVehicle(deliveryVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("remaining_vehicle_journey_segments"))
.build();
try {
DeliveryVehicle updatedDeliveryVehicle =
deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Untuk memberi tahu Fleet Engine tentang penyelesaian
pemberhentian dari lingkungan server,
lakukan panggilan REST HTTP ke UpdateDeliveryVehicle
:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remaining_vehicle_journey_segments`
<id> adalah ID unik untuk kendaraan pengiriman di armada Anda yang urutan tugasnya ingin Anda perbarui. Ini adalah pengenal yang yang Anda tentukan saat membuat kendaraan.
Header permintaan harus berisi kolom Authorization dengan nilai Bearer <token>, dengan <token> adalah token yang dikeluarkan oleh factory token Fleet Engine.
Isi permintaan harus berisi entity DeliveryVehicle
:
Kolom wajib diisi:
Kolom Nilai remaining_vehicle_journey_segments Perhentian yang telah Anda selesaikan seharusnya tidak lagi ada dalam daftar perhentian kendaraan yang tersisa. Kolom opsional:
- Tidak ada
Semua kolom lain dalam entity akan diabaikan untuk update.
Contoh perintah curl
:
# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"remainingVehicleJourneySegments": [
{
"stop": {
"state": "NEW",
"plannedLocation": {
"point": {
"latitude": 37.3382,
"longitude": 121.8863
}
},
"tasks": [
{
"taskId": "${TASK2_ID}"
}
]
}
}
]
}
EOM
Memperbarui tugas
Sebagian besar kolom tugas tidak dapat diubah. Namun, Anda dapat memodifikasi status, hasil tugas, waktu hasil tugas, lokasi hasil tugas, dan atribut berdasarkan secara langsung memperbarui entity tugas. Misalnya, dalam kasus di mana tugas belum telah ditugaskan ke sebuah kendaraan, Anda dapat menutup tugas dengan memperbarui negara bagian secara langsung.
gRPC
Ini adalah contoh pembaruan tugas melalui gRPC.
REST
Ini adalah contoh pembaruan tugas melalui REST.
Menutup tugas
Untuk menutup tugas yang telah ditetapkan ke kendaraan, beri tahu Fleet Engine bahwa kendaraan telah menyelesaikan perhentian tempat tugas dilakukan atau menghapusnya dari daftar perhentian kendaraan. Untuk melakukannya, Anda dapat mengatur daftar kendaraan yang tersisa akan berhenti tepat saat memperbarui pengurutan tugas untuk kendaraan.
Jika tugas belum ditetapkan untuk kendaraan dan harus ditutup, perbarui tugas ke status TUTUP. Namun, Anda tidak dapat membuka kembali tugas yang TERTUTUP.
Penutupan tugas tidak mengindikasikan keberhasilan atau kegagalan. Ini menunjukkan bahwa tidak lagi dianggap sedang berlangsung. Untuk pelacakan armada, penting untuk menunjukkan hasil aktual dari suatu tugas sehingga pengiriman hasil dapat ditampilkan.
gRPC
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
.setName(taskName)
.setState(Task.State.CLOSED) // You can only directly CLOSE a
.build(); // task that is NOT assigned to a vehicle.
// Task request
UpdateTaskRequest updateTaskRequest =
UpdateTaskRequest.newBuilder() // No need for the header
.setTask(task)
.setUpdateMask(FieldMask.newBuilder().addPaths("state"))
.build();
try {
Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Untuk menandai tugas sebagai ditutup dari lingkungan server, buat panggilan REST HTTP untuk
UpdateTask
:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=state`
<id> adalah ID unik untuk tugas.
Header permintaan Anda harus berisi kolom Authorization dengan nilai Bearer <token>, dengan <token> adalah token yang dikeluarkan oleh factory token Fleet Engine.
Anda harus menyertakan entity Task
dalam isi permintaan:
Kolom wajib diisi:
Kolom Nilai dengan status tersembunyi akhir State.CLOSED Kolom opsional:
Kolom Nilai taskOutcome Results.Berhasil atau Hasil.FAILED taskOutcomeTime Waktu saat tugas diselesaikan. taskOutcomeLocation Lokasi tempat tugas diselesaikan. Fleet Engine menjadi default untuk ke lokasi kendaraan terakhir, kecuali jika diganti secara manual oleh penyedia.
Semua kolom lain dalam entity akan diabaikan untuk update.
Contoh perintah curl
:
# Set JWT, PROJECT_ID, and TASK_ID in the local environment curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=state,taskOutcome,taskOutcomeTime" \ -H "Content-type: application/json" \ -H "Authorization: Bearer ${JWT}" \ --data-binary @- << EOM { "state": "CLOSED", "taskOutcome": "SUCCEEDED", "taskOutcomeTime": "$(date -u --iso-8601=seconds)" } EOM
Menetapkan hasil tugas dan lokasi hasil
Penutupan tugas tidak menunjukkan keberhasilan atau kegagalan, itu menunjukkan bahwa maka tugas tersebut tidak lagi dianggap berjalan. Untuk pelacakan armada, penting untuk menunjukkan hasil aktual dari suatu tugas sehingga hasil pengiriman dapat ditampilkan dan ada penagihan yang tepat untuk layanan. Setelah ditetapkan, Anda tidak dapat mengubah hasil tugas. Namun, Anda dapat memodifikasi waktu hasil tugas dan lokasi hasil tugas setelah mereka ditetapkan.
Tugas yang berstatus DITUTUP dapat memiliki hasil yang ditetapkan ke SUCCEEDED atau GAGAL. Fleet Engine hanya mengenakan biaya pengiriman dengan status SUCCEEDED.
Saat menandai hasil tugas, Fleet Engine otomatis mengisi lokasi hasil tugas dengan lokasi kendaraan terakhir yang diketahui. Anda dapat mengganti perilaku ini.
gRPC
Anda memiliki opsi untuk menetapkan lokasi hasil tugas saat Anda menetapkan hasil proyek. Menyetel lokasi mencegah Fleet Engine menyetelnya ke {i>default <i}dari lokasi kendaraan. Anda juga dapat menimpa lokasi hasil tugas Fleet Engine tetapkan di lain waktu. Fleet Engine tidak pernah menimpa lokasi hasil tugas yang Anda sediakan. Anda tidak dapat menetapkan lokasi hasil tugas untuk tugas yang belum menetapkan hasil tugas. Anda dapat menetapkan kedua hasil tugas dan lokasi hasil tugas dalam permintaan yang sama.
Contoh berikut menunjukkan cara menggunakan Library gRPC Java untuk menetapkan hasil tugas ke SUCCEEDED dan setel lokasi tempat tugas berada selesai:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
.setName(taskName)
.setTaskOutcome(TaskOutcome.SUCCEEDED)
.setTaskOutcomeTime(now())
.setTaskOutcomeLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.build();
// Task request
UpdateTaskRequest updateTaskRequest =
UpdateTaskRequest.newBuilder() // No need for the header
.setTask(task)
.setUpdateMask(FieldMask.newBuilder().addPaths("task_outcome", "task_outcome_time", "task_outcome_location"))
.build();
try {
Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Untuk menandai tugas sebagai selesai
dari lingkungan server,
lakukan panggilan REST HTTP ke UpdateTask
:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=taskOutcome,taskOutcomeTime,taskOutcomeLocation`
<id> adalah ID unik untuk tugas.
Header permintaan harus berisi kolom Authorization dengan nilai Bearer <token>, dengan <token> adalah token yang dikeluarkan oleh factory token Fleet Engine.
Isi permintaan harus berisi entity Task
:
Kolom wajib diisi:
Kolom Nilai taskOutcome Results.Berhasil atau Hasil.FAILED Kolom opsional:
Kolom Nilai taskOutcomeLocation Lokasi tempat tugas diselesaikan. Jika tidak ditetapkan, Fleet Engine defaultnya adalah lokasi kendaraan terakhir. taskOutcomeTime Stempel waktu saat tugas selesai.
Semua kolom lain dalam entity akan diabaikan untuk update.
Contoh perintah curl
:
# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=taskOutcome,taskOutcomeTime,taskOutcomeLocation" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"taskOutcome": "SUCCEEDED",
"taskOutcomeTime": "$(date -u --iso-8601=seconds)",
"taskOutcomeLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
}
}
EOM
Mengubah rute pengiriman
Setelah tugas pengiriman dibuat, lokasi yang direncanakan tidak dapat diubah. Untuk mengubah rute pengiriman, tutup tugas pengiriman tanpa menyetelnya hasilnya, dan kemudian membuat tugas baru dengan lokasi yang direncanakan yang telah diperbarui. Setelah membuat tugas baru, tetapkan tugas ke kendaraan yang sama. Untuk selengkapnya informasi lainnya, lihat menutup tugas pengiriman dan menetapkan tugas.
Menggunakan kendaraan pengumpan dan pengiriman
Jika Anda menggunakan kendaraan pengumpan untuk mengangkut kiriman ke kendaraan pengiriman sepanjang hari, buat model transfer pengiriman sebagai tugas penghentian terjadwal untuk kendaraan pengiriman. Untuk memastikan pelacakan lokasi yang akurat, hanya tetapkan tugas pengiriman untuk pengiriman yang ditransfer setelah dimuat ke kendaraan pengiriman. Untuk informasi selengkapnya, lihat perhentian terjadwal.
Status pengiriman toko dan informasi meta lainnya
Saat tugas pengiriman selesai, status dan hasil tugas dicatat dalam tugas. Namun, Anda mungkin ingin memperbarui informasi meta yang spesifik untuk pengiriman. Untuk menyimpan informasi meta lain yang dapat Anda di luar layanan Fleet Engine, gunakan tracking_id yang terkait dengan tugas sebagai kunci dalam tabel eksternal.
Untuk informasi selengkapnya, lihat Masa aktif tugas.
Cari kendaraan
Anda bisa mencari kendaraan dari SDK Driver, atau dari lingkungan server menggunakan gRPC atau REST.
gRPC
Contoh berikut menunjukkan cara menggunakan Library gRPC Java untuk mencari kendaraan:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle request
String name = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
GetDeliveryVehicleRequest getVehicleRequest = GetDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(name)
.build();
try {
DeliveryVehicle vehicle = deliveryService.getDeliveryVehicle(getVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Untuk mencari kendaraan
dari lingkungan server,
lakukan panggilan REST HTTP ke GetVehicle
:
`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<vehicleId>`
<id> adalah ID unik untuk tugas.
<vehicleId> adalah ID kendaraan yang akan dicari.
Header permintaan harus berisi kolom Authorization dengan nilai Bearer <token>, dengan <token> adalah token yang dikeluarkan oleh factory token Fleet Engine.
Isi permintaan harus kosong.
Jika pencarian berhasil, isi respons berisi entity kendaraan.
Contoh perintah curl
:
# Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
"https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}"
Mencari tugas
Anda dapat mencari tugas dari lingkungan server menggunakan gRPC atau REST. Driver SDK tidak dukungan untuk mencari tugas.
gRPC
Contoh berikut menunjukkan cara menggunakan Library gRPC Java untuk mencari tugas:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8597549";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task request
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
GetTaskRequest getTaskRequest = GetTaskRequest.newBuilder() // No need for the header
.setName(taskName)
.build();
try {
Task task = deliveryService.getTask(getTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Untuk mencari tugas dari lingkungan server,
lakukan panggilan REST HTTP ke GetTask
:
`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<taskId>`
<id> adalah ID unik untuk tugas.
<taskId> adalah ID tugas yang akan dicari.
Header permintaan harus berisi kolom Authorization dengan nilai Bearer <token>, dengan <token> adalah token yang dikeluarkan oleh factory token Fleet Engine.
Isi permintaan harus kosong.
Jika pencarian berhasil, isi respons akan berisi entity tugas.
Contoh perintah curl
:
# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
"https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}"
Mencari informasi tugas pengiriman berdasarkan ID pelacakannya
Anda dapat mencari informasi tugas fleet dengan cara berikut, yang masing-masing memiliki tujuan berbeda:
- berdasarkan ID tugas: digunakan oleh pengguna seperti operator fleet yang memiliki akses ke tampilan lengkap dari data tugas.
- dengan ID pelacakan: digunakan oleh software klien untuk menyediakan informasi kepada pengguna akhir, seperti ketika sebuah paket diharapkan tiba di rumah mereka.
Bagian ini membahas pencarian informasi tugas dengan ID pelacakan. Jika Anda ingin untuk mencari tugas berdasarkan ID tugas, buka Mencari tugas.
Untuk mencari informasi menurut ID pelacakan, Anda dapat menggunakan salah satu cara berikut:
Persyaratan pencarian
Informasi pengiriman yang diberikan oleh ID pelacakan mematuhi aturan visibilitas dinyatakan di Kontrol visibilitas lokasi yang dilacak.
Gunakan Fleet Engine untuk mencari informasi pengiriman berdasarkan ID pelacakan. Pengemudi SDK tidak mendukung pencarian informasi berdasarkan ID pelacakan. Untuk melakukan ini dengan Fleet Google Cloud Platform, Anda menggunakan lingkungan server atau browser.
Gunakan token paling sempit untuk membatasi risiko keamanan. Misalnya, jika Anda menggunakan Token Konsumen Pengiriman, setiap panggilan API Pengiriman Fleet Engine menghasilkan hanya informasi yang relevan dengan pengguna akhir tersebut, seperti pengirim atau penerima pengiriman. Semua informasi lainnya dalam respons akan disamarkan. Untuk informasi selengkapnya tentang token, lihat Membuat Token Web JSON (JWT) untuk otorisasi.
Mencari dengan Java menggunakan gRPC
Contoh berikut menunjukkan cara menggunakan Library gRPC Java untuk mencari informasi tentang tugas pengiriman berdasarkan ID pelacakannya.
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TRACKING_ID = "TID-7449w087464x5";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Tasks request
String parent = "providers/" + PROJECT_ID;
GetTaskTrackingInfoRequest getTaskTrackingInfoRequest = GetTaskTrackingInfoRequest.newBuilder() // No need for the header
.setParent(parent)
.setTrackingId(TRACKING_ID)
.build();
try {
TaskTrackingInfo taskTrackingInfo = deliveryService.getTaskTrackingInfo(getTaskTrackingInfoRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
Mencari menggunakan HTTP
Untuk mencari tugas pengiriman dari browser, buat panggilan REST HTTP untuk
GetTaskTrackingInfo
:
`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/taskTrackingInfo/<tracking_id>`
<tracking_id> adalah ID pelacakan yang dikaitkan dengan tugas.
Header permintaan harus berisi kolom Authorization dengan nilai Bearer <token>, dengan <token> adalah token yang dikeluarkan oleh factory token Fleet Engine.
Jika pencarian berhasil, isi respons berisi taskTrackingInfo entitas.
Contoh perintah curl
:
# Set JWT, PROJECT_ID, and TRACKING_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
"https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/taskTrackingInfo/${TRACKING_ID}"
Membuat daftar tugas
Anda dapat membuat daftar tugas dari lingkungan server atau browser. Driver SDK tidak mendukung tugas daftar.
Mencantumkan tugas meminta akses luas ke tugas. Tugas daftar hanya dimaksudkan untuk pengguna tepercaya. Gunakan Pembaca Armada Pengiriman atau Pengiriman Autentikasi Pengguna Super Token saat membuat permintaan tugas daftar.
Kolom berikut pada tugas yang tercantum telah disamarkan:
- VehicleStop.planned_location
- VehicleStop.state
- VehicleStop.TaskInfo.taskId
Tugas yang tercantum dapat difilter menurut sebagian besar properti tugas. Untuk sintaks kueri filter, lihat AIP-160. Daftar berikut menunjukkan tugas yang valid yang dapat Anda gunakan untuk memfilter:
- attribut
- delivery_vehicle_id
- dengan status tersembunyi akhir
- planned_location
- task_duration
- task_outcome
- task_outcome_location
- task_outcome_location_source
- task_outcome_time
- tracking_id
- jenis
Gunakan format kolom berikut berdasarkan Proposal Peningkatan Google API:
Jenis Kolom | Format | Contoh |
---|---|---|
Stempel waktu | RFC-3339 | task_outcome_time = 2022-03-01T11:30:00-08:00 |
Durasi | Jumlah detik diikuti dengan s |
task_duration = 120s |
Enum | String | state = CLOSED AND type = PICKUP |
Lokasi | point.latitude dan point.longitude |
planned_location.point.latitude > 36.1 AND planned_location.point.longitude < -122.0 |
Lihat AIP-160 untuk mengetahui daftar lengkap kueri filter operator.
Jika tidak ada kueri filter yang ditentukan, semua tugas akan dicantumkan.
Daftar tugas diberi nomor halaman. Ukuran halaman dapat ditentukan dalam permintaan tugas daftar. Jika ukuran halaman ditentukan, jumlah tugas yang ditampilkan tidak lebih besar dari ukuran halaman yang ditentukan. Jika tidak ada ukuran halaman, setelan default yang wajar digunakan. Jika ukuran halaman yang diminta melebihi nilai maksimum internal, maka nilai maksimum internal akan digunakan.
Daftar tugas dapat menyertakan token untuk membaca halaman hasil berikutnya. Menggunakan token halaman dengan permintaan yang identik dengan token sebelumnya untuk mengambil laman tugas berikutnya. Kapan token halaman yang ditampilkan kosong, tidak ada lagi tugas yang tersedia untuk diambil.
gRPC
Contoh berikut menunjukkan cara menggunakan Library gRPC Java untuk mencantumkan tugas untuk deliveryKendaraanId dan atribut tugas. Iklan respons masih boleh kosong. Respons kosong menunjukkan bahwa tidak ada Tasks yang yang terkait dengan deliveryKendaraanId yang disediakan.
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TRACKING_ID = "TID-7449w087464x5";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Tasks request
String parent = "providers/" + PROJECT_ID;
ListTasksRequest listTasksRequest = ListTasksRequest.newBuilder() // No need for the header
.setParent(parent)
.setFilter("delivery_vehicle_id = 123 AND attributes.foo = true")
.build();
try {
ListTasksResponse listTasksResponse = deliveryService.listTasks(listTasksRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Untuk menampilkan daftar tugas dari browser, lakukan panggilan REST HTTP ke ListTasks
:
`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks`
Untuk menerapkan filter ke tugas yang tercantum, sertakan "filter" Parameter URL dengan kueri filter yang di-escape URL sebagai nilainya.
Header permintaan harus berisi kolom Authorization dengan nilai Bearer <token>, dengan <token> adalah token yang dikeluarkan oleh factory token Fleet Engine.
Jika pencarian berhasil, isi respons berisi data dengan struktur berikut:
// JSON representation
{
"tasks": [
{
object (Task)
}
],
"nextPageToken": string,
"totalSize": integer
}
Respons yang berhasil masih boleh kosong. Respons kosong menunjukkan bahwa tidak tugas yang ditemukan memenuhi kriteria filter yang ditentukan.
Contoh perintah curl
:
# Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
"https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?filter=state%20%3D%20OPEN%20AND%20delivery_vehicle_id%20%3D%20${VEHICLE_ID}"
Buat daftar kendaraan pengiriman
Anda dapat menampilkan daftar kendaraan pengiriman dari lingkungan server atau browser. Pengemudi SDK tidak mendukung listingan kendaraan pengiriman.
Mencantumkan kendaraan pengiriman meminta akses yang luas ke kendaraan pengiriman dan hanya ditujukan untuk pengguna tepercaya. Gunakan Pembaca Armada Pengiriman atau Super Pengiriman Token Autentikasi Pengguna saat membuat permintaan kendaraan pengiriman daftar.
Kolom berikut pada kendaraan pengiriman yang tercantum disamarkan karena dampaknya tentang ukuran respons:
- CurrentRouteSegment
- RemainingVehicleJourneySegments
Anda dapat memfilter daftar kendaraan pengiriman menurut properti attributes
. Sebagai
Misalnya, untuk mengkueri atribut dengan kunci my_key
dan nilai my_value
, gunakan
attributes.my_key = my_value
. Untuk membuat kueri beberapa atribut, gabungkan kueri
menggunakan operator AND
dan OR
yang logis seperti di attributes.key1 = value1 AND
attributes.key2 = value2
. Lihat AIP-160 untuk mengetahui
deskripsi sintaksis kueri filter.
Anda dapat memfilter kendaraan pengiriman yang tercantum menurut lokasi menggunakan permintaan viewport
. Parameter permintaan viewport
menentukan area pandang menggunakan dua pembatas
koordinat: lintang dan bujur high
(timur laut) dan low
(barat daya)
pasangan koordinat objek. Permintaan ditolak jika memuat lintang tinggi
yang secara geografis lebih rendah dari lintang rendah.
Daftar kendaraan pengiriman akan dipaginasi secara default menggunakan ukuran halaman yang wajar. Jika Anda menentukan ukuran halaman, permintaan hanya akan menampilkan jumlah kendaraan yang ditentukan oleh batas, atau lebih sedikit. Jika ukuran halaman yang diminta melebihi nilai maksimum, maka nilai maksimum internal akan digunakan. Halaman default dan maksimum berukuran sama-sama 100 kendaraan.
Daftar kendaraan pengiriman dapat menyertakan token untuk membaca halaman berikutnya dari hasil pengujian tersebut. Token halaman hanya ada dalam respons jika lebih banyak halaman penayangan kendaraan tersedia untuk diambil kembali. Untuk mengambil halaman tugas berikutnya, gunakan token halaman dengan permintaan yang identik dengan token permintaan.
gRPC
Contoh berikut menunjukkan cara menggunakan Library gRPC Java untuk mencantumkan kendaraan pengiriman di region tertentu dengan atribut tertentu. J respons yang berhasil masih boleh kosong. Ketika itu terjadi, itu berarti tidak ada kendaraan dengan atribut yang ditentukan sudah ada di area pandang yang ditentukan.
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Tasks request
String parent = "providers/" + PROJECT_ID;
ListDeliveryVehiclesRequest listDeliveryVehiclesRequest =
ListDeliveryVehiclesRequest.newBuilder() // No need for the header
.setParent(parent)
.setViewport(
Viewport.newBuilder()
.setHigh(LatLng.newBuilder()
.setLatitude(37.45)
.setLongitude(-122.06)
.build())
.setLow(LatLng.newBuilder()
.setLatitude(37.41)
.setLongitude(-122.11)
.build())
.setFilter("attributes.my_key = my_value")
.build();
try {
ListDeliveryVehiclesResponse listDeliveryVehiclesResponse =
deliveryService.listDeliveryVehicles(listDeliveryVehiclesRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Untuk menampilkan daftar tugas dari browser, lakukan panggilan REST HTTP ke ListDeliveryVehicles
:
`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles`
Untuk menerapkan filter ke tugas yang tercantum, sertakan "filter" parameter URL dengan Kueri filter yang di-escape URL sebagai nilainya.
Header permintaan harus berisi kolom Authorization dengan nilai Bearer <token>, dengan <token> adalah token yang dikeluarkan oleh factory token Fleet Engine.
Jika pencarian berhasil, isi respons berisi data dengan struktur berikut:
// JSON representation
{
"deliveryVehicles": [
{
object (DeliveryVehicle)
}
],
"nextPageToken": string,
"totalSize": integer
}
Respons yang berhasil masih boleh kosong. Ketika itu terjadi, itu berarti tidak ada kendaraan pengiriman ditemukan memenuhi area pandang dan kueri filter yang ditentukan.
Contoh perintah curl
:
# Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
"https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?filter=attributes.my_key%20%3D%20my_value%20&viewport.high.latitude=37.45&viewport.high.longitude=-122.06&viewport.low.latitude=37.41&viewport.low.longitude=-122.11"
Pelacakan armada
Anda memiliki dua opsi untuk menggunakan Fleet Engine Deliveries API untuk memungkinkan pelacakan fleet:
Pilihan: Gunakan Library Pelacakan Armada JavaScript. Library memungkinkan Anda memvisualisasikan lokasi kendaraan dan lokasi yang dilacak di Fleet Engine. Berisi komponen peta JavaScript yang merupakan pengganti langsung untuk objek google.maps.Map standar, dan komponen data untuk terhubung dengan Fleet Engine. Komponen ini memungkinkan Anda memberikan pengalaman pelacakan perangkat animasi yang dapat disesuaikan dari web atau aplikasi seluler.
Implementasikan pelacakan perangkat Anda di atas Fleet Engine Deliveries API.
Kuncinya adalah mencari tugas fleet dengan melacak ID.
Logging
Anda dapat menetapkan Fleet Engine untuk mengirim log RPC ke Cloud Logging. Untuk selengkapnya informasi, lihat Logging.
Peran dan Token Otorisasi
Seperti yang dijelaskan dalam Mengelola siklus proses kendaraan dan tugas dan catatan otorisasi untuk setiap kasus penggunaan, sehingga panggilan ke Fleet Engine memerlukan autentikasi dengan Token Web JSON yang memiliki telah ditandatangani menggunakan kredensial akun layanan. Akun layanan yang digunakan token tersebut mungkin memiliki satu atau beberapa peran, dengan setiap pemberian peran kumpulan izin akses yang berbeda.
Untuk informasi selengkapnya, lihat Autentikasi dan Otorisasi.
Memecahkan masalah umum
Periksa bagian berikut untuk mendapatkan bantuan jika Anda mengalami masalah apa pun.
Ketahanan
Fleet Engine tidak dianggap sebagai sumber kebenaran. Anda bertanggung jawab untuk memulihkan status sistem Anda, jika perlu, tanpa bergantung pada Fleet Engine.
Status hilang di Fleet Engine
Saat bekerja dengan Fleet Engine, terapkan klien agar sistem sembuh itu sendiri jika terjadi kegagalan. Misalnya, saat Fleet Engine mencoba memperbarui kendaraan, sistem mungkin merespons dengan error yang menunjukkan bahwa kendaraan tidak ada. Klien kemudian harus membuat ulang kendaraan di status baru. Meskipun masalah ini jarang terjadi, pastikan sistem Anda cukup tangguh untuk menangani anotasi.
Dalam skenario kegagalan bencana yang sangat tidak mungkin terjadi di Fleet Engine, Anda mungkin perlu membuat ulang sebagian besar atau semua kendaraan dan tugas. Jika rasio pembuatan menjadi terlalu tinggi, beberapa permintaan mungkin gagal lagi karena masalah kuota Pemeriksaan kuota diterapkan untuk menghindari serangan denial of service (DOS). Dalam hal ini, perlambat laju pembuatan ulang menggunakan strategi backoff untuk percobaan ulang.
Status hilang di aplikasi driver
Jika aplikasi driver error, aplikasi harus membuat ulang status saat ini dalam Driver SDK. Aplikasi harus mencoba membuat ulang tugas untuk memastikan yang ada dan memulihkan statusnya saat ini. Aplikasi juga harus membuat ulang dan menetapkan secara eksplisit daftar perhentian untuk Driver SDK.
FAQ
Bagaimana jika pengemudi berhenti untuk melakukan tugas secara tidak berurutan?
Dalam hal ini, perbarui urutan tugas terlebih dahulu dan lanjutkan seperti biasa, menandai kedatangan di perhentian, penyelesaian tugas, dan detail lainnya. Jika tidak dilakukan, sistem mungkin menjadi tidak konsisten, PWT bisa menjadi salah, dan error tak terduga mungkin akan dilaporkan.