Mulai menggunakan Fleet Engine untuk Pelacakan Pengiriman

Buat model aktivitas fleet Anda untuk pengiriman kilometer pertama dan terakhir dengan Feet Engine Deliveries API. Anda dapat menggunakan API ini dengan Driver SDK untuk Android dan iOS, atau secara langsung menggunakan panggilan HTTP REST atau gRPC.

Penyiapan awal

Anda mengonfigurasi Fleet Engine Deliveries API di Konsol Google Cloud.

• Untuk mengetahui informasi tentang langkah-langkah yang perlu dilakukan di 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 penyiapan tersebut, Anda dapat memastikan bahwa Anda telah mengatasi masalah otorisasi umum yang dapat muncul saat menyiapkan project. Ada dua cara untuk memverifikasi penyiapan Anda:

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

• Uji penyiapan Anda dengan Contoh Skrip Auth Fleet Engine.

Library Klien

Untuk 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 terbiasa dengan gRPC.

Struktur data

Fleet Engine Deliveries API menggunakan dua struktur data untuk membuat model pengambilan dan pengiriman pengiriman:

• Kendaraan pengantar yang digunakan untuk mengangkut kiriman.
• Tugas pengambilan dan pengantaran pesanan.

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

Kendaraan pengiriman

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

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

Tugas

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

• Untuk pengambilan dan pengiriman, tetapkan Tugas pengiriman.
• Untuk saat pengemudi tidak tersedia, seperti waktu istirahat yang diperlukan, tetapkan Tugas tidak tersedia.
• Untuk tugas selain mengemudi di drop box atau lokasi pelanggan, tetapkan Tugas perhentian terjadwal.

Setiap tugas yang Anda tetapkan harus memiliki ID tugas yang 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 penjadwalan untuk membuat estimasi. Untuk informasi selengkapnya tentang ID tugas, lihat Panduan ID Tugas.

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

Tugas pengiriman

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

• Lokasi pengambilan atau pengiriman.
• Nomor pelacakan atau ID.
• Waktu tunggu untuk memperhitungkan waktu tambahan untuk menyelesaikan tugas, mencari tempat parkir, atau berjalan ke lokasi penyerahan.
• ID tugas unik. Lihat Pedoman Task ID.

Untuk informasi selengkapnya, lihat topik berikut:

Android

• Membuat tugas pengambilan pengiriman
• Membuat tugas pengiriman pengiriman

iOS

• GMTD DeliveryTaskManager.
• GMTSTaskType

Tugas tidak tersedia

Tugas ketidaktersediaan mencakup jangka waktu saat kendaraan tidak tersedia untuk pengambilan atau pengiriman, seperti waktu istirahat untuk mengisi bahan bakar kendaraan atau waktu istirahat pengemudi.

Buat tugas tidak tersedia dengan informasi berikut:

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

Catatan: Selama tugas yang tidak tersedia, tidak ada informasi lokasi yang dibagikan kepada pengguna akhir Library Pelacakan Pengiriman. Namun, alat ini tersedia untuk pengelola fleet yang menggunakan Fleet Tracking Library.

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 dibuat oleh kendaraan pengiriman. Misalnya, buat tugas perhentian terjadwal untuk perhentian pengambilan terjadwal hari di lokasi tertentu, terlepas dari pengiriman atau pengambilan lain di lokasi yang sama. Anda juga dapat membuat tugas perhentian terjadwal untuk koleksi dari drop box atau untuk membuat model transfer feeder-kendaraan atau perhentian di pusat layanan dan titik layanan.

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.
• Menggunakan string Unicode yang valid.
• Gunakan maksimal 64 karakter.
• Jangan sertakan karakter ASCII berikut: "/", ":", "\", "?", atau "#".
• Normalisasikan menurut Unicode Normalization Form C.

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

Berikut ini adalah beberapa contoh ID Tugas yang baik:

• 566c33d9-2a31-4b6a-9cd4-80ba1a0c643b
• e4708eabcfa39bf2767c9546c9273f747b4626e8cc44e9630d50f6d129013d38
• NTA1YTliYWNkYmViMTI0ZmMzMWFmOWY2NzNkM2Jk

Tabel berikut menampilkan contoh ID Tugas yang tidak didukung:

ID Tugas yang Tidak Didukung	Alasan
8/31/2019-20:48-46.70746,-130.10807,-85.17909,61.33680	Melanggar persyaratan karakter dan PII: koma, titik, titik dua, dan garis miring.
JohnDoe-577b484da26f-Cupertino-SantaCruz	Melanggar persyaratan PII.
4R0oXLToF"112 Summer Dr. East Hartford, CT06118"577b484da26f8a	Melanggar persyaratan karakter dan PII: spasi kosong, koma, dan tanda kutip. Lebih dari 64 karakter.

Referensi lainnya

Untuk melihat kolom tertentu yang ada di setiap struktur data, lihat dokumentasi Referensi API untuk DeliveryVehicle (gRPC, REST) dan Task (gRPC, REST).

Masa pakai kendaraan

Objek DeliveryVehicle mewakili kendaraan pengiriman mil pertama atau terakhir. Anda membuat objek DeliveryVehicle menggunakan:

• Project ID untuk 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 menggunakan ulang ID kendaraan kecuali jika tidak ada tugas aktif untuk kendaraan asli.

Fleet Engine secara 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, kendaraan masih tersedia untuk diupdate.

Catatan: Jika 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, defaultnya adalah AUTO.

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

Atribut kendaraan

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

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

Keberlangsungan tugas

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

Objek Task memiliki kolom status untuk melacak perkembangannya selama siklus prosesnya. Nilai akan berpindah 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 untuk tugas tersebut.

Panduan tugas

Anda hanya dapat menetapkan tugas ke kendaraan saat dalam status BUKA.

Anda membatalkan tugas dengan menghapusnya dari daftar perhentian kendaraan, yang menetapkan status tugas ke DITUTUP secara otomatis.

Saat kendaraan tugas menyelesaikan perhentian kendaraan tugas:

1. Perbarui kolom hasil tugas menjadi SUCCEEDED 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.

   Library Pelacakan Pengiriman JavaScript kemudian menunjukkan hasil tugas dan status tugas ditetapkan ke DITUTUP secara otomatis. Untuk informasi lebih lanjut, 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, Fleet Engine akan menampilkan error.

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

Atribut tugas

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

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

Kelola 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 terkaitnya.

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

Misalnya, Anda memiliki skenario berikut:

• Seorang 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 kedekatan paket mereka.
• Setelah pengemudi menyelesaikan pengiriman, dia mengklik tombol "Pengiriman terkirim" di aplikasi pengemudi.
• Tindakan "Pengiriman terkirim" mengirimkan informasi ke sistem backend Anda, yang melakukan langkah validasi dan verifikasi bisnis yang diperlukan.
• Sistem Anda mengonfirmasi tugas sebagai resolve dan mengupdate Fleet Engine menggunakan Deliveries API.

Diagram berikut mengilustrasikan proses ini di level umum. Laporan ini juga menunjukkan hubungan standar antara sistem Anda, klien, dan Fleet Engine.

Kelola token klien

Update 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. Sediakan token cakupan terbatas kepada aplikasi driver. Cakupan ini hanya memungkinkannya memperbarui lokasi perangkat di Fleet Engine.

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

Peran akun layanan lainnya

Jika Anda ingin mengizinkan aplikasi driver untuk melakukan update Fleet Engine langsung selain yang dibatasi pada peran Pengemudi Tidak Tepercaya, seperti untuk update tugas tertentu, Anda dapat menggunakan peran Pengemudi Tepercaya. Untuk mengetahui informasi tentang model yang menggunakan peran Driver Tepercaya, 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 bagi pengemudi kilometer pertama atau terakhir di perusahaan pengiriman dan logistik. Detail informasi perusahaan Anda mungkin berbeda-beda, tetapi Anda dapat melihat bagaimana Anda membuat model untuk hari kerja.

Waktu	Aktivitas	Pemodelan
Dalam waktu 24 jam sejak awal hari	Petugas operator menetapkan pengiriman ke kendaraan atau rute pengiriman.	Anda dapat membuat tugas untuk pengiriman, pengambilan, jeda pengiriman, dan lainnya di Fleet Engine terlebih dahulu. Misalnya, Anda dapat membuat tugas pengambilan di pengiriman, tugas pengiriman pengiriman, ketidaktersediaan terjadwal, atau perhentian terjadwal. Tetapkan tugas ke kendaraan setelah kumpulan paket pengiriman dan urutan pengirimannya telah 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 melakukan commit ke jumlah tugas berikutnya yang harus diselesaikan.	Berikan semua tugas atau subkumpulan tugas ke kendaraan dengan menetapkan urutan penyelesaiannya.
	Pengemudi mengirimkan kiriman.	Setelah tiba di perhentian pengiriman, lakukan tindakan terkait kendaraan yang tiba di perhentian. Setelah barang dikirimkan, 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 yang terkait dengan kendaraan menyelesaikan perhentian dan kendaraan beralih 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 urutan tugas.
	Pengemudi menerima notifikasi permintaan penjemputan.	Setelah menyetujui permintaan pengambilan, buat tugas pengambilan untuk pengiriman. Kemudian perbarui urutan eksekusi tugas dengan menetapkan tugas ke kendaraan dan memperbarui urutan tugas.
Tengah hari	Pengemudi beristirahat makan siang.	Jika lokasi terkait dengan tugas tidak tersedia, perlakukan seperti tugas lainnya. Melakukan tindakan terkait kendaraan yang tiba di perhentian, kendaraan menyelesaikan perhentian dan kendaraan beralih ke perhentian berikutnya. Jika tidak, Anda tidak perlu melakukan tindakan lebih lanjut hingga akhir jeda. Hapus tugas dengan mengonfirmasi tugas berikutnya dan tugas lainnya, serta memperbarui pengurutan tugas.
	Pengemudi mengambil kiriman.	Ini dimodelkan seperti perhentian pengiriman. Melakukan tindakan terkait kendaraan yang tiba di perhentian dan menutup tugas, serta secara opsional, status pengiriman 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 beralih ke perhentian berikutnya. Catatan: Untuk memastikan penagihan yang benar, semua pengambilan harus memiliki tugas pengiriman yang sesuai. Jika pengambilan akan dikirimkan ke lokasi lain di rute yang sama oleh pengemudi pada hari tersebut, sebaiknya buat model tugas pengiriman tersebut seperti tugas pengiriman lainnya di rute tersebut. Jika pengemudi mengembalikan barangnya ke depot, sebaiknya buat tugas pengiriman di tujuan depot.
	Pengemudi membuat perhentian terjadwal untuk mengambil kiriman dari drop box.	Ini modelnya sama seperti titik penjemputan lainnya. Melakukan tindakan 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 menyelesaikan perhentian dan kendaraan beralih ke perhentian berikutnya.
	Pengemudi menerima notifikasi bahwa pengiriman dialihkan ke lokasi alternatif.	Tetapkan status tugas pengiriman asli ke SELESAI dan buat tugas pengiriman baru untuk lokasi pengiriman yang baru. Untuk informasi lebih lanjut, lihat Mengubah rute pengiriman.
	Pengemudi mencoba mengirimkan paket, tetapi tidak dapat melakukannya.	Tindakan ini dimodelkan mirip dengan penghentian pengiriman yang berhasil, yang menandai tugas pengiriman sebagai selesai. Melakukan tindakan terkait kendaraan yang tiba di perhentian. Setelah gagal mengirimkan pengiriman, tutup tugas dan, secara opsional, 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 beralih ke perhentian berikutnya.
	Pengemudi diberi tahu untuk menunda (tidak mengirimkan) pengiriman.	Setelah notifikasi diterima dan dikonfirmasi, tetapkan status tugas ke SELESAI.
	Pengemudi diberi tahu untuk mengirimkan pengiriman tertentu berikutnya, mengubah pesanan pengiriman yang dilakukan.	Memperbarui urutan tugas.
	Pengemudi memilih untuk mengirimkan pesanan secara tidak berurutan.	Perbarui pengurutan tugas, lalu lanjutkan seperti biasa.
	Pengemudi mengirimkan beberapa pengiriman ke satu lokasi.	Hal ini dimodelkan mirip dengan satu perhentian pengiriman pengiriman. Setelah tiba di perhentian, lakukan tindakan terkait kendaraan yang tiba di perhentian. Setelah mengirim 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 menyelesaikan perhentian dan kendaraan beralih ke perhentian berikutnya.
Akhir hari	Pengemudi kembali ke depot.	Jika pengemudi kembali ke depot dengan pengiriman diambil selama rutenya, Anda juga harus membuat dan menutup setiap paket sebagai tugas pengiriman untuk memastikan penagihan yang benar. Anda dapat melakukannya dengan memodelkan depot seperti perhentian pengiriman lainnya. Jika depot tidak digunakan sebagai perhentian pengiriman, Anda masih dapat secara opsional membuat model depot sebagai perhentian terjadwal. Dengan membuat model perhentian, pengemudi Anda dapat melihat rute kembali ke depot dan memberikan visibilitas tentang perkiraan waktu kedatangan mereka.

Cara kerja pembaruan lokasi

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

1. Gunakan Driver SDK - Android, iOS -- opsi paling sederhana.
2. Gunakan kode kustom -- berguna jika lokasi disusun melalui backend Anda, atau jika Anda menggunakan perangkat selain Android atau iOS.

Terlepas dari cara Anda memberikan pembaruan lokasi kendaraan, backend Anda bertanggung jawab untuk mengupdate Fleet Engine saat kendaraan pengiriman dalam perjalanan ke perhentian (termasuk depot) dan saat tiba di perhentian. Fleet Engine tidak mendeteksi peristiwa ini secara otomatis.

Tempat perhentian dan lokasi pengiriman kendaraan

Perhentian kendaraan adalah tempat kendaraan pengiriman menyelesaikan tugas pengiriman atau beberapa tugas lainnya. Lokasi ini dapat berupa titik akses seperti dok pemuatan atau lokasi yang langsung berada di jalan.

Lokasi pengiriman adalah lokasi pengiriman atau pengambilan pengiriman. Pergi ke dan dari lokasi pengiriman mungkin memerlukan beberapa jalan kaki dari kendaraan berhenti.

Misalnya, saat pengemudi mengirimkan kiriman ke toko di mal, kendaraan pengantaran berhenti di tempat parkir mal dekat pintu masuk terdekat ke toko. Ini adalah perhentian kendaraan. Pengemudi lalu berjalan dari perhentian kendaraan ke lokasi dalam mal tempat toko berada. Ini adalah lokasi pengiriman.

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

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 jumlah perhentian kendaraan yang terbatas sebelum tujuannya. Memiliki banyak perhentian kendaraan yang diselesaikan dalam waktu singkat tidak memberi banyak waktu bagi pengguna untuk melacak progres pengiriman mereka.

Menggunakan SDK seluler

Sebelum melakukan panggilan ke Driver SDK, pastikan Anda melakukan inisialisasi.

Melakukan inisialisasi Delivery Driver API

Sebelum menginisialisasi Delivery Driver API di Driver SDK, pastikan untuk menginisialisasi Navigation SDK. Kemudian, inisialisasi Delivery Driver API seperti yang ditunjukkan dalam 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 akan bersifat buram bagi Fleet Engine. Hindari penggunaan ID yang bertambah secara 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 nilai apa pun yang ditentukan untuk kolom Name akan diabaikan sesuai panduan API untuk ID yang ditentukan pengguna. Anda harus menggunakan kolom DeliveryVehicleId untuk menetapkan ID kendaraan.

Saat membuat DeliveryVehicle, Anda dapat menentukan kolom berikut 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 diperbarui dengan panggilan ke UpdateDeliveryVehicle.

Untuk membuat kendaraan tanpa menetapkan 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, lakukan panggilan REST HTTP ke CreateDeliveryVehicle:

POST https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles?deliveryVehicleId=<id>

<id> adalah ID unik untuk kendaraan pengiriman di armada Anda.

Header permintaan harus berisi kolom Authorization dengan nilai Bearer <token>, dengan <token> adalah token yang diterbitkan 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 per 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 diperbarui menggunakan panggilan ke UpdateDeliveryVehicle.

Untuk membuat kendaraan tanpa menetapkan 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, lakukan panggilan REST HTTP ke CreateTask:

`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`

<id> adalah ID unik untuk tugas tersebut. 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> adalah token yang diterbitkan oleh factory token Fleet Engine.

Isi permintaan harus berisi entitas 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 akan diselesaikan, dalam hal ini lokasi pengambilan pengiriman.
  taskDuration	Perkiraan waktu, dalam detik, yang diperlukan untuk mengambil pengiriman di lokasi penjemputan.

• Kolom opsional:

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

Semua kolom lain dalam entity akan 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, lakukan panggilan REST HTTP ke CreateTask:

`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`

<id> adalah ID unik untuk tugas tersebut. 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> adalah token yang diterbitkan oleh factory token Fleet Engine.

Isi permintaan harus berisi entitas 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 akan diselesaikan, dalam hal ini lokasi pengiriman untuk pengiriman ini.
  taskDuration	Perkiraan waktu, dalam detik, yang diperlukan untuk menurunkan pengiriman di lokasi pengiriman.

• Kolom opsional:

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

Semua kolom lain dalam entity akan 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": "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

Membuat Tugas Batch

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 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, lakukan panggilan REST HTTP ke BatchCreateTasks:

POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks:batchCreate

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

Isi permintaan harus berisi entitas BatchCreateTasksRequest:

• Kolom wajib diisi:

  Kolom	Nilai
  permintaan	Array<CreateTasksRequest>

• Kolom opsional:

  Kolom	Nilai
  header	`DeliveryRequestHeader`

Setiap elemen CreateTasksRequest dalam requests harus meneruskan aturan validasi yang sama dengan permintaan CreateTask, dengan pengecualian bahwa kolom parent dan header bersifat opsional. Jika ditetapkan, kolom tersebut harus sama persis dengan kolomnya masing-masing di BatchCreateTasksRequest level teratas. Lihat membuat tugas pengambilan pengiriman dan membuat tugas pengiriman untuk mengetahui aturan validasi spesifik untuk setiap tugas.

Untuk mengetahui 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 tidak tersedia (misalnya, untuk jeda pengemudi atau pengisian bahan bakar kendaraan) dari Driver SDK, atau dari lingkungan server menggunakan gRPC atau REST. Tugas tidak tersedia terjadwal tidak boleh menyertakan ID pelacakan. Anda dapat memberikan lokasi.

gRPC

Contoh berikut menunjukkan cara menggunakan library gRPC Java untuk membuat tugas tidak tersedia:

    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 yang tidak tersedia dari lingkungan server, lakukan panggilan REST HTTP ke CreateTask:

`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`

<id> adalah ID unik untuk tugas tersebut. 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> adalah token yang diterbitkan oleh factory token Fleet Engine.

Isi permintaan harus berisi entitas Task:

• Kolom wajib diisi:

  Kolom	Nilai
  tipe	Type.UNAVAILABLE
  state	State.OPEN
  taskDuration	Durasi jeda dalam hitungan detik.

• Kolom opsional:

  Kolom	Nilai
  plannedLocation	Lokasi jeda jika harus diambil di lokasi tertentu.

Semua kolom lain dalam entity akan 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, 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 penghentian 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 penghentian 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 perhentian terjadwal dari lingkungan server, lakukan panggilan REST HTTP ke CreateTask:

`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`

<id> adalah ID unik untuk tugas tersebut. Jika tidak memiliki task ID di sistem, Anda dapat membuat ID unik universal (UUID).

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

Isi permintaan harus berisi entitas Task:

• Kolom wajib diisi:

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

• Kolom opsional:

  • Tidak ada

Semua kolom lain dalam entity akan 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, 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 saat tugas harus diselesaikan. Misalnya, jika Anda memberitahukan periode waktu pengiriman kepada penerima pengiriman, Anda dapat menggunakan periode waktu target tugas untuk mencatat periode waktu ini dan membuat pemberitahuan atau menganalisis performa pascaperjalanan 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 pemilihan rute.

gRPC

Contoh berikut menunjukkan cara menggunakan library gRPC Java untuk menetapkan periode waktu tugas:

    static final String PROJECT_ID = "my-delivery-co-gcp-project";
    static final String TASK_ID = "task-8241890";

    DeliveryServiceBlockingStub deliveryService =
      DeliveryServiceGrpc.newBlockingStub(channel);

    // Task settings
    String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
    Task task = Task.newBuilder()
      .setName(taskName)
      .setTargetTimeWindow(
        TimeWindow.newBuilder()
          .setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
          .setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
      .build();

    // Task request
    UpdateTaskRequest updateTaskRequest =
      UpdateTaskRequest.newBuilder()  // No need for the header
          .setTask(task)
          .setUpdateMask(FieldMask.newBuilder().addPaths("targetTimeWindow"))
          .build();

    try {
      Task updatedTask = deliveryService.updateTask(updateTaskRequest);
    } catch (StatusRuntimeException e) {
      Status s = e.getStatus();
      switch (s.getCode()) {
         case NOT_FOUND:
           break;
         case PERMISSION_DENIED:
           break;
      }
      return;
    }

REST

Untuk menetapkan 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 tersebut.

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

Isi permintaan harus berisi entitas 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 pembaruan.

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

Menetapkan konfigurasi visibilitas pelacakan tugas

Visibilitas data di library Pelacakan Pengiriman 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 tersebut.

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

Isi permintaan harus berisi entitas Task:

• Kolom wajib diisi:

  Kolom	Nilai
  taskTrackingViewConfig	Konfigurasi untuk pelacakan tugas yang menentukan elemen data mana yang terlihat oleh pengguna akhir dalam keadaan apa.

• Kolom opsional:

  • Tidak ada

Semua kolom lain dalam entity akan diabaikan untuk pembaruan.

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 urutan tugas untuk kendaraan tersebut. Pengurutan tugas untuk kendaraan ditentukan oleh daftar pemberhentian kendaraan untuk kendaraan pengiriman, dan Anda dapat menetapkan satu atau beberapa tugas untuk setiap perhentian kendaraan. Untuk mengetahui detailnya, lihat Memperbarui urutan tugas.

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

Memperbarui pengurutan tugas

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

Saat Anda memperbarui urutan tugas untuk kendaraan, sistem ini juga akan melakukan hal berikut:

• Menetapkan tugas yang baru untuk kendaraan.
• Menutup tugas apa pun yang sebelumnya ditetapkan ke kendaraan, tetapi tidak dalam urutan yang diperbarui.

Untuk mengubah pengiriman dari satu kendaraan ke kendaraan lain, tutup tugas asli lalu buat kembali sebelum menugaskan kendaraan baru. Jika Anda memperbarui urutan tugas untuk tugas yang sudah ditetapkan ke kendaraan yang berbeda, 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

Untuk memperbarui urutan tugas kendaraan dari lingkungan server, lakukan panggilan REST HTTP ke UpdateDeliveryVehicle:

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`

<id> adalah ID unik untuk kendaraan pengiriman di fleet Anda yang ingin Anda perbarui urutan tugasnya. Ini adalah ID yang Anda tentukan saat membuat kendaraan.

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

Isi permintaan harus berisi entitas DeliveryVehicle:

• Kolom wajib diisi:

  Kolom	Nilai
  remainingVehicleJourneySegments	Daftar segmen perjalanan untuk tugas sesuai urutan eksekusinya. Tugas pertama dalam daftar dijalankan terlebih dahulu.
  segmenJourney yang tersisa[i].stop	Perhentian untuk tugas i dalam daftar.
  SegmenJourney yang tersisa[i].stop.plannedLocation	Lokasi perhentian yang direncanakan.
  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 pembaruan.

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 proses ke perhentian berikutnya dari lingkungan server, lakukan panggilan REST HTTP ke UpdateDeliveryVehicle:

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`

<id> adalah ID unik untuk kendaraan pengiriman di fleet Anda yang ingin Anda perbarui urutan tugasnya. Ini adalah ID yang Anda tentukan saat membuat kendaraan.

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

Isi permintaan harus berisi entitas DeliveryVehicle:

• Kolom wajib diisi:

  Kolom	Nilai
  remainingVehicleJourneySegments	Daftar perhentian kendaraan yang tersisa dengan statusnya 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 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": "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 kendaraan aktif, Fleet Engine mengharapkan pembaruan lokasi minimal sekali setiap menit dan paling banyak sekali setiap 5 detik.

gRPC

Contoh berikut menunjukkan cara menggunakan library gRPC Java untuk memperbarui lokasi kendaraan di Fleet Engine:

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle myDeliveryVehicle = DeliveryVehicle.newBuilder()
    .setLastLocation(DeliveryVehicleLocation.newBuilder()
        .setSupplementalLocation(LatLng.newBuilder()
            .setLatitude(37.3382)
            .setLongitude(121.8863))
        .setSupplementalLocationTime(now())
        .setSupplementalLocationSensor(DeliveryVehicleLocationSensor.CUSTOMER_SUPPLIED_LOCATION)
        .setSupplementalLocationAccuracy(DoubleValue.of(15.0)))  // Optional
    .build();

// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
  UpdateDeliveryVehicleRequest.newBuilder()  // No need for the header
      .setName(vehicleName)
      .setDeliveryVehicle(myDeliveryVehicle)
      .setUpdateMask(FieldMask.newBuilder()
          .addPaths("last_location"))
      .build();

try {
  DeliveryVehicle updatedDeliveryVehicle =
      deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Untuk memperbarui lokasi kendaraan di Fleet Engine menggunakan 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 fleet Anda atau yang ingin Anda perbarui lokasinya. Ini adalah ID yang Anda tentukan saat membuat kendaraan.

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

Isi permintaan harus berisi entitas DeliveryVehicle:

• Kolom wajib diisi:

  Kolom	Nilai
  lastLocation.supplementalLocation	Lokasi kendaraan.
  lastLocation.supplementalLocationTime	Stempel waktu terakhir yang diketahui saat kendaraan berada di lokasi ini.
  lastLocation.supplementalLocationSensor	Harus diisi dengan CUSTOMER_supPLIED_LOCATION.

• Kolom opsional:

  Kolom	Nilai
  lastLocation.supplementalLocationAccuracy	Akurasi lokasi yang diberikan, dalam meter.

Contoh perintah curl:

# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "lastLocation": {
    "supplementalLocation": {"latitude": 12.1, "longitude": 14.5},
    "supplementalLocationTime": "$(date -u --iso-8601=seconds)",
    "supplementalLocationSensor": "CUSTOMER_SUPPLIED_LOCATION",
    "supplementalLocationAccuracy": 15
  }
}
EOM

Kendaraan tiba di perhentian

Fleet Engine harus diberi tahu saat kendaraan tiba di perhentian. Anda dapat memberi tahu Fleet Engine 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, lakukan panggilan REST HTTP ke UpdateDeliveryVehicle:

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`

<id> adalah ID unik untuk kendaraan pengiriman di fleet Anda yang ingin Anda perbarui urutan tugasnya. Ini adalah ID yang Anda tentukan saat membuat kendaraan.

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

Isi permintaan harus berisi entitas DeliveryVehicle:

• Kolom wajib diisi:

  Kolom	Nilai
  remainingVehicleJourneySegments	Perhentian yang telah Anda tiba dengan status ditetapkan sebagai State.ARRIVED, diikuti dengan daftar perhentian kendaraan lainnya dengan status yang 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 menyelesaikan perhentian. Hal ini menyebabkan semua tugas yang terkait dengan perhentian ditetapkan ke status TERTUTUP. 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 selesai berhenti.

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
    // This stop has been completed and is commented out to indicate it
    // should be removed from the list of vehicle journey segments.
    // .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()
    //    .setStop(VehicleStop.newBuilder()
    //        .setPlannedLocation(LocationInfo.newBuilder()
    //            .setPoint(LatLng.newBuilder()
    //                .setLatitude(37.7749)
    //                .setLongitude(122.4194)))
    //        .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
    //        .setState(VehicleStop.State.ARRIVED)))
    // All other remaining stops marked as NEW.
    // The next stop could be marked as ENROUTE if the vehicle has begun
    // its journey to the next stop.
    .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // Next stop
       .setStop(VehicleStop.newBuilder()
           .setPlannedLocation(LocationInfo.newBuilder()
               .setPoint(LatLng.newBuilder()
                   .setLatitude(37.3382)
                   .setLongitude(121.8863)))
           .addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
           .setState(VehicleStop.State.NEW)))
    .build();

// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
  UpdateDeliveryVehicleRequest.newBuilder()  // no need for the header
      .setName(vehicleName)
      .setDeliveryVehicle(deliveryVehicle)
      .setUpdateMask(FieldMask.newBuilder()
          .addPaths("remaining_vehicle_journey_segments"))
      .build();

try {
  DeliveryVehicle updatedDeliveryVehicle =
      deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Untuk memberi tahu Fleet Engine tentang penyelesaian penghentian dari lingkungan server, lakukan panggilan REST HTTP ke UpdateDeliveryVehicle:

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remaining_vehicle_journey_segments`

<id> adalah ID unik untuk kendaraan pengiriman di fleet Anda yang ingin Anda perbarui urutan tugasnya. Ini adalah ID yang Anda tentukan saat membuat kendaraan.

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

Isi permintaan harus berisi entitas DeliveryVehicle:

• Kolom wajib diisi:

  Kolom	Nilai
  remaining_vehicle_journey_segments	Perhentian yang telah Anda selesaikan tidak akan lagi ada dalam daftar perhentian kendaraan yang tersisa.

• Kolom opsional:

  • Tidak ada

Semua kolom lain dalam entity akan diabaikan untuk pembaruan.

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 mengubah 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 tempat tugas dilakukan atau hapus dari daftar perhentian kendaraan. Untuk melakukannya, Anda dapat menetapkan daftar pemberhentian kendaraan yang tersisa sama seperti saat memperbarui urutan tugas untuk kendaraan.

Jika tugas belum ditetapkan untuk kendaraan dan harus ditutup, perbarui tugas ke status DITUTUP. Namun, Anda tidak boleh membuka kembali tugas DITUTUP.

Penutupan tugas tidak menunjukkan keberhasilan atau kegagalan. Hal ini menunjukkan bahwa tugas tidak lagi dianggap sedang berlangsung. Untuk pelacakan pengiriman, penting untuk menunjukkan hasil sebenarnya dari 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, lakukan panggilan REST HTTP ke UpdateTask:

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=state`

<id> adalah ID unik untuk tugas tersebut.

Header permintaan Anda harus berisi kolom Authorization dengan nilai Bearer <token>, dengan <token> adalah token yang diterbitkan 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	Hasil.Failed atau Results.FAILED
  taskOutcomeTime	Waktu saat tugas selesai.
  taskOutcomeLocation	Lokasi tempat tugas diselesaikan. Fleet Engine menetapkan ini ke lokasi kendaraan terakhir secara default, 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 sebenarnya dari tugas sehingga hasil pengiriman dapat ditampilkan dan ada penagihan yang tepat untuk layanan. Setelah ditetapkan, Anda tidak dapat mengubah hasil tugas. Namun, Anda dapat mengubah waktu hasil tugas dan lokasi hasil tugas setelah ditetapkan.

Tugas yang berada dalam status TERTUTUP dapat memiliki hasilnya yang ditetapkan 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 yang terakhir diketahui. Anda dapat mengganti perilaku ini.

gRPC

Anda memiliki opsi untuk menetapkan lokasi hasil tugas saat menetapkan hasilnya. Jika lokasi ditetapkan, Fleet Engine tidak akan 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 memiliki penetapan 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 functions dan menetapkan lokasi tugas tersebut 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 tersebut.

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

Isi permintaan harus berisi entitas Task:

• Kolom wajib diisi:

  Kolom	Nilai
  taskOutcome	Hasil.Failed atau Results.FAILED

• Kolom opsional:

  Kolom	Nilai
  taskOutcomeLocation	Lokasi tempat tugas diselesaikan. Jika tidak disetel, Fleet Engine akan menyetelnya ke lokasi kendaraan terakhir.
  taskOutcomeTime	Stempel waktu saat tugas selesai.

Semua kolom lain dalam entity akan diabaikan untuk pembaruan.

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 mengetahui informasi selengkapnya, lihat menutup tugas pengiriman dan menetapkan tugas.

Gunakan kendaraan pengumpan dan pengiriman

Jika Anda menggunakan kendaraan pemasok untuk mengangkut pengiriman 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 lain khusus untuk pengiriman. Untuk menyimpan informasi meta lain yang dapat Anda referensikan di luar layanan Fleet Engine, gunakan tracking_id yang terkait dengan tugas sebagai kunci dalam tabel eksternal.

Untuk informasi selengkapnya, lihat Masa aktif tugas.

Cari kendaraan

Anda 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, lakukan panggilan REST HTTP ke GetVehicle:

`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<vehicleId>`

<id> adalah ID unik untuk tugas tersebut.

<vehicleId> adalah ID kendaraan yang akan dicari.

Header permintaan harus berisi kolom Authorization dengan nilai Bearer <token>, dengan <token> adalah token yang diterbitkan 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 tersebut.

<taskId> adalah ID tugas yang akan dicari.

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

Isi permintaan harus kosong.

Jika pencarian berhasil, isi respons 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 kapan sebuah paket diharapkan 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 berdasarkan ID pelacakan, Anda dapat menggunakan salah satu cara berikut:

• Mencari dengan Java menggunakan gRPC
• Pencarian menggunakan HTTP

Persyaratan pencarian

• Informasi pengiriman yang diberikan oleh ID pelacakan mematuhi aturan visibilitas yang dinyatakan di 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 melakukan ini dengan Fleet Engine, Anda menggunakan lingkungan server atau browser.

• Gunakan token tersempit yang mungkin untuk membatasi risiko keamanan. Misalnya, jika Anda menggunakan Token Konsumen Pengiriman, setiap panggilan Fleet Engine Deliveries API hanya menampilkan informasi yang relevan dengan pengguna akhir tersebut, seperti pengirim atau penerima kiriman. Semua informasi lain dalam respons akan disamarkan. Untuk mengetahui informasi selengkapnya tentang token, lihat Membuat Token Web JSON (JWT) untuk otorisasi.

Mencari dengan Java menggunakan gRPC

Contoh berikut menunjukkan cara menggunakan library gRPC Java untuk mencari informasi tentang tugas pengiriman berdasarkan ID pelacakannya.

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TRACKING_ID = "TID-7449w087464x5";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Tasks request
String parent = "providers/" + PROJECT_ID;
GetTaskTrackingInfoRequest getTaskTrackingInfoRequest = GetTaskTrackingInfoRequest.newBuilder()  // No need for the header
    .setParent(parent)
    .setTrackingId(TRACKING_ID)
    .build();

try {
  TaskTrackingInfo taskTrackingInfo = deliveryService.getTaskTrackingInfo(getTaskTrackingInfoRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;

     case PERMISSION_DENIED:
       break;
  }
  return;
}

Mencari menggunakan HTTP

Untuk mencari tugas pengiriman dari browser, lakukan panggilan REST HTTP ke GetTaskTrackingInfo:

`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/taskTrackingInfo/<tracking_id>`

<tracking_id> adalah ID pelacakan yang terkait 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 menampilkan daftar tugas dari lingkungan server atau browser. Driver SDK tidak mendukung pembuatan listingan tugas.

Mencantumkan tugas meminta akses luas ke tugas. Membuat daftar tugas hanya ditujukan untuk pengguna tepercaya. Menggunakan Token Delivery Fleet Reader atau Delivery Super User Authentication saat membuat permintaan tugas daftar.

Tugas yang tercantum memiliki kolom berikut yang disamarkan:

• VehicleStop.planned_location
• VehicleStop.state
• VehicleStop.TaskInfo.taskId

Tugas yang tercantum dapat difilter menurut sebagian besar properti tugas. Untuk mengetahui 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 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, setelan 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 sama 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 untuk mencantumkan tugas untuk deliveryvehicleId dan atribut tugas. Respons yang berhasil masih boleh kosong. Respons kosong menunjukkan bahwa tidak ada Tasks yang terkait dengan deliveryvehicleId 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 mencantumkan 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> adalah token yang diterbitkan 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 ditemukan 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}"

Menampilkan daftar kendaraan pengiriman

Anda dapat menampilkan daftar kendaraan pengiriman dari lingkungan server atau browser. SDK Pengemudi tidak mendukung listingan kendaraan pengiriman.

Mencantumkan kendaraan pengiriman meminta akses luas ke kendaraan pengiriman dan ditujukan hanya untuk pengguna tepercaya. Menggunakan Delivery Fleet Reader atau Delivery Super User Authentication Token saat membuat permintaan daftar kendaraan pengiriman.

Kendaraan pengiriman yang tercantum memiliki kolom berikut yang disamarkan karena dampaknya terhadap ukuran respons:

• CurrentRouteSegment
• RemainingVehicleJourneySegments

Anda dapat memfilter kendaraan pengiriman daftar berdasarkan properti attributes miliknya. 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 menurut 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 ditolak jika berisi lintang tinggi yang secara geografis lebih rendah daripada lintang rendah.

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

Daftar kendaraan pengiriman diberi nomor halaman 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 ada lebih banyak halaman kendaraan pengiriman yang tersedia untuk diambil. Untuk mengambil halaman tugas berikutnya, gunakan token halaman dengan permintaan yang sama 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 itu terjadi, berarti tidak ada kendaraan dengan atribut yang ditentukan sudah berada di area tampilan 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 mencantumkan 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> adalah token yang diterbitkan 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, artinya tidak ada kendaraan pengiriman yang ditemukan yang memenuhi area pandang dan kueri filter yang ditentukan.

Contoh perintah curl:

# Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
  "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?filter=attributes.my_key%20%3D%20my_value%20&viewport.high.latitude=37.45&viewport.high.longitude=-122.06&viewport.low.latitude=37.41&viewport.low.longitude=-122.11"

Pelacakan pengiriman

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

• Pilihan: Gunakan library Pelacakan Pengiriman JavaScript. Library ini memungkinkan Anda memvisualisasikan lokasi kendaraan dan lokasi minat yang dilacak di Fleet Engine. Objek 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 dengan animasi yang dapat disesuaikan dari web atau aplikasi seluler Anda.

• Terapkan pelacakan pengiriman Anda sendiri pada Fleet Engine Deliveries API.

Kuncinya adalah mencari tugas pengiriman dengan ID pelacakan.

Jika Anda menggunakan Peran Delivery Consumer, setiap panggilan Fleet Engine Deliveries API hanya menampilkan informasi yang relevan untuk pengirim atau penerima. Semua informasi lain dalam respons disamarkan. Anda bertanggung jawab untuk mengotentikasi pengguna akhir. Selain itu, informasi lokasi difilter berdasarkan tugas yang sudah dilakukan. Selama tugas yang tidak tersedia, 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 selengkapnya, 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, dan setiap peran memberikan serangkaian izin yang berbeda.

Untuk mengetahui informasi selengkapnya, lihat Autentikasi dan Otorisasi.

Memecahkan masalah umum

Periksa bagian berikut untuk mendapatkan bantuan jika Anda mengalami masalah.

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 bekerja dengan Fleet Engine, implementasikan klien agar sistem sembuh dengan sendirinya jika terjadi kegagalan. Misalnya, saat Fleet Engine mencoba mengupdate kendaraan, Fleet Engine dapat merespons dengan error yang menunjukkan bahwa kendaraan tersebut tidak ada. Klien kemudian harus membuat ulang kendaraan dengan status baru. Meskipun masalah ini jarang terjadi, pastikan sistem Anda cukup tangguh untuk menanganinya.

Dalam skenario kegagalan bencana Fleet Engine yang sangat jarang terjadi, Anda mungkin perlu membuat ulang sebagian besar atau semua kendaraan dan tugas. Jika rasio pembuatan terlalu tinggi, beberapa permintaan mungkin 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 upaya ulang.

Status hilang di aplikasi pengemudi

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

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 entity sudah ada, error tersebut dapat diserap dan entity dapat diperbarui menggunakan ID-nya.

FAQ

Bagaimana jika pengemudi berhenti karena tugas yang tidak berurutan?

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