Mulai menggunakan Fleet Engine untuk Pelacakan Pengiriman

Buat model aktivitas fleet Anda untuk mil pertama dan terakhir pengiriman dengan Fleet Engine Deliveries API. Anda dapat menggunakan API ini dengan 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 mengetahui informasi tentang langkah-langkah yang harus dilakukan dalam konsol dan cara membuat Token Web JSON untuk otorisasi, lihat Autentikasi dan otorisasi.

• Untuk mengetahui detail tentang cara menggunakan konsol, lihat dokumentasi Konsol Google Cloud.

Memverifikasi penyiapan Anda

Setelah membuat akun layanan, pastikan penyiapan Anda selesai dan Anda dapat membuat kendaraan pengiriman. Dengan segera memverifikasi konfigurasi, Anda dapat memastikan bahwa Anda telah mengatasi masalah otorisasi umum yang dapat muncul saat menyiapkan project. Ada dua cara untuk memverifikasi konfigurasi Anda:

• Uji dua bagian penting penyiapan Anda: penandatanganan token otorisasi dan pembuatan kendaraan pengiriman uji coba dengan utilitas command line gcloud. Untuk mengetahui detailnya, lihat panduan Memverifikasi penyiapan.

• Uji konfigurasi Anda dengan Contoh Skrip Autentikasi Flet Engine.

Library Klien

Untuk mendapatkan pengalaman developer yang lebih baik melalui gRPC atau REST mentah, gunakan library klien dalam beberapa bahasa pemrograman umum. Untuk mengetahui petunjuk 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 pengiriman:

• Kendaraan pengiriman yang digunakan untuk mengangkut kiriman.
• Tugas pengambilan dan pengiriman kiriman.

Anda juga menggunakan tugas untuk membuat model waktu istirahat pengemudi dan perhentian terjadwal sepanjang hari.

Kendaraan pengiriman

Kendaraan pengiriman mengangkut kiriman dari depot ke lokasi pengiriman, dan dari lokasi pengambilan ke depot. Dalam kasus tertentu, mereka juga dapat memindahkan kiriman langsung dari lokasi pengambilan ke lokasi pengiriman.

Gunakan Driver SDK untuk membuat objek DeliveryVehicle di Fleet Engine dan mengirim pembaruan lokasi untuk pengiriman dan pelacakan fleet.

Tugas

Untuk tindakan yang dilakukan kendaraan pada siang hari, Anda menetapkan tugas sesuai dengan jenis tindakan:

• Untuk pengambilan dan pengantaran, tetapkan Tugas pengiriman.
• Saat pengemudi tidak tersedia, seperti waktu istirahat yang diwajibkan, tetapkan Tugas ketidaktersediaan.
• Untuk tugas tanpa pengemudi di drop box atau lokasi pelanggan, tetapkan Tugas perhentian terjadwal.

Setiap tugas yang Anda tetapkan harus memiliki ID tugas unik, tetapi tugas dapat memiliki ID pelacakan yang sama. Saat Fleet Engine menghitung periode PWT untuk setiap tugas, Fleet Engine menggunakan semua tugas dan urutan penjadwalannya untuk membuat estimasi. Untuk mengetahui informasi selengkapnya tentang ID tugas, lihat Panduan ID Tugas.

Untuk membuat tugas di Fleet Engine, gunakan Task Manager Driver SDK.

Tugas pengiriman

Buat tugas pengiriman untuk pengambilan dan pengantaran kiriman, dan sertakan informasi berikut:

• Lokasi pengambilan atau pengiriman.
• Nomor atau ID pelacakan.
• Waktu singgah untuk memperhitungkan waktu tambahan guna menyelesaikan tugas, mencari tempat parkir, atau berjalan ke lokasi penyerahan.
• ID tugas unik. Lihat Panduan ID Tugas.

Untuk informasi selengkapnya, lihat topik berikut:

Android

• Membuat tugas pengambilan pengiriman
• Membuat tugas pengiriman

iOS

• GMTD DeliveryTaskManager.
• GMTSTaskType

Tugas ketidaktersediaan

Tugas ketidaktersediaan mencakup jangka waktu saat kendaraan tidak dapat diambil atau dikirim, seperti istirahat untuk mengisi bahan bakar kendaraan atau istirahat bagi pengemudi.

Buat tugas ketidaktersediaan dengan informasi berikut:

• Lamanya jeda.
• (Opsional) Lokasi istirahat. Anda tidak perlu memberikan lokasi tertentu, tetapi hal ini akan memberikan periode PWT yang lebih akurat sepanjang hari.

Catatan: Selama tugas ketidaktersediaan, tidak ada informasi lokasi yang akan dibagikan kepada pengguna akhir Shipment Tracking Library. Namun, fitur ini tersedia untuk pengelola inventaris yang menggunakan Library Pelacakan Fleet.

Untuk informasi selengkapnya, lihat topik berikut:

Android

• Ketidaktersediaan terjadwal

iOS

• GMTD DeliveryTaskManager.
• GMTSTaskType

Tugas perhentian terjadwal

Buat tugas perhentian terjadwal untuk membuat model perhentian yang perlu dilakukan oleh kendaraan pengiriman. Misalnya, buat tugas perhentian terjadwal untuk perhentian pengambilan terjadwal harian di lokasi tertentu, terlepas dari pengiriman atau penjemputan lainnya di lokasi yang sama. Anda juga dapat membuat tugas perhentian terjadwal untuk pengumpulan dari drop box atau untuk membuat model transfer kendaraan pengumpan atau pemberhentian di pusat servis dan titik servis.

Untuk informasi selengkapnya, lihat topik berikut:

Android

• Perhentian terjadwal

iOS

• GMTD DeliveryTaskManager.
• GMTSTaskType

Panduan ID tugas

Saat Anda membuat ID tugas, ikuti panduan konten dan format berikut:

• Membuat ID tugas unik
• Jangan mengekspos informasi identitas pribadi (PII) atau data teks yang jelas.
• 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.

Tips: Anda dapat membuat ID tugas menggunakan mekanisme terprogram yang diinginkan. Google merekomendasikan penggunaan alat UUID versi 4.

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 ada dalam setiap struktur 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 yang digunakan untuk memanggil Fleet Engine API.
• 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 diupdate menggunakan UpdateDeliveryVehicle setelah tujuh hari. Untuk melihat apakah kendaraan ada:

1. Lakukan panggilan ke UpdateDeliveryVehicle.
2. Jika Anda mendapatkan error NOT_FOUND, panggil CreateDeliveryVehicle untuk membuat ulang kendaraan. Jika panggilan menampilkan kendaraan, panggilan masih dapat diperbarui.

Catatan: Jika Anda memanggil CreateDeliveryVehicle dengan pasangan project ID dan ID kendaraan yang sudah ada, Anda akan mendapatkan error.

Jenis kendaraan

Entity VehicleType berisi kolom opsional VehicleType, yang berisi enum Category yang dapat Anda tentukan sebagai AUTO, TWO_WHEELER, BICYCLE, atau PEDESTRIAN. Jika Anda tidak menetapkan kolom ini, nilai defaultnya adalah AUTO.

Semua pemilihan rute untuk kendaraan menggunakan RouteTravelMode yang sesuai untuk jenis kendaraannya.

Atribut kendaraan

Entity DeliveryVehicle berisi kolom berulang DeliveryVehicleAttribute. ListDeliveryVehicles API mencakup kolom filter yang dapat membatasi entity DeliveryVehicle yang ditampilkan ke entity dengan atribut yang ditentukan. DeliveryVehicleAttribute tidak memengaruhi perilaku perutean Fleet Engine.

Jangan menyertakan informasi identitas pribadi (PII) atau informasi sensitif dalam atribut karena kolom ini dapat dilihat oleh pengguna.

Umur tugas

Anda dapat membuat, memperbarui, dan membuat kueri tugas di Fleet Engine dengan antarmuka gRPC atau REST Deliveries API.

Objek Task memiliki kolom status untuk melacak perkembangannya selama siklus prosesnya. 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 menetapkan status tugas ke TUTUP secara otomatis.

Saat kendaraan tugas menyelesaikan penghentian kendaraan tugas:

1. Perbarui kolom hasil tugas ke SUCCESS atau FAILED.

   Catatan: Anda dapat menetapkan hasil tugas kapan saja sebelum atau setelah tugas selesai, tetapi hanya dapat menetapkannya sekali.

2. Tentukan stempel waktu peristiwa.

   Selanjutnya, library Pelacakan Pengiriman JavaScript akan menunjukkan hasil tugas dan status tugas akan otomatis ditetapkan ke CLOSED. Untuk informasi selengkapnya, lihat Melacak Pengiriman dengan library Pelacakan Pengiriman JavaScript.

Seperti kendaraan, Fleet Engine menghapus tugas yang belum diperbarui setelah tujuh hari, dan jika Anda mencoba membuat tugas dengan ID yang sudah ada, error akan ditampilkan.

Catatan: Fleet Engine tidak mendukung penghapusan tugas secara eksplisit. Layanan akan otomatis menghapus tugas setelah tujuh hari tanpa update. Jika ingin menyimpan data tugas lebih dari tujuh hari, Anda harus menerapkan kemampuan itu sendiri.

Atribut tugas

Entity Task berisi kolom berulang TaskAttribute, yang dapat memiliki nilai dari salah satu dari 3 jenis tersebut: string, angka, dan bool. ListTasks API mencakup kolom filter yang dapat membatasi entity Task yang ditampilkan ke entity dengan atribut yang ditentukan. Atribut tugas tidak memengaruhi perilaku perutean Fleet Engine.

Jangan menyertakan informasi identitas pribadi (PII) atau informasi sensitif lainnya 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 ditingkatkan oleh Fleet Engine Deliveries API untuk Anda.

Untuk mengelola siklus proses kendaraan dan tugas di sistem Anda, gunakan Fleet Engine Deliveries API untuk membuat, mengupdate, dan melacak kendaraan Anda serta tugas terkait.

Pada saat yang sama, aplikasi pengemudi berkomunikasi langsung ke Fleet Engine untuk memperbarui informasi rute dan lokasi perangkat. Dengan model ini, Fleet Engine dapat mengelola lokasi real-time secara efisien. Fungsi ini mengirimkan lokasi langsung ke library pelacakan, yang kemudian dapat Anda gunakan untuk memperbarui status pesanan kepada konsumen.

Misalnya, Anda memiliki skenario berikut:

• Pengemudi mendekati halte pengiriman. Aplikasi driver mengirimkan lokasinya ke Fleet Engine.
• Fleet Engine mengirimkan lokasi perangkat ke library pelacakan, yang digunakan aplikasi konsumen untuk memberi tahu konsumen tentang jarak paket mereka.
• Setelah pengemudi menyelesaikan pengiriman, mereka mengklik tombol "Pengiriman terkirim" di aplikasi pengemudi.
• Tindakan "Pengiriman terkirim" mengirimkan informasi ke sistem backend Anda, yang melakukan langkah-langkah validasi dan verifikasi bisnis yang diperlukan.
• Sistem Anda mengonfirmasi tugas sebagai Assistant dan mengupdate Fleet Engine menggunakan Deliveries API.

Diagram berikut mengilustrasikan proses ini pada tingkat umum. Contoh ini juga menunjukkan hubungan standar antara sistem Anda, klien, dan Fleet Engine.

Kelola token klien

Pembaruan lokasi yang berasal dari aplikasi pengemudi dan yang dikirim langsung ke Fleet Engine memerlukan token otorisasi. Berikut adalah pendekatan yang direkomendasikan untuk menangani update dari klien ke Fleet Engine:

1. Buat token menggunakan peran akun layanan Fleet Engine Delivery Untrusted Driver User.

2. Berikan token cakupan terbatas ke aplikasi pengemudi. Cakupan ini hanya memungkinkannya memperbarui lokasi perangkat di Fleet Engine.

Pendekatan ini memastikan bahwa panggilan yang berasal dari perangkat seluler--yang dianggap sebagai lingkungan dengan tingkat kepercayaan rendah--mematuhi prinsip hak istimewa terendah.

Peran akun layanan lainnya

Jika Anda ingin mengizinkan aplikasi driver untuk melakukan update Fleet Engine langsung di luar update yang dibatasi untuk peran Driver Tidak Tepercaya, seperti untuk update tugas tertentu, Anda dapat menggunakan peran Driver Tepercaya. Untuk mengetahui informasi tentang model yang menggunakan peran Trusted Driver, lihat Model Driver Tepercaya.

Untuk mengetahui informasi selengkapnya tentang penggunaan peran driver yang tidak tepercaya dan tepercaya, lihat Penyiapan project Cloud.

Membuat model hari kerja

Tabel berikut menjelaskan tampilan hari kerja untuk pengemudi kilometer pertama atau terakhir di perusahaan pengiriman dan logistik. Perusahaan Anda mungkin memiliki detail yang berbeda, tetapi Anda dapat melihat bagaimana Anda dapat membuat model hari kerja.

Waktu	Aktivitas	Pemodelan
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 lainnya di Fleet Engine terlebih dahulu. Misalnya, Anda dapat membuat tugas pengambilan barang, tugas pengantaran pengiriman, ketidaktersediaan terjadwal, atau perhentian terjadwal. Tetapkan 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, buat tugas pengiriman pengiriman pada saat pemindaian.
	Pengemudi mengonfirmasi urutan tugas yang akan dilakukan.	Jika tidak dibuat sebelumnya, buat tugas pengambilan pengiriman, ketidaktersediaan terjadwal, dan perhentian terjadwal.
	Pengemudi meninggalkan depot dan berkomitmen pada jumlah tugas berikutnya yang harus diselesaikan.	Tetapkan semua tugas atau subset tugas ke kendaraan dengan menerapkan urutan penyelesaiannya.
	Pengemudi mengirim barang.	Setelah tiba di perhentian pengiriman, lakukan tindakan terkait kendaraan yang tiba di perhentian. Setelah mengirim pengiriman, tutup tugas pengiriman dan, jika perlu, status pengiriman toko dan informasi meta lainnya. Setelah menyelesaikan semua tugas di perhentian dan sebelum mulai berkendara ke perhentian berikutnya, lakukan 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 urutan penyelesaian tugas dengan menetapkan tugas ke kendaraan dan memperbarui pengurutan tugas.
	Pengemudi menerima notifikasi permintaan pengambilan.	Setelah menerima permintaan pengambilan, buat tugas pengambilan pengiriman. Kemudian, perbarui urutan eksekusi tugas dengan menetapkan tugas ke kendaraan dan memperbarui pengurutan tugas.
Tengah hari	Pengemudi beristirahat makan siang.	Jika lokasi dikaitkan dengan tugas ketidaktersediaan, perlakukan tugas tersebut seperti tugas lainnya. Lakukan tindakan terkait kendaraan yang tiba di perhentian berikutnya, kendaraan menyelesaikan perhentian, dan kendaraan yang sedang dalam perjalanan ke perhentian berikutnya. Jika tidak, tindakan lebih lanjut tidak diperlukan sampai jeda iklan berakhir. Hapus tugas dengan mengonfirmasi tugas berikutnya dan yang tersisa, serta memperbarui pengurutan tugas.
	Pengemudi mengambil kiriman.	Ini dimodelkan seperti perhentian pengiriman. Lakukan tindakan yang terkait dengan kendaraan yang tiba di perhentian dan menutup tugas serta, secara opsional, menyimpan status pengiriman dan informasi meta lainnya. Setelah menyelesaikan semua tugas di perhentian dan sebelum mulai berkendara ke perhentian berikutnya, lakukan 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 tugas pengiriman yang sesuai. Jika pengangkutan penumpang akan diantar ke lokasi lain di rute yang sama dengan pengemudi pada hari tersebut, sebaiknya buat model tugas pengiriman tersebut seperti tugas pengiriman lainnya di rute tersebut. Jika pengemudi membawa kembali pengambilan ke depot, sebaiknya buat tugas pengiriman di tujuan depot.
	Pengemudi membuat jadwal perhentian untuk mengambil kiriman dari kotak barang.	Di sini dibuat modelnya sama seperti tempat penjemputan lainnya. Lakukan tindakan yang terkait dengan kendaraan yang tiba di perhentian dan menutup tugas. Setelah menyelesaikan semua tugas di perhentian dan mulai berkendara ke perhentian berikutnya, lakukan tindakan terkait 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 tugas pengiriman baru untuk lokasi pengiriman baru. Untuk mengetahui informasi selengkapnya, lihat Mengubah rute pengiriman.
	Pengemudi mencoba mengirimkan paket tetapi tidak dapat melakukannya.	Proses ini dibuat mirip dengan perhentian pengiriman yang berhasil, yang menandai tugas pengiriman sebagai selesai. Melakukan tindakan yang terkait dengan kendaraan yang tiba di perhentian. Setelah gagal mengirimkan pengiriman, tutup tugas dan, jika perlu, status pengiriman toko dan informasi meta lainnya. Setelah menyelesaikan semua tugas di perhentian dan sebelum mulai berkendara ke perhentian berikutnya, lakukan 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 SELESAI.
	Pengemudi diberi tahu untuk mengirimkan kiriman tertentu berikutnya, sehingga mengubah komitmen pesanan pengiriman.	Memperbarui urutan tugas.
	Pengemudi memilih untuk mengantarkan pesanan secara tidak berurutan.	Perbarui pengurutan 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 terkait 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 berkendara ke perhentian berikutnya, lakukan 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 pengiriman yang diambil selama rutenya, Anda juga harus membuat dan menutup setiap paket sebagai tugas pengiriman untuk memastikan penagihan yang benar. Anda dapat melakukannya dengan membuat model depot seperti perhentian pengiriman lainnya. Jika depot tidak digunakan sebagai perhentian pengiriman, Anda masih dapat memodelkan depot sebagai perhentian terjadwal. Dengan pemodelan perhentian, pengemudi Anda dapat melihat rute kembali ke depot dan memberikan visibilitas perkiraan waktu tiba mereka.

Cara kerja pembaruan lokasi

Untuk performa terbaik dengan Fleet Engine, berikan aliran data pembaruan lokasi kendaraan. Gunakan salah satu cara berikut untuk memberikan update ini:

1. Gunakan Driver SDK - Android, iOS - opsi paling sederhana.
2. Gunakan kode kustom -- berguna jika lokasi di-relai 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 kendaraan pengiriman dalam perjalanan ke perhentian (termasuk depot) dan saat tiba di perhentian. Fleet Engine tidak mendeteksi peristiwa ini secara otomatis.

Perhentian kendaraan dan lokasi pengiriman

Perhentian kendaraan adalah tempat kendaraan pengiriman menyelesaikan tugas pengiriman atau tugas lainnya. Titik akses ini dapat berupa titik akses seperti dok pemuatan atau lokasi yang diikat jalan.

Lokasi pengiriman adalah lokasi tempat pengiriman diantarkan atau diambil. Untuk menuju dan dari lokasi pengiriman mungkin perlu berjalan kaki dari halte kendaraan.

Misalnya, saat pengemudi mengantarkan pengiriman ke toko di suatu mal, kendaraan pengiriman akan 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 tempat toko tersebut berada. Ini adalah lokasi pengiriman.

Untuk pengalaman pelacakan pengiriman terbaik bagi pengguna Anda, pertimbangkan cara tugas pengiriman ditetapkan ke perhentian kendaraan dan perlu diingat bahwa jumlah perhentian kendaraan yang tersisa untuk tugas pengiriman dilaporkan kepada pengguna untuk membantu mereka melihat progres pengiriman mereka.

Misalnya, jika pengemudi melakukan banyak pengiriman ke satu gedung kantor, pertimbangkan untuk menetapkan semua tugas pengiriman ke satu perhentian kendaraan. Jika setiap tugas pengiriman ditetapkan ke perhentian kendaraannya sendiri, pengalaman pelacakan pengiriman Anda akan kurang membantu bagi pengguna karena pelacakan hanya tersedia setelah kendaraan berada dalam sejumlah perhentian kendaraan yang terbatas sebelum tempat tujuan. Banyaknya penghentian kendaraan yang diselesaikan dalam waktu singkat tidak memberi pengguna banyak waktu untuk melacak progres 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));
     }
   });

Catatan: Driver SDK berisi API untuk beberapa vertical, termasuk pengiriman. Untuk mengurangi ukuran biner secara keseluruhan, gunakan ProGuard atau alat pengoptimalan lainnya untuk menghapus kode yang tidak digunakan.

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 buram untuk Fleet Engine. Hindari penggunaan ID yang bertambah otomatis, dan pastikan 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 baru. Perhatikan bahwa setiap nilai yang ditentukan untuk kolom Name akan diabaikan sesuai dengan 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 kolom tersebut bersifat hanya baca atau hanya dapat diupdate dengan panggilan ke UpdateDeliveryVehicle.

Untuk membuat kendaraan tanpa menyetel kolom opsional, Anda dapat membiarkan 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, buat 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> berupa token yang dikeluarkan oleh factory token Fleet Engine.

Isi POST mewakili entity DeliveryVehicle yang akan dibuat. Anda dapat menentukan kolom opsional berikut:

• atribut
• lastLocation
• tipe

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 kolom tersebut bersifat hanya baca atau hanya dapat diupdate menggunakan panggilan ke UpdateDeliveryVehicle.

Untuk membuat kendaraan tanpa menyetel kolom apa pun, kosongkan isi permintaan POST. 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 Driver SDK 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. Nomor ini tidak boleh berupa nomor pelacakan untuk pengiriman. Jika tidak memiliki ID tugas di sistem, Anda dapat membuat ID unik universal (UUID).

Header permintaan harus berisi kolom Authorization dengan nilai Bearer <token>, dengan <token> berupa token yang dikeluarkan oleh factory token Fleet Engine.

Isi permintaan harus berisi entity Task:

• Kolom wajib diisi:

  Kolom	Nilai
  tipe	Type.PICKUP
  state	State.OPEN
  trackingId	Nomor atau ID yang Anda gunakan untuk melacak pengiriman.
  plannedLocation	Lokasi tempat tugas harus diselesaikan, dalam hal ini lokasi pengambilan pengiriman.
  taskDuration	Perkiraan waktu, dalam detik, yang diperlukan untuk mengambil paket di lokasi pengambilan.

• Kolom opsional:

  Kolom	Nilai
  targetTimeWindow	Periode waktu saat tugas harus diselesaikan. Hal ini tidak memengaruhi perilaku pemilihan rute.
  atribut	Daftar atribut Tugas kustom. Setiap atribut harus memiliki kunci unik.

Semua kolom lain dalam entity diabaikan untuk pembuatan. Fleet Engine menampilkan pengecualian jika permintaan menyertakan deliveryVehicleId yang ditetapkan. Anda menetapkan tugas menggunakan UpdateDeliveryVehicleRequest. Untuk mengetahui 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 pengiriman dari Driver SDK atau dari lingkungan server menggunakan gRPC atau REST.

gRPC

Contoh berikut menunjukkan cara menggunakan library gRPC Java untuk membuat tugas pengiriman 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. Nomor ini tidak boleh berupa nomor pelacakan untuk pengiriman. Jika tidak memiliki ID tugas di sistem, Anda dapat membuat ID unik universal (UUID).

Header permintaan harus berisi kolom Authorization dengan nilai Bearer <token>, dengan <token> berupa token yang dikeluarkan oleh factory token Fleet Engine.

Isi permintaan harus berisi entity Task:

• Kolom wajib diisi:

  Kolom	Nilai
  tipe	Type.DELIVERY
  state	State.OPEN
  trackingId	Nomor atau ID yang Anda gunakan untuk melacak pengiriman.
  plannedLocation	Lokasi tempat tugas harus diselesaikan, dalam hal ini lokasi pengiriman untuk pengiriman ini.
  taskDuration	Waktu yang diharapkan, dalam detik, yang diperlukan untuk mengantarkan paket di lokasi pengiriman.

• Kolom opsional:

  Kolom	Nilai
  targetTimeWindow	Periode waktu saat tugas harus diselesaikan. Hal ini tidak memengaruhi perilaku pemilihan rute.
  atribut	Daftar atribut Tugas kustom. Setiap atribut harus memiliki kunci unik.

Semua kolom lain dalam entity diabaikan untuk pembuatan. Fleet Engine menampilkan pengecualian jika permintaan menyertakan deliveryKendaraanId yang ditetapkan. Anda menetapkan tugas menggunakan UpdateDeliveryVehicleRequest. Untuk mengetahui 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 pengiriman dan satu lagi untuk pengambilan di lokasi yang sama:

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> berupa 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 meneruskan aturan validasi yang sama sebagai permintaan CreateTask, dengan pengecualian bahwa kolom parent dan header bersifat opsional. Jika ditetapkan, nilai tersebut harus sama dengan kolom masing-masing di BatchCreateTasksRequest tingkat teratas. Lihat membuat tugas pengambilan pengiriman dan membuat tugas pengiriman pengiriman untuk mengetahui aturan validasi spesifik bagi setiap tugas.

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 jeda pengemudi atau mengisi bahan bakar kendaraan) dari Driver SDK, atau dari lingkungan server menggunakan gRPC atau REST. Tugas ketidaktersediaan terjadwal tidak boleh menyertakan 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 tidak memiliki ID tugas di sistem, Anda dapat membuat ID unik universal (UUID).

Header permintaan harus berisi kolom Authorization dengan nilai Bearer <token>, dengan <token> berupa token yang dikeluarkan oleh factory token Fleet Engine.

Isi permintaan harus berisi entity Task:

• Kolom wajib diisi:

  Kolom	Nilai
  tipe	Type.UNAVAILABLE
  state	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. Fleet Engine menampilkan pengecualian jika permintaan menyertakan deliveryKendaraanId yang ditetapkan. Anda menetapkan tugas menggunakan UpdateDeliveryVehicleRequest. Untuk mengetahui 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 dari Driver SDK, atau dari lingkungan server menggunakan gRPC atau REST. Tugas perhentian terjadwal mungkin tidak menyertakan ID pelacakan.

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 sistem tidak memiliki ID tugas, Anda dapat membuat ID unik universal (UUID).

Header permintaan harus berisi kolom Authorization dengan nilai Bearer <token>, dengan <token> berupa token yang dikeluarkan oleh factory token Fleet Engine.

Isi permintaan harus berisi entity Task:

• Kolom wajib diisi:

  Kolom	Nilai
  tipe	Type.SCHEDULED_STOP
  state	State.OPEN
  plannedLocation	Lokasi perhentian.
  taskDuration	Perkiraan panjang perhentian dalam hitungan detik.

• Kolom opsional:

  • Tidak ada

Semua kolom lain dalam entity diabaikan untuk pembuatan. Fleet Engine menampilkan pengecualian jika permintaan menyertakan deliveryKendaraanId yang ditetapkan. Anda menetapkan tugas menggunakan UpdateDeliveryVehicleRequest. Untuk mengetahui 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 TimeWindow selama tugas harus diselesaikan. Misalnya, jika Anda mengomunikasikan periode waktu pengiriman kepada penerima pengiriman, Anda dapat menggunakan periode waktu target tugas untuk mencatat jangka waktu ini dan membuat pemberitahuan atau menganalisis performa pasca-perjalanan menggunakan kolom ini.

Periode waktu target terdiri dari waktu mulai dan waktu berakhir, serta dapat ditetapkan pada jenis tugas apa pun. Periode waktu target tidak memengaruhi perilaku perutean.

gRPC

Contoh berikut menunjukkan cara menggunakan library gRPC Java untuk menetapkan jangka 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> berupa 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 pemilihan rute

• 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 dan data tersebut yang ditampilkan dari panggilan ke GetTaskTrackingInfo dapat dikontrol per tugas dengan menetapkan TaskTrackingViewConfig pada tugas. Lihat Tugas kendaraan aktif untuk mengetahui informasi selengkapnya. Hal ini dapat dilakukan saat membuat atau memperbarui tugas. Berikut adalah contoh pembaruan tugas dengan konfigurasi ini:

gRPC

Contoh berikut menunjukkan cara menggunakan library gRPC Java untuk menetapkan 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> berupa 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 yang terlihat 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 tersebut. Pengurutan 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 pengurutan tugas.

Untuk mengubah pengiriman dari satu kendaraan ke kendaraan lainnya, tutup tugas asli, lalu buat ulang pengiriman tersebut sebelum menugaskan kendaraan baru. Jika Anda memperbarui pengurutan tugas untuk tugas yang sudah ditetapkan ke kendaraan lain, Anda akan mendapatkan error.

Perbarui pengurutan tugas

Anda dapat memperbarui tugas pesanan yang ditetapkan ke kendaraan yang dijalankan dari Driver SDK, atau lingkungan server. Jangan gunakan kedua metode untuk menghindari kondisi race dan mempertahankan satu sumber tepercaya.

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 berada dalam urutan yang diperbarui.

Untuk mengubah pengiriman dari satu kendaraan ke kendaraan lainnya, tutup tugas asli, lalu buat ulang sebelum menugaskan kendaraan baru. Jika Anda memperbarui pengurutan tugas untuk tugas yang sudah ditetapkan ke kendaraan lain, Anda akan mendapatkan error.

Anda dapat memperbarui pengurutan tugas kapan saja.

gRPC

Contoh berikut menunjukkan cara menggunakan library gRPC Java untuk memperbarui pengurutan tugas untuk kendaraan:

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, buat 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 fleet Anda yang pengurutan tugasnya ingin Anda perbarui. ID ini adalah ID yang Anda tentukan saat membuat kendaraan.

Header permintaan harus berisi kolom Authorization dengan nilai Bearer <token>, dengan <token> berupa 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.
  tersisaKendaraanJourneySegmen[i].stop	Perhentian untuk tugas i dalam daftar.
  sisaKendaraanJourneySegments[i].stop.plannedLocation	Lokasi yang direncanakan untuk perhentian.
  sisaKendaraanJourneySegments[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:

Catatan: Perintah ini menimpa remainingVehicleJourneySegments yang telah ditetapkan di kendaraan pengiriman.

# 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 memulai navigasi. Anda dapat memberi tahu Fleet Engine dari Driver SDK 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 sedang dalam perjalanan 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 dalam perjalanan ke perhentian berikutnya dari lingkungan server, buat 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 fleet Anda yang pengurutan tugasnya ingin Anda perbarui. ID ini adalah ID yang Anda tentukan saat membuat kendaraan.

Header permintaan harus berisi kolom Authorization dengan nilai Bearer <token>, dengan <token> berupa 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:

Catatan: Perintah ini menimpa remainingVehicleJourneySegments yang sudah disetel di kendaraan pengiriman.

# 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 melakukan panggilan langsung ke Fleet Engine dengan lokasi kendaraan. Untuk semua kendaraan yang aktif, Fleet Engine mengharapkan pembaruan lokasi setidaknya sekali setiap menit dan paling sekali setiap 5 detik.

gRPC

Contoh berikut menunjukkan cara menggunakan library gRPC Java untuk mengupdate 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 REST HTTP, 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 armada Anda atau yang lokasinya ingin Anda perbarui. ID ini adalah ID yang Anda tentukan saat membuat kendaraan.

Header permintaan harus berisi kolom Authorization dengan nilai Bearer <token>, dengan <token> berupa 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 tahuFleet Engine dari Driver SDK, 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 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, buat 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 fleet Anda yang pengurutan tugasnya ingin Anda perbarui. ID ini adalah ID yang Anda tentukan saat membuat kendaraan.

Header permintaan harus berisi kolom Authorization dengan nilai Bearer <token>, dengan <token> berupa token yang dikeluarkan oleh factory token Fleet Engine.

Isi permintaan harus berisi entity DeliveryVehicle:

• Kolom wajib diisi:

  Kolom	Nilai
  remainingVehicleJourneySegments	Perhentian yang telah Anda datangi dengan statusnya ditetapkan sebagai State.ARRIVED, diikuti dengan daftar perhentian kendaraan yang tersisa dengan statusnya ditandai sebagai State.NEW.

• Kolom opsional:

  • Tidak ada

Semua kolom lain dalam entity akan diabaikan untuk update.

Contoh perintah curl:

Catatan: Perintah ini menimpa remainingVehicleJourneySegments yang telah ditetapkan di kendaraan pengiriman.

# 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 ditetapkan ke status TUTUP. Anda dapat memberi tahu Fleet Engine dari Driver SDK, 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 menyelesaikan 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()
    // 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 perhentian dari lingkungan server, buat 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 fleet Anda yang pengurutan tugasnya ingin Anda perbarui. ID ini adalah ID yang Anda tentukan saat membuat kendaraan.

Header permintaan harus berisi kolom Authorization dengan nilai Bearer <token>, dengan <token> berupa 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:

Catatan: Perintah ini menimpa remainingVehicleJourneySegments yang telah ditetapkan di kendaraan pengiriman.

    # 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 dengan memperbarui entity tugas secara langsung. Misalnya, jika tugas belum ditetapkan ke kendaraan, Anda dapat menutup tugas dengan memperbarui status 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 di tempat tugas dilakukan atau hapus dari daftar perhentian kendaraan. Untuk melakukannya, Anda dapat menetapkan daftar penghentian kendaraan yang tersisa 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. Hal ini menunjukkan bahwa tugas tidak lagi dianggap sedang berlangsung. Untuk pelacakan pengiriman, penting untuk menunjukkan hasil aktual dari suatu tugas sehingga hasil pengiriman 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 ke 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> berupa token yang dikeluarkan oleh factory token Fleet Engine.

Anda harus menyertakan entity Task dalam isi permintaan:

• Kolom wajib diisi:

  Kolom	Nilai
  state	State.CLOSED

• Kolom opsional:

  Kolom	Nilai
  taskOutcome	Results.Berhasil atau Hasil.FAILED
  taskOutcomeTime	Waktu saat tugas diselesaikan.
  taskOutcomeLocation	Lokasi tempat tugas diselesaikan. Fleet Engine menetapkan ini secara default 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, hal ini menunjukkan bahwa tugas tidak lagi dianggap sedang berlangsung. Untuk pelacakan pengiriman, penting untuk menunjukkan hasil aktual dari suatu tugas sehingga hasil pengiriman dapat ditampilkan dan ada penagihan yang tepat untuk layanan tersebut. Setelah ditetapkan, Anda tidak dapat mengubah hasil tugas. Namun, Anda dapat mengubah waktu hasil tugas dan lokasi hasil tugas setelah ditetapkan.

Tugas yang memiliki status DITUTUP dapat menetapkan hasilnya ke Berhasil atau GAGAL. Fleet Engine hanya menagih tugas pengiriman dengan status Berhasil.

Saat menandai hasil tugas, Fleet Engine akan 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. Menyetel lokasi akan mencegah Fleet Engine menyetelnya ke default lokasi kendaraan terakhir. Anda juga dapat menimpa lokasi hasil tugas yang ditetapkan Fleet Engine di lain waktu. Fleet Engine tidak pernah menimpa lokasi hasil tugas yang Anda berikan. Anda tidak dapat menetapkan lokasi hasil tugas untuk tugas yang tidak menetapkan hasil tugas. Anda dapat menetapkan hasil tugas dan lokasi hasil tugas dalam permintaan yang sama.

Contoh berikut menunjukkan cara menggunakan library gRPC Java untuk menetapkan hasil tugas ke Effective dan menetapkan lokasi tempat tugas diselesaikan:

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, buat 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> berupa 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 disetel, Fleet Engine akan menetapkannya ke lokasi kendaraan terakhir secara default.
  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 menetapkan hasil, lalu buat tugas baru dengan lokasi terencana yang diperbarui. Setelah membuat tugas baru, tetapkan tugas ke kendaraan yang sama. Untuk informasi selengkapnya, lihat menutup tugas pengiriman dan menetapkan tugas.

Menggunakan kendaraan pengumpan dan pengiriman

Jika Anda menggunakan kendaraan pengangkutan untuk mengangkut kiriman ke kendaraan pengiriman sepanjang hari, buat model transfer pengiriman sebagai tugas perhentian 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 khusus lainnya untuk pengiriman tersebut. Untuk menyimpan informasi meta lain yang dapat Anda referensikan di luar layanan Fleet Engine, gunakan tracking_id yang terkait dengan tugas sebagai kunci di tabel eksternal.

Untuk informasi selengkapnya, lihat Masa aktif tugas.

Cari kendaraan

Anda dapat mencari kendaraan dari Driver SDK, 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, buat 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> berupa 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 mendukung pencarian 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, buat 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> berupa 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 pengiriman dengan cara berikut, yang masing-masing memiliki tujuan terpisah:

• berdasarkan ID tugas: digunakan oleh pengguna seperti operator fleet yang memiliki akses ke tampilan lengkap data tugas.
• berdasarkan ID pelacakan: digunakan oleh software klien untuk memberikan informasi terbatas kepada pengguna akhir, seperti ketika sebuah paket diperkirakan akan tiba di rumah mereka.

Bagian ini membahas pencarian informasi tugas dengan ID pelacakan. Jika Anda ingin mencari tugas berdasarkan ID tugas, buka Mencari tugas.

Untuk mencari informasi menurut ID pelacakan, Anda dapat menggunakan salah satu cara berikut:

• Mencari dengan Java menggunakan gRPC
• Mencari menggunakan HTTP

Persyaratan pencarian

• Informasi pengiriman yang diberikan oleh ID pelacakan mematuhi aturan visibilitas yang dinyatakan dalam Mengontrol visibilitas lokasi yang dilacak.

• Gunakan Fleet Engine untuk mencari informasi pengiriman berdasarkan ID pelacakan. Driver SDK tidak mendukung pencarian informasi berdasarkan ID pelacakan. Untuk melakukannya dengan Fleet Engine, gunakan 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 hanya menampilkan informasi yang relevan dengan pengguna akhir tersebut, seperti pengirim atau penerima pengiriman. Semua informasi lainnya dalam respons akan disamarkan. Untuk mengetahui informasi selengkapnya tentang token, baca 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 ke 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 entity taskTrackingInfo.

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 daftar tugas.

Mencantumkan tugas meminta akses luas ke tugas. Mencantumkan tugas hanya ditujukan untuk pengguna tepercaya. Gunakan Pembaca Armada Pengiriman atau Token Autentikasi Pengguna Super Pengiriman 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 sintaksis kueri filter, lihat AIP-160. Daftar berikut menunjukkan properti tugas yang valid yang dapat Anda gunakan untuk pemfilteran:

• atribut
• delivery_vehicle_id
• state
• planned_location
• task_duration
• task_outcome
• task_outcome_location
• task_outcome_location_source
• task_outcome_time
• tracking_id
• tipe

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 operator kueri filter.

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, ukuran default yang wajar akan digunakan. Jika ukuran halaman yang diminta melebihi nilai maksimum internal, ukuran maksimum internal akan digunakan.

Daftar tugas dapat menyertakan token untuk membaca halaman hasil berikutnya. Gunakan token halaman dengan permintaan yang identik dengan permintaan sebelumnya untuk mengambil halaman tugas berikutnya. Jika token halaman yang ditampilkan kosong, tidak ada lagi tugas yang tersedia untuk diambil.

Catatan: Pemfilteran pada atribut tugas dapat menyebabkan latensi pengambilan meningkat secara signifikan, dan harus digunakan dengan hati-hati.

gRPC

Contoh berikut menunjukkan cara menggunakan library gRPC Java guna mencantumkan tugas untuk deliveryKendaraanId dan atribut tugas. Respons yang berhasil masih boleh kosong. Respons kosong menunjukkan bahwa tidak ada Tasks yang dikaitkan 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 parameter URL "filter" dengan kueri filter yang di-escape URL sebagai nilainya.

Header permintaan harus berisi kolom Authorization dengan nilai Bearer <token>, dengan <token> berupa 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 ada tugas yang 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. SDK Pengemudi tidak mendukung listingan kendaraan pengiriman.

Listingan kendaraan pengiriman meminta akses luas ke kendaraan pengiriman dan ditujukan hanya untuk pengguna tepercaya. Gunakan Pembaca Armada Pengiriman atau Token Autentikasi Pengguna Super Pengiriman saat membuat permintaan daftar kendaraan pengiriman.

Kolom berikut pada kendaraan pengiriman yang tercantum telah disamarkan karena dampaknya terhadap ukuran respons:

• CurrentRouteSegment
• RemainingVehicleJourneySegments

Anda dapat memfilter daftar kendaraan pengiriman menurut properti attributes. Misalnya, untuk membuat kueri 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 lengkap tentang sintaksis kueri filter.

Anda dapat memfilter kendaraan pengiriman yang tercantum berdasarkan lokasi menggunakan parameter permintaan viewport. Parameter permintaan viewport menentukan area pandang menggunakan dua koordinat pembatas: pasangan koordinat lintang dan bujur high (timur laut) dan low (barat daya). Permintaan akan ditolak jika memuat lintang tinggi yang secara geografis lebih rendah dari lintang rendah.

Catatan: Jika Anda tidak menentukan kueri filter atau area tampilan, responsnya akan menyertakan semua kendaraan pengiriman.

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 internal, ukuran maksimum internal akan digunakan. Ukuran halaman default dan maksimum adalah 100 kendaraan.

Daftar kendaraan pengiriman dapat menyertakan token untuk membaca halaman hasil berikutnya. Token halaman hanya ada dalam respons jika lebih banyak halaman kendaraan pengiriman tersedia untuk diambil. Untuk mengambil halaman tugas berikutnya, gunakan token halaman dengan permintaan yang identik dengan permintaan sebelumnya.

gRPC

Contoh berikut menunjukkan cara menggunakan library gRPC Java untuk mencantumkan kendaraan pengiriman di region tertentu dengan atribut tertentu. Respons yang berhasil masih boleh kosong. Jika hal itu terjadi, berarti tidak ada kendaraan dengan atribut yang ditentukan yang 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 parameter URL "filter" dengan kueri filter yang di-escape URL sebagai nilainya.

Header permintaan harus berisi kolom Authorization dengan nilai Bearer <token>, dengan <token> berupa 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. Jika hal itu terjadi, berarti tidak ditemukan kendaraan pengiriman yang memenuhi area tampilan 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 pengiriman

Anda memiliki dua opsi untuk menggunakan Fleet Engine Deliveries API guna mengaktifkan pelacakan pengiriman:

• Lebih Disukai: Gunakan library Pelacakan Pengiriman JavaScript. Library ini memungkinkan Anda memvisualisasi lokasi kendaraan dan lokasi minat yang dilacak di Fleet Engine. Library ini 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 pengiriman beranimasi dan dapat disesuaikan dari web atau aplikasi seluler Anda.

• Implementasikan pelacakan pengiriman Anda sendiri di atas Fleet Engine Deliveries API.

Kuncinya adalah mencari tugas pengiriman berdasarkan ID pelacakan.

Jika Anda menggunakan Peran Konsumen Pengiriman, semua panggilan API Pengiriman Fleet Engine Deliveries hanya menampilkan informasi yang relevan untuk pengirim atau penerima. Semua informasi lainnya dalam respons akan disamarkan. Anda bertanggung jawab untuk mengautentikasi pengguna akhir. Selain itu, informasi lokasi difilter berdasarkan tugas yang sudah dilakukan. Selama tugas ketidaktersediaan, tidak ada informasi lokasi yang dibagikan kepada pengguna akhir.

Logging

Anda dapat menetapkan Fleet Engine untuk mengirim log RPC ke Cloud Logging. Untuk mengetahui informasi lebih lanjut, lihat Logging.

Peran dan Token Otorisasi

Seperti yang dijelaskan dalam Mengelola siklus proses kendaraan dan tugas serta catatan otorisasi untuk setiap kasus penggunaan, melakukan panggilan ke Fleet Engine memerlukan autentikasi dengan Token Web JSON yang telah ditandatangani menggunakan kredensial akun layanan. Akun layanan yang digunakan untuk menerbitkan token tersebut mungkin memiliki satu atau beberapa peran, dengan setiap peran memberikan serangkaian izin yang berbeda.

Untuk mengetahui informasi lebih lanjut, 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, jika perlu, tanpa mengandalkan Fleet Engine.

Status hilang di Fleet Engine

Saat menangani Fleet Engine, terapkan klien agar sistem memulihkan diri jika terjadi kegagalan. Misalnya, saat Fleet Engine mencoba mengupdate kendaraan, Fleet Engine mungkin merespons dengan error yang menunjukkan bahwa kendaraan tersebut tidak ada. Klien kemudian harus membuat ulang kendaraan di status baru. Meskipun masalah ini jarang terjadi, pastikan sistem Anda cukup tangguh untuk menangani masalah ini.

Dalam skenario kegagalan dahsyat Fleet Engine, Anda mungkin perlu membuat ulang sebagian besar atau semua kendaraan dan tugas. Jika rasio pembuatan menjadi terlalu tinggi, beberapa permintaan dapat gagal lagi karena masalah kuota karena pemeriksaan kuota dilakukan untuk menghindari serangan denial of service (DOS). Dalam hal ini, perlambat kecepatan pembuatan ulang menggunakan strategi backoff untuk percobaan ulang.

Status hilang di aplikasi driver

Jika aplikasi driver mengalami error, aplikasi harus membuat ulang status saat ini dalam Driver SDK. Aplikasi harus mencoba membuat ulang tugas untuk memastikan tugas tersebut ada dan memulihkan statusnya saat ini. Aplikasi juga harus membuat ulang dan secara eksplisit menetapkan daftar perhentian untuk Driver SDK.

Catatan: Pemulihan ini harus dilakukan secara mandiri tanpa mengandalkan informasi dari Fleet Engine, selain error yang menunjukkan apakah dan kapan entity sudah ada dalam database. Jika entitas sudah ada, error tersebut dapat diserap dan entitas tersebut dapat diperbarui menggunakan ID-nya.

FAQ

Bagaimana jika pengemudi berhenti untuk melakukan tugas secara tidak berurutan?

Dalam hal ini, perbarui urutan tugas terlebih dahulu, lalu lanjutkan seperti biasa, menandai kedatangan di perhentian, penyelesaian tugas, dan detail lainnya. Jika tidak dilakukan, sistem mungkin menjadi tidak konsisten, PWT mungkin menjadi salah, dan error tak terduga dapat dilaporkan.