Mulai menggunakan Fleet Engine untuk Pelacakan Pengiriman

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

Penyiapan awal

Anda mengonfigurasi Fleet Engine Deliveries API di Google Cloud Console.

Memverifikasi penyiapan Anda

Setelah membuat akun layanan, pastikan penyiapan Anda sudah selesai dan Anda dapat membuat kendaraan pengiriman. Segera verifikasi konfigurasi Anda memastikan bahwa Anda telah mengatasi masalah otorisasi umum yang dapat timbul saat menyiapkan proyek Anda. Ada dua cara untuk memverifikasi konfigurasi Anda:

Library Klien

Untuk pengalaman developer yang lebih baik melalui gRPC atau REST mentah, gunakan library klien dalam beberapa bahasa pemrograman yang umum. Sebagai instruksi cara mendapatkan library klien untuk aplikasi server Anda, lihat Library Klien.

Contoh Java dalam dokumentasi ini mengasumsikan bahwa Anda sudah memahami gRPC.

Struktur data

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

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

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

Kendaraan pengiriman

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

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

Tasks

Untuk tindakan yang dilakukan kendaraan dalam sehari, Anda menetapkan tugas sesuai dengan jenis tindakan:

  • Untuk pengambilan dan pengantaran, tetapkan Tugas pengiriman.
  • Ketika pengemudi tidak dapat tersedia, seperti waktu istirahat yang diperlukan, menetapkan Tugas ketidaktersediaan.
  • Untuk tugas non-mengemudi di drop box atau lokasi pelanggan, tetapkan Tugas perhentian terjadwal.

Setiap tugas yang Anda tetapkan harus memiliki ID tugas unik, tetapi tugas dapat berbagi tugas yang sama ID pelacakan. Saat Fleet Engine menghitung PWT jendela untuk setiap tugas, ia menggunakan semua tugas dan urutan di mana mereka dijadwalkan untuk membuat perkiraan. Untuk informasi lebih lanjut tentang ID tugas, lihat Panduan ID tugas.

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

Tugas pengiriman

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

  • Lokasi pengambilan atau pengiriman.
  • Nomor atau ID pelacakan.
  • {i>Dwell time<i} untuk memperhitungkan waktu tambahan untuk menyelesaikan tugas, lihat untuk tempat parkir, atau berjalan ke lokasi penyerahan.
  • ID tugas unik. Lihat Panduan ID Tugas.

Untuk informasi selengkapnya, lihat topik berikut:

Android

iOS

Tugas ketidaktersediaan

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

Buat tugas ketidaktersediaan dengan informasi berikut:

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

Untuk informasi selengkapnya, lihat topik berikut:

Android

iOS

Tugas perhentian terjadwal

Buat tugas perhentian terjadwal untuk membuat model perhentian yang diperlukan kendaraan pengiriman lakukan. Misalnya, buat tugas perhentian terjadwal untuk jadwal harian pengumpulan berhenti di lokasi tertentu, terlepas dari pengiriman lainnya atau pengambilan di lokasi yang sama. Anda juga dapat membuat tugas perhentian terjadwal untuk koleksi dari drop box atau untuk model transfer feeder-vehicle atau berhenti di pusat layanan dan titik servis.

Untuk informasi selengkapnya, lihat topik berikut:

Android

iOS

Panduan ID tugas

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

  • Membuat ID tugas unik
  • Jangan mengungkapkan informasi identitas pribadi (PII) atau menghapus data teks.
  • Gunakan string Unicode yang valid.
  • Gunakan 64 karakter atau kurang.
  • Jangan sertakan salah satu karakter ASCII berikut: "/", ":", "\", "?", atau "#".
  • Lakukan normalisasi sesuai dengan Formulir Normalisasi Unicode C.

Berikut adalah beberapa contoh ID Tugas yang baik:

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

Tabel berikut menunjukkan contoh ID Tugas yang tidak didukung:

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

Referensi lainnya

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

Masa pakai kendaraan

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

  • Project ID dari project Google Cloud yang berisi akun layanan biasa digunakan untuk memanggil API Fleet Engine.
  • ID kendaraan milik pelanggan.

Gunakan ID kendaraan yang unik untuk tiap kendaraan. Jangan gunakan ulang ID kendaraan kecuali jika tidak ada tugas aktif untuk kendaraan asli.

Fleet Engine otomatis menghapus objek DeliveryVehicle yang belum diperbarui menggunakan UpdateDeliveryVehicle setelah tujuh hari. Rekomendasi pendekatan untuk menjaga agar kendaraan tetap tersedia di Fleet Engine adalah dengan memperbarui lokasinya dengan interval yang teratur. Pembaruan pada sebagian besar kolom lainnya di DeliveryVehicle entitas juga akan memperpanjang umurnya, asalkan nilai kolom baru berbeda dari yang lama.

Untuk melihat apakah kendaraan ada:

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

Jenis kendaraan

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

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

Atribut kendaraan

Entity DeliveryVehicle berisi kolom berulang berupa DeliveryVehicleAttribute. ListDeliveryVehicles API menyertakan filter yang dapat membatasi entitas DeliveryVehicle yang ditampilkan ke entitas dengan atribut yang ditentukan. DeliveryVehicleAttribute tidak memengaruhi Fleet Engine perilaku {i>routing<i}.

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

Umur tugas

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

Objek Task memiliki kolom status untuk melacak progresnya siklus hidupnya. Nilai dipindahkan dari OPEN ke CLOSED. Tugas baru dibuat dalam status OPEN, yang menunjukkan bahwa:

  • Tugas belum ditugaskan ke kendaraan pengiriman.
  • Kendaraan pengiriman belum melewati perhentian kendaraan yang ditetapkan tugas.

Panduan tugas

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

Anda membatalkan tugas dengan menghapusnya dari daftar perhentian kendaraan, yang akan menetapkan status tugas menjadi TUTUP secara otomatis.

Saat kendaraan tugas menyelesaikan penghentian kendaraan tugas:

  1. Perbarui kolom hasil tugas ke SUCCESS atau FAILED.

  2. Tentukan stempel waktu peristiwa.

    {i>Library<i} Pelacakan Pengiriman JavaScript kemudian menunjukkan hasil tugas dan status tugas diatur ke {i>CLOSED<i} secara otomatis. Untuk informasi selengkapnya, lihat Lacak Pengiriman Anda 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, maka akan menghasilkan {i>error<i}.

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

Atribut tugas

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

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

Mengelola siklus proses kendaraan dan tugas

Pengingat: Sistem internal Anda bertindak sebagai sumber data tepercaya yang Fleet Engine Deliveries API meningkatkan untuk Anda.

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

Pada saat yang sama, aplikasi pengemudi berkomunikasi langsung ke Fleet Engine untuk memperbarui informasi rute dan lokasi perangkat. Model ini membuat Fleet Engine mengelola lokasi real-time secara efisien. Ini mengirimkan lokasi langsung ke pustaka pelacakan, yang kemudian dapat Anda gunakan untuk memberitahukan status konsumen pesanan mereka.

Misalnya, Anda memiliki skenario berikut:

  • Pengemudi mendekati halte pengiriman. Aplikasi pengemudi mengirimkan lokasinya ke Fleet Engine.
  • Fleet Engine mengirimkan lokasi perangkat ke pustaka pelacakan, yang digunakan aplikasi konsumen Anda untuk memberi tahu konsumen dekat dengan paket mereka.
  • Setelah pengemudi menyelesaikan pengiriman, mereka akan mengklik "Pengiriman terkirim" pada aplikasi driver.
  • "Pengiriman terkirim" tindakan mengirimkan informasi ke sistem backend Anda, yang melakukan langkah-langkah validasi dan verifikasi bisnis yang diperlukan.
  • Sistem Anda mengonfirmasi bahwa tugas sebagai SUCCEEDED dan memperbarui Fleet Engine menggunakan Deliveries API.

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

Menggunakan Deliveries API

Kelola token klien

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

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

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

Pendekatan ini memastikan bahwa panggilan yang berasal dari perangkat seluler--dianggap di lingkungan yang kurang tepercaya--taatilah prinsip hak istimewa terendah.

Peran akun layanan lainnya

Jika Anda ingin mengizinkan aplikasi {i>driver<i} untuk melakukan Pembaruan Fleet Engine di luar yang dibatasi pada peran Pengemudi Tidak Tepercaya, seperti untuk pembaruan tugas tertentu, Anda dapat menggunakan peran {i>Trusted Driver<i}. Sebagai informasi tentang model yang menggunakan peran Trusted Driver, lihat Model Driver Tepercaya.

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

Membuat model hari kerja

Tabel berikut menjelaskan bagaimana hari kerja untuk pengemudi kilometer pertama atau terakhir mungkin terlihat seperti di perusahaan pengiriman dan logistik. Perusahaan Anda mungkin berbeda dalam detailnya, tetapi Anda dapat melihat bagaimana Anda dapat membuat model hari kerja.

WaktuAktivitasModel
Dalam waktu 24 jam sejak awal hari Petugas operator menugaskan pengiriman ke kendaraan atau rute pengiriman. Anda dapat membuat tugas untuk pengiriman, pengambilan, istirahat, dan orang lain di Fleet Engine. Misalnya, Anda dapat membuat tugas pengambilan pengiriman, tugas pengiriman, ketidaktersediaan terjadwal, atau perhentian terjadwal.

Menetapkan tugas ke kendaraan setelah serangkaian paket pengiriman dan urutan pengirimannya diselesaikan.
Awal hari Pengemudi memulai hari di depot dengan login ke aplikasi Driver. Melakukan inisialisasi Delivery Driver API. Buat kendaraan pengiriman di Fleet Engine sesuai kebutuhan.
Pengemudi memuat kiriman ke kendaraan pengiriman, memindai kiriman. Jika tugas pengiriman pengiriman tidak dibuat sebelumnya, membuat tugas pengiriman pada saat pemindaian.
Pengemudi mengonfirmasi urutan tugas yang akan dilakukan. Jika tidak dibuat sebelumnya, buatlah tugas pengambilan pengiriman, ketidaktersediaan terjadwal, dan perhentian terjadwal.
Pengemudi meninggalkan depot dan berkomitmen pada jumlah tugas berikutnya yang akan selesai. Tetapkan semua tugas atau sebagian tugas ke kendaraan dengan melakukan pesanan penyelesaian proyek.
Pengemudi mengirim barang. Setelah tiba di halte pengiriman, lakukan tindakan terkait ke kendaraan yang tiba di perhentian. Setelah mengirimkan kiriman, tutup tugas pengiriman dan, secara opsional, status pengiriman toko dan informasi meta lainnya. Setelah menyelesaikan semua tugas di perhentian dan sebelum mulai berkendara ke perhentian berikutnya, melakukan tindakan terkait kendaraan menyelesaikan perhentian dan kendaraan yang sedang dalam perjalanan ke perhentian berikutnya.
Pengemudi bertemu kendaraan pengumpan untuk mentransfer pengiriman tambahan ke kendaraan pengiriman. Titik pertemuan untuk transfer antara kendaraan pengumpan dan pengiriman harus dimodelkan sebagai perhentian terjadwal.

Setelah mentransfer dan memindai pengiriman, buat tugas pengiriman jika belum dibuat. Kemudian perbarui penyelesaian tugas pesanan dengan menetapkan tugas ke kendaraan dan memperbarui pengurutan tugas.
Pengemudi menerima notifikasi permintaan pengambilan. Setelah menerima permintaan pengambilan, membuat tugas pengambilan pengiriman. Kemudian perbarui eksekusi tugas pesanan dengan menetapkan tugas ke kendaraan dan memperbarui pengurutan tugas.
Siang Pengemudi beristirahat makan siang. Jika lokasi dikaitkan dengan tugas ketidaktersediaan, perlakukan hal tersebut seperti tugas lain. Melakukan tindakan terkait kendaraan tiba di perhentian, kendaraan menyelesaikan perhentian dan kendaraan yang sedang dalam perjalanan ke perhentian berikutnya.

Jika tidak, tindakan lebih lanjut tidak diperlukan sampai akhir jeda. Hapus tugas dengan mengonfirmasi tugas berikutnya dan tugas yang tersisa, dan memperbarui pengurutan tugas.
Pengemudi mengambil kiriman. Ini dimodelkan seperti perhentian pengiriman. Melakukan tindakan terkait ke kendaraan yang tiba di perhentian dan menutup tugas, dan, secara opsional, menyimpan status pengiriman dan informasi meta lainnya. Setelah menyelesaikan semua tugas di perhentian dan sebelum mulai mengemudi ke perhentian berikutnya, melakukan tindakan terkait kendaraan yang menyelesaikan perhentian dan kendaraan yang sedang dalam perjalanan ke perhentian berikutnya. Catatan: Untuk memastikan penagihan yang benar, semua pengambilan harus memiliki pengiriman tugas. Jika pengambilan akan diantar ke lokasi lain pada rute yang sama dengan pengemudi pada hari itu, sebaiknya modelkan tugas pengiriman itu sebagai tugas pengiriman lainnya di rute tersebut. Jika pengemudi membawa penjemputan kembali ke depot, sebaiknya buat tugas pengiriman di depot tujuan.
Pengemudi membuat jadwal perhentian untuk mengambil kiriman dari kotak barang. Di sini dibuat modelnya sama seperti tempat penjemputan lainnya. Melakukan tindakan terkait ke kendaraan yang tiba di perhentian dan menutup tugas. Setelah menyelesaikan semua tugas di perhentian dan mulai berkendara ke perhentian berikutnya, melakukan tindakan yang terkait dengan kendaraan yang menyelesaikan perhentian dan kendaraan yang sedang dalam perjalanan ke perhentian berikutnya.
Pengemudi menerima notifikasi tentang pengiriman yang dialihkan ke lokasi alternatif. Tetapkan status tugas pengiriman asli ke SELESAI dan buat yang baru pengiriman untuk lokasi pengiriman baru. Untuk informasi selengkapnya, lihat Mengubah rute pengiriman.
Pengemudi mencoba mengirimkan paket tetapi tidak dapat melakukannya. Hal ini dimodelkan mirip dengan perhentian pengiriman yang berhasil, yang menandai tugas pengiriman telah selesai. Melakukan tindakan yang terkait dengan kendaraan yang tiba di perhentian. Sesudah pengiriman yang gagal, menutup tugas dan, jika perlu, status pengiriman toko dan informasi meta lainnya. Setelah menyelesaikan semua tugas di perhentian dan sebelum mulai mengemudi ke perhentian berikutnya, melakukan tindakan terkait kendaraan yang menyelesaikan perhentian dan kendaraan yang sedang dalam perjalanan ke perhentian berikutnya.
Pengemudi diberi tahu untuk menahan (tidak mengirimkan) kiriman. Setelah notifikasi diterima dan dikonfirmasi, tetapkan status tugas ke COMPLETED.
Pengemudi diberi tahu untuk mengirimkan kiriman tertentu berikutnya, sehingga mengubah komitmen pesanan pengiriman. Memperbarui urutan tugas.
Pengemudi memilih untuk mengantarkan pesanan secara tidak berurutan. Memperbarui urutan tugas, lalu lanjutkan seperti biasa.
Pengemudi mengirimkan beberapa kiriman ke satu lokasi. Model ini dibuat mirip dengan satu perhentian pengiriman. Setelah tiba di perhentian, lakukan tindakan yang terkait dengan kendaraan yang tiba di perhentian. Setelah mengirimkan setiap pengiriman, tutup setiap tugas dan, jika perlu, status pengiriman toko dan informasi meta lainnya. Setelah menyelesaikan semua tugas di perhentian dan sebelum mulai mengemudi ke perhentian berikutnya, melakukan tindakan terkait kendaraan yang menyelesaikan perhentian dan kendaraan yang sedang dalam perjalanan ke perhentian berikutnya.
Akhir hari Pengemudi kembali ke depot. Jika pengemudi kembali ke depot dengan mengangkut barang yang telah diambil Anda juga harus membuat dan menutup setiap paket sebagai tugas pengiriman untuk memastikan penagihan yang benar. Anda dapat melakukannya dengan membuat model depot seperti pengiriman lainnya. Jika depot tidak digunakan sebagai perhentian pengiriman, Anda masih dapat memilih memodelkan depot sebagai perhentian terjadwal. Pemodelan perhentian memungkinkan pengemudi Anda untuk melihat rute kembali ke depot dan memberikan visibilitas tentang perkiraan waktu mereka dari kedatangan.

Cara kerja pembaruan lokasi

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

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

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

Perhentian kendaraan dan lokasi pengiriman

Pemberhentian kendaraan adalah tempat kendaraan pengiriman menyelesaikan tugas pengiriman atau tugas lain. Ini bisa berupa titik akses seperti dok pemuatan atau lokasi yang diambil oleh jalan.

Lokasi pengiriman adalah lokasi pengantaran atau diangkat. Pergi ke dan dari lokasi pengiriman mungkin perlu berjalan beberapa saat dari halte kendaraan.

Misalnya, saat pengemudi mengantarkan pengiriman ke toko di sebuah mal, kendaraan pengiriman berhenti di tempat parkir mal dekat pintu masuk terdekat ke toko. Ini adalah perhentian kendaraan. Pengemudi kemudian berjalan dari halte kendaraan ke lokasi dalam mal di mana lokasi toko. Ini adalah lokasi pengiriman.

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

Misalnya, jika seorang pengemudi melakukan banyak pengiriman ke satu gedung kantor, pertimbangkan untuk menetapkan semua tugas pengiriman ke satu perhentian kendaraan. Jika setiap tugas pengiriman ditugaskan ke pemberhentian kendaraannya sendiri, pengiriman pesanan pengalaman pelacakan akan kurang membantu pengguna Anda karena pelacakan hanya setelah kendaraan berada dalam sejumlah perhentian kendaraan yang terbatas sebelum tujuannya. Banyaknya penghentian kendaraan dalam waktu singkat tidak memberikan banyak waktu bagi pengguna untuk melacak kemajuan pengiriman mereka.

Menggunakan SDK seluler

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

Melakukan inisialisasi Delivery Driver API

Sebelum menginisialisasi Delivery Driver API di Driver SDK, pastikan untuk melakukan inisialisasi Navigation SDK. Kemudian inisialisasi Delivery Driver API seperti ditunjukkan pada contoh berikut:

static final String PROVIDER_ID = "provider-1234";
static final String VEHICLE_ID = "vehicle-8241890";

NavigationApi.getNavigator(
   this, // Activity.
   new NavigatorListener() {
     @Override
     public void onNavigatorReady(Navigator navigator) {
       DeliveryDriverApi.createInstance(DriverContext.builder(getApplication())
         .setNavigator(navigator)
         .setProviderId(PROVIDER_ID)
         .setVehicleId(VEHICLE_ID)
         .setAuthTokenFactory((context) -> "JWT") // AuthTokenFactory returns JWT for call context.
         .setRoadSnappedLocationProvider(NavigationApi.getRoadSnappedLocationProvider(getApplication()))
         .setNavigationTransactionRecorder(NavigationApi.getNavigationTransactionRecorder(getApplication()))
         .setStatusListener((statusLevel,statusCode,statusMsg) -> // Optional, surfaces polling errors.
             Log.d("TAG", String.format("New status update. %s, %s, %s", statusLevel, statusCode, statusMsg)))
         .build));
     }
     @Override
     public void onError(int errorCode) {
       Log.e("TAG", String.format("Error loading Navigator instance: %s", errorCode));
     }
   });

Kasus penggunaan

Bagian ini menjelaskan cara menggunakan Deliveries API untuk membuat model kasus penggunaan umum.

ID entitas unik

Format dan nilai ID entity unik yang digunakan dalam panggilan REST adalah buram ke Fleet Engine. Hindari penggunaan ID yang bertambah otomatis, dan pastikan bahwa ID tidak berisi informasi identitas pribadi (PII), seperti nomor telepon pengemudi.

Buat kendaraan

Anda dapat membuat kendaraan dari Driver SDK atau dari lingkungan server menggunakan gRPC atau REST.

gRPC

Untuk membuat kendaraan baru, lakukan panggilan CreateDeliveryVehicle ke Fleet Engine. Gunakan objek CreateDeliveryVehicleRequest untuk menentukan atribut kendaraan pengiriman yang baru. Perhatikan bahwa nilai apa pun yang ditentukan untuk kolom Name diabaikan per panduan API untuk ID yang ditentukan pengguna. Anda harus menggunakan kolom DeliveryVehicleId untuk menetapkan ID kendaraan.

Saat membuat DeliveryVehicle, Anda dapat menentukan kolom ini secara opsional:

  • Atribut
  • LastLocation
  • Jenis

Jangan tetapkan kolom lain. Jika Anda melakukannya, Fleet Engine akan menampilkan error karena isian itu bersifat {i>read-only<i} atau hanya dapat diperbarui dengan panggilan ke UpdateDeliveryVehicle.

Untuk membuat kendaraan tanpa menyetel kolom opsional, Anda dapat keluar dari halaman Kolom DeliveryVehicle tidak disetel di CreateDeliveryVehicleRequest.

Contoh berikut menunjukkan cara menggunakan Library gRPC Java untuk membuat kendaraan:

    static final String PROJECT_ID = "my-delivery-co-gcp-project";
    static final String VEHICLE_ID = "vehicle-8241890"; // Avoid auto-incrementing IDs.

    DeliveryServiceBlockingStub deliveryService =
      DeliveryServiceGrpc.newBlockingStub(channel);

    // Vehicle settings
    String parent = "providers/" + PROJECT_ID;
    DeliveryVehicle vehicle = DeliveryVehicle.newBuilder()
      .addAttributes(DeliveryVehicleAttribute.newBuilder()
        .setKey("route_number").setValue("1"))  // Opaque to the Fleet Engine
      .build();

    // Vehicle request
    CreateDeliveryVehicleRequest createVehicleRequest =
      CreateDeliveryVehicleRequest.newBuilder()  // No need for the header
          .setParent(parent)
          .setDeliveryVehicleId(VEHICLE_ID)     // Vehicle ID assigned by the Provider
          .setDeliveryVehicle(vehicle)
          .build();

    // Error handling
    // If Fleet Engine does not have vehicle with that ID and the credentials of the
    // requestor pass, the service creates the vehicle successfully.

    try {
      DeliveryVehicle createdVehicle =
        deliveryService.createDeliveryVehicle(createVehicleRequest);
    } catch (StatusRuntimeException e) {
      Status s = e.getStatus();
      switch (s.getCode()) {
         case ALREADY_EXISTS:
           break;
         case PERMISSION_DENIED:
           break;
      }
      return;
    }

REST

Untuk membuat kendaraan dari lingkungan server, lakukan panggilan REST HTTP ke CreateDeliveryVehicle:

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

&lt;id&gt; adalah ID unik untuk kendaraan pengiriman di armada Anda.

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

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

  • attribut
  • lastLocation
  • jenis

Contoh perintah curl:

# Set $JWT, $PROJECT_ID, and $VEHICLE_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?deliveryVehicleId=${VEHICLE_ID}" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
  "attributes": [{"key": "model", "value": "sedan"}],
  "lastLocation": {"location": {"latitude": 12.1, "longitude": 14.5}}
}
EOM

Fleet Engine mengabaikan kolom name dari entity DeliveryVehicle sesuai panduan API untuk ID yang ditentukan pengguna. Jangan tetapkan kolom lain. Jika Anda melakukannya, Fleet Engine akan menampilkan error karena isian itu bersifat {i>read-only<i} atau hanya dapat diperbarui menggunakan panggilan untuk UpdateDeliveryVehicle.

Untuk membuat kendaraan tanpa menyetel kolom apa pun, tinggalkan isi POST kosong. Kendaraan yang baru dibuat kemudian mengekstrak ID kendaraan dari Parameter deliveryVehicleId di URL POST.

Contoh perintah curl:

# Set $JWT, $PROJECT_ID, and $VEHICLE_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?deliveryVehicleId=${VEHICLE_ID}" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}"

Membuat tugas pengambilan pengiriman

Anda dapat membuat tugas pengambilan pengiriman dari SDK Driver atau dari lingkungan server menggunakan gRPC atau REST.

gRPC

Contoh berikut menunjukkan cara menggunakan Library gRPC Java untuk membuat tugas pengambilan pengiriman:

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
  .setType(Task.Type.PICKUP)
  .setState(Task.State.OPEN)
  .setTrackingId("my-tracking-id")
  .setPlannedLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .setTaskDuration(
    Duration.newBuilder().setSeconds(2 * 60))
  .setTargetTimeWindow(
    TimeWindow.newBuilder()
      .setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
      .setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
  .addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
  .addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
  .addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
  .build();

// Task request
CreateTaskRequest createTaskRequest =
  CreateTaskRequest.newBuilder()  // No need for the header
      .setParent(parent)          // Avoid using auto-incrementing IDs for the taskId
      .setTaskId("task-8241890")  // Task ID assigned by the Provider
      .setTask(task)              // Initial state
      .build();

// Error handling
// If Fleet Engine does not have a task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.

try {
  Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case ALREADY_EXISTS:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Untuk membuat tugas pengambilan pengiriman dari lingkungan server, buat panggilan REST HTTP ke CreateTask:

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

&lt;id&gt; adalah ID unik untuk tugas. Tidak boleh berupa nomor pelacakan untuk pengiriman. Jika tidak memiliki ID tugas di sistem, Anda dapat membuat pengenal unik universal (UUID).

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

Isi permintaan harus berisi entity Task:

  • Kolom wajib diisi:

    KolomNilai
    jenis Type.PICKUP
    dengan status tersembunyi akhir State.OPEN
    trackingId Nomor atau ID yang Anda gunakan untuk melacak pengiriman.
    plannedLocation Lokasi tempat tugas akan diselesaikan, dalam hal ini lokasi pengambilan pengiriman.
    taskDuration Waktu yang diharapkan, dalam detik, yang diperlukan untuk mengambil kiriman di lokasi penjemputan.

  • Kolom opsional:

    KolomNilai
    targetTimeWindow Periode waktu saat tugas harus diselesaikan. Hal ini tidak mempengaruhi perilaku {i>routing<i}.
    attribut Daftar atribut Tugas kustom. Setiap atribut harus memiliki kunci unik.

Semua kolom lain dalam entity diabaikan untuk pembuatan. Lemparan Fleet Engine pengecualian jika permintaan menyertakan deliveryVehicleId yang ditetapkan. Anda menetapkan tugas menggunakan UpdateDeliveryVehicleRequest. Untuk informasi selengkapnya, lihat Menetapkan tugas ke kendaraan dan UpdateDeliveryVehicleRequest.

Contoh perintah curl:

# Set $JWT, $PROJECT_ID, $TRACKING_ID, and $TASK_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "type": "PICKUP",
  "state": "OPEN",
  "trackingId": "${TRACKING_ID}",
  "plannedLocation": {
     "point": {
        "latitude": -6.195139,
        "longitude": 106.820826
     }
  },
  "taskDuration": "90s",
  "targetTimeWindow": {
    "startTime": "2023-03-29T21:00:00Z",
    "endTime": "2023-03-29T23:00:00Z"
  }
}
EOM

Membuat tugas pengiriman pengiriman

Buat tugas pengiriman, baik dari SDK Driver atau dari lingkungan server menggunakan gRPC atau REST.

gRPC

Contoh berikut menunjukkan cara menggunakan Library gRPC Java untuk membuat tugas pengiriman:

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
  .setType(Task.Type.DELIVERY)
  .setState(Task.State.OPEN)
  .setTrackingId("my-tracking-id")
  .setPlannedLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .setTaskDuration(
    Duration.newBuilder().setSeconds(2 * 60))
  .setTargetTimeWindow(
    TimeWindow.newBuilder()
      .setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
      .setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
  .addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
  .addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
  .addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
  .build();

// Task request
CreateTaskRequest createTaskRequest =
  CreateTaskRequest.newBuilder()  // No need for the header
      .setParent(parent)          // Avoid using auto-incrementing IDs for the taskId
      .setTaskId("task-8241890")  // Task ID assigned by the Provider
      .setTask(task)              // Initial state
      .build();

// Error handling
// If Fleet Engine does not have task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.

try {
  Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case ALREADY_EXISTS:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Untuk membuat tugas pengiriman pengiriman dari lingkungan server menggunakan gRPC atau REST, buat panggilan REST HTTP ke CreateTask:

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

&lt;id&gt; adalah ID unik untuk tugas. Tidak boleh berupa nomor pelacakan untuk pengiriman. Jika tidak memiliki ID tugas di sistem, Anda dapat membuat pengenal unik universal (UUID).

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

Isi permintaan harus berisi entity Task:

  • Kolom wajib diisi:

    KolomNilai
    jenis Type.DELIVERY
    dengan status tersembunyi akhir State.OPEN
    trackingId Nomor atau ID yang Anda gunakan untuk melacak pengiriman.
    plannedLocation Lokasi tempat tugas akan diselesaikan, dalam hal ini lokasi pengiriman untuk pengiriman ini.
    taskDuration Waktu yang diharapkan, dalam detik, yang diperlukan untuk menurunkan kiriman di lokasi pengiriman.

  • Kolom opsional:

    KolomNilai
    targetTimeWindow Periode waktu saat tugas harus diselesaikan. Hal ini tidak mempengaruhi perilaku {i>routing<i}.
    attribut Daftar atribut Tugas kustom. Setiap atribut harus memiliki kunci unik.

Semua kolom lain dalam entity diabaikan untuk pembuatan. Lemparan Fleet Engine pengecualian jika permintaan menyertakan deliveryKendaraanId yang ditetapkan. Anda menetapkan tugas menggunakan UpdateDeliveryVehicleRequest. Untuk informasi selengkapnya, lihat Menetapkan tugas ke kendaraan dan UpdateDeliveryVehicleRequest.

Contoh perintah curl:

# Set $JWT, $PROJECT_ID, $TRACKING_ID, and $TASK_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "type": "DELIVERY",
  "state": "OPEN",
  "trackingId": "${TRACKING_ID}",
  "plannedLocation": {
     "point": {
        "latitude": -6.195139,
        "longitude": 106.820826
     }
  },
  "taskDuration": "90s",
  "targetTimeWindow": {
    "startTime": "2023-03-29T21:00:00Z",
    "endTime": "2023-03-29T23:00:00Z"
  }
}
EOM

Buat Tugas Secara Kelompok

Anda dapat membuat batch tugas dari lingkungan server menggunakan gRPC atau REST.

gRPC

Contoh berikut menunjukkan cara menggunakan Library gRPC Java untuk membuat dua tugas, satu untuk pengantaran dan satu untuk pengambilan pada saat yang sama lokasi:

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Delivery Task settings
Task deliveryTask = Task.newBuilder()
  .setType(Task.Type.DELIVERY)
  .setState(Task.State.OPEN)
  .setTrackingId("delivery-tracking-id")
  .setPlannedLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .setTaskDuration(
    Duration.newBuilder().setSeconds(2 * 60))
  .build();

// Delivery Task request
CreateTaskRequest createDeliveryTaskRequest =
  CreateTaskRequest.newBuilder()  // No need for the header or parent fields
      .setTaskId("task-8312508")  // Task ID assigned by the Provider
      .setTask(deliveryTask)      // Initial state
      .build();

// Pickup Task settings
Task pickupTask = Task.newBuilder()
  .setType(Task.Type.PICKUP)
  .setState(Task.State.OPEN)
  .setTrackingId("pickup-tracking-id")
  .setPlannedLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .setTaskDuration(
    Duration.newBuilder().setSeconds(2 * 60))
  .build();

// Pickup Task request
CreateTaskRequest createPickupTaskRequest =
  CreateTaskRequest.newBuilder()  // No need for the header or parent fields
      .setTaskId("task-8241890")  // Task ID assigned by the Provider
      .setTask(pickupTask)        // Initial state
      .build();

// Batch Create Tasks settings
String parent = "providers/" + PROJECT_ID;

// Batch Create Tasks request
BatchCreateTasksRequest batchCreateTasksRequest =
  BatchCreateTasksRequest.newBuilder()
      .setParent(parent)
      .addRequests(createDeliveryTaskRequest)
      .addRequests(createPickupTaskRequest)
      .build();

// Error handling
// If Fleet Engine does not have any task(s) with these task ID(s) and the
// credentials of the requestor pass, the service creates the task(s)
// successfully.

try {
  BatchCreateTasksResponse createdTasks = deliveryService.batchCreateTasks(
    batchCreateTasksRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case ALREADY_EXISTS:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Untuk membuat tugas pengiriman dan pengambilan dari lingkungan server, buat Panggilan REST HTTP ke BatchCreateTasks:

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

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

Isi permintaan harus berisi entity BatchCreateTasksRequest:

  • Kolom wajib diisi:

    KolomNilai
    permintaan Array<CreateTasksRequest>

  • Kolom opsional:

    KolomNilai
    header `DeliveryRequestHeader`

Setiap elemen CreateTasksRequest di requests harus lulus validasi yang sama sebagai permintaan CreateTask, dengan pengecualian bahwa parent dan kolom header bersifat opsional. Jika ditetapkan, penentu tersebut harus sama dengan {i>field<i} masing-masing di tingkat teratas BatchCreateTasksRequest. Lihat membuat tugas pengambilan pengiriman dan membuat tugas pengiriman untuk setiap aturan validasinya.

Untuk informasi selengkapnya, lihat dokumentasi Referensi API untuk BatchCreateTasks (gRPC, REST).

Contoh perintah curl:

# Set $JWT, $PROJECT_ID, $DELIVERY_TRACKING_ID, $DELIVERY_TASK_ID,
# $PICKUP_TRACKING_ID, and $PICKUP_TASK_ID in the local environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks:batchCreate" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "requests" : [
    {
      "taskId": "${DELIVERY_TASK_ID}",
      "task" : {
        "type": "DELIVERY",
        "state": "OPEN",
        "trackingId": "${DELIVERY_TRACKING_ID}",
        "plannedLocation": {
          "point": {
              "latitude": -6.195139,
              "longitude": 106.820826
          }
        },
        "taskDuration": "90s"
      }
    },
    {
      "taskId": "${PICKUP_TASK_ID}",
      "task" : {
        "type": "PICKUP",
        "state": "OPEN",
        "trackingId": "${PICKUP_TRACKING_ID}",
        "plannedLocation": {
          "point": {
              "latitude": -6.195139,
              "longitude": 106.820826
          }
        },
        "taskDuration": "90s"
      }
    }
  ]
}
EOM

Ketidaktersediaan terjadwal

Anda dapat membuat tugas yang menunjukkan ketidaktersediaan (misalnya, untuk pengemudi atau mengisi bahan bakar kendaraan) baik dari SDK Driver, atau dari lingkungan server menggunakan gRPC atau REST. Tugas ketidaktersediaan terjadwal tidak boleh disertakan ID pelacakan. Anda dapat memberikan lokasi secara opsional.

gRPC

Contoh berikut menunjukkan cara menggunakan Library gRPC Java untuk membuat tugas ketidaktersediaan:

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

    DeliveryServiceBlockingStub deliveryService =
      DeliveryServiceGrpc.newBlockingStub(channel);

    // Task settings
    String parent = "providers/" + PROJECT_ID;
    Task task = Task.newBuilder()
      .setType(Task.Type.UNAVAILABLE)
      .setState(Task.State.OPEN)
      .setTaskDuration(
        Duration.newBuilder().setSeconds(60 * 60))  // 1hr break
      .build();

    // Task request
    CreateTaskRequest createTaskRequest =
      CreateTaskRequest.newBuilder()  // No need for the header
          .setParent(parent)          // Avoid using auto-incrementing IDs for the taskId
          .setTaskId("task-8241890")  // Task ID assigned by the Provider
          .setTask(task)              // Initial state
          .build();

    // Error handling
    // If Fleet Engine does not have task with that ID and the credentials of the
    // requestor pass, the service creates the task successfully.

    try {
      Task createdTask = deliveryService.createTask(createTaskRequest);
    } catch (StatusRuntimeException e) {
      Status s = e.getStatus();
      switch (s.getCode()) {
         case ALREADY_EXISTS:
           break;
         case PERMISSION_DENIED:
           break;
      }
      return;
    }

REST

Untuk membuat tugas ketidaktersediaan dari lingkungan server, buat panggilan REST HTTP ke CreateTask:

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

&lt;id&gt; adalah ID unik untuk tugas. Jika Anda tidak memiliki ID tugas di sistem Anda, Anda dapat membuat pengenal tertentu (UUID).

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

Isi permintaan harus berisi entity Task:

  • Kolom wajib diisi:

    KolomNilai
    jenis Type.UNAVAILABLE
    dengan status tersembunyi akhir State.OPEN
    taskDuration Durasi jeda dalam detik.

  • Kolom opsional:

    KolomNilai
    plannedLocation Lokasi istirahat jika harus diambil di lokasi tertentu.

Semua kolom lain dalam entity diabaikan untuk pembuatan. Lemparan Fleet Engine pengecualian jika permintaan menyertakan deliveryKendaraanId yang ditetapkan. Anda menetapkan tugas menggunakan UpdateDeliveryVehicleRequest. Untuk informasi selengkapnya, lihat Menetapkan tugas ke kendaraan dan UpdateDeliveryVehicleRequest.

Contoh perintah curl:

    # Set $JWT, $PROJECT_ID, and $TASK_ID in the local environment
    curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
      -H "Content-type: application/json" \
      -H "Authorization: Bearer ${JWT}" \
      --data-binary @- << EOM
    {
      "type": "UNAVAILABLE",
      "state": "OPEN",
      "plannedLocation": {
         "point": {
            "latitude": -6.195139,
            "longitude": 106.820826
         }
      },
      "taskDuration": "300s"
    }
    EOM

Perhentian terjadwal

Anda dapat membuat tugas perhentian terjadwal baik dari SDK Driver, atau dari lingkungan server menggunakan gRPC atau REST. Tugas perhentian terjadwal mungkin tidak menyertakan pelacakan ke ID.

gRPC

Contoh berikut menunjukkan cara menggunakan Library gRPC Java untuk membuat tugas perhentian terjadwal:

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
  .setType(Task.Type.SCHEDULED_STOP)
  .setState(Task.State.OPEN)
  .setPlannedLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .setTaskDuration(
    Duration.newBuilder().setSeconds(2 * 60))
  .build();

// Task request
CreateTaskRequest createTaskRequest =
  CreateTaskRequest.newBuilder()  // No need for the header
      .setParent(parent)
      .setTaskId("task-8241890")  // Task ID assigned by the Provider
      .setTrip(task)              // Initial state
      .build();

// Error handling
// If Fleet Engine does not have task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.

try {
  Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case ALREADY_EXISTS:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Untuk membuat tugas penghentian terjadwal dari lingkungan server, buat panggilan REST HTTP ke CreateTask:

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

&lt;id&gt; adalah ID unik untuk tugas. Jika Anda tidak memiliki ID tugas di sistem Anda, Anda dapat membuat pengenal unik universal (UUID).

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

Isi permintaan harus berisi entity Task:

  • Kolom wajib diisi:

    KolomNilai
    jenis Type.SCHEDULED_STOP
    dengan status tersembunyi akhir State.OPEN
    plannedLocation Lokasi perhentian.
    taskDuration Perkiraan panjang perhentian dalam hitungan detik.

  • Kolom opsional:

    • Tidak ada

Semua kolom lain dalam entity diabaikan untuk pembuatan. Lemparan Fleet Engine pengecualian jika permintaan menyertakan deliveryKendaraanId yang ditetapkan. Anda menetapkan tugas menggunakan UpdateDeliveryVehicleRequest. Untuk informasi selengkapnya, lihat Menetapkan tugas ke kendaraan dan UpdateDeliveryVehicleRequest.

Contoh perintah curl:

    # Set $JWT, $PROJECT_ID, and $TASK_ID in the local environment
    curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
      -H "Content-type: application/json" \
      -H "Authorization: Bearer ${JWT}" \
      --data-binary @- << EOM
    {
      "type": "SCHEDULED_STOP",
      "state": "OPEN",
      "plannedLocation": {
         "point": {
            "latitude": -6.195139,
            "longitude": 106.820826
         }
      },
      "taskDuration": "600s"
    }
    EOM

Setel periode waktu target

Periode waktu target adalah periode TimeWindow di mana tugas harus diselesaikan. Misalnya, jika Anda mengomunikasikan jangka waktu pengiriman ke penerima pengiriman, Anda dapat menggunakan target waktu tugas untuk mencatat periode waktu ini dan menghasilkan pemberitahuan atau menganalisis pasca-perjalanan performa terbaik menggunakan kolom ini.

Periode waktu target terdiri dari waktu mulai dan waktu berakhir serta dapat ditetapkan sesuai jenis tugas apa pun. Periode waktu target tidak memengaruhi pemilihan rute perilaku model.

gRPC

Contoh berikut menunjukkan cara menggunakan Library gRPC Java untuk menyetel periode waktu tugas:

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

    DeliveryServiceBlockingStub deliveryService =
      DeliveryServiceGrpc.newBlockingStub(channel);

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

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

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

REST

Untuk menyetel jangka waktu tugas menggunakan HTTP, panggil UpdateTask:

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

&lt;id&gt; adalah ID unik untuk tugas.

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

Isi permintaan harus berisi entity Task:

  • Kolom wajib diisi:

    KolomNilai
    targetTimeWindow Periode waktu saat tugas harus diselesaikan. Setelan ini tidak memengaruhi perilaku perutean

  • Kolom opsional:

    • Tidak ada

Semua kolom lain dalam entity akan diabaikan untuk update.

Contoh perintah curl:

# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=targetTimeWindow" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "targetTimeWindow": {
    "startTime": "2023-03-29T21:00:00Z",
    "endTime": "2023-03-29T23:00:00Z"
  }
}
EOM

Setel konfigurasi visibilitas pelacakan tugas

Visibilitas data di library Shipment Tracking serta data tersebut yang ditampilkan dari panggilan ke GetTaskTrackingInfo dapat dikontrol di per tugas dengan menetapkan TaskTrackingViewConfig pada tugas tersebut. Lihat Tugas kendaraan aktif untuk informasi selengkapnya. Hal ini dapat dilakukan saat membuat atau memperbarui tugas Anda. Berikut adalah contoh pembaruan tugas dengan konfigurasi ini:

gRPC

Contoh berikut menunjukkan cara menggunakan Library gRPC Java untuk mengatur konfigurasi tampilan pelacakan tugas:

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
  .setName(taskName)
  .setTaskTrackingViewConfig(
    TaskTrackingViewConfig.newBuilder()
      .setRoutePolylinePointsVisibility(
        VisibilityOption.newBuilder().setRemainingStopCountThreshold(3))
      .setEstimatedArrivalTimeVisibility(
        VisibilityOption.newBuilder().remainingDrivingDistanceMetersThreshold(5000))
      .setRemainingStopCountVisibility(
        VisibilityOption.newBuilder().setNever(true)))
  .build();

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

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

REST

Untuk menetapkan jendela konfigurasi tampilan pelacakan tugas menggunakan HTTP, panggil UpdateTask:

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

&lt;id&gt; adalah ID unik untuk tugas.

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

Isi permintaan harus berisi entity Task:

  • Kolom wajib diisi:

    KolomNilai
    taskTrackingViewConfig Konfigurasi untuk pelacakan tugas yang menentukan elemen data mana dapat dilihat oleh pengguna akhir dalam situasi apa.

  • Kolom opsional:

    • Tidak ada

Semua kolom lain dalam entity akan diabaikan untuk update.

Contoh perintah curl:

# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=taskTrackingViewConfig" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "taskTrackingViewConfig": {
    "routePolylinePointsVisibility": {
      "remainingStopCountThreshold": 3
    },
    "estimatedArrivalTimeVisibility": {
      "remainingDrivingDistanceMetersThreshold": 5000
    },
    "remainingStopCountVisibility": {
      "never": true
    }
  }
}
EOM

Menetapkan tugas ke kendaraan

Anda menetapkan tugas ke kendaraan pengiriman dengan memperbarui pengurutan tugas untuk kendaraan. Pemesanan tugas untuk kendaraan ditentukan oleh daftar perhentian kendaraan untuk kendaraan pengiriman, dan Anda dapat menetapkan satu atau beberapa tugas ke setiap perhentian kendaraan. Untuk mengetahui detailnya, lihat Memperbarui pengurutan tugas.

Untuk mengubah pengiriman dari satu kendaraan ke kendaraan lainnya, tutup tugas asli lalu membuatnya kembali sebelum menetapkannya menjadi kendaraan baru. Jika Anda memperbarui tugas memesan untuk tugas yang sudah diberikan ke kendaraan lain, Anda akan mendapatkan pesan {i>error.<i}

Perbarui pengurutan tugas

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

Saat Anda memperbarui pengurutan tugas untuk kendaraan, update tersebut juga melakukan hal berikut:

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

Untuk mengubah pengiriman dari satu kendaraan ke kendaraan lainnya, menutup tugas asli lalu membuatnya kembali sebelum menetapkannya menjadi kendaraan baru. Jika Anda memperbarui tugas memesan untuk tugas yang sudah diberikan ke kendaraan lain, Anda akan mendapatkan pesan {i>error.<i}

Anda dapat memperbarui pengurutan tugas kapan saja.

gRPC

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

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
static final String TASK1_ID = "task-756390";
static final String TASK2_ID = "task-849263";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
    .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // 1st stop
       .setStop(VehicleStop.newBuilder()
           .setPlannedLocation(LocationInfo.newBuilder()
               .setPoint(LatLng.newBuilder()
                   .setLatitude(37.7749)
                   .setLongitude(122.4194)))
           .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
           .setState(VehicleStop.State.NEW)))
    .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // 2nd stop
       .setStop(VehicleStop.newBuilder()
           .setPlannedLocation(LocationInfo.newBuilder()
               .setPoint(LatLng.newBuilder()
                   .setLatitude(37.3382)
                   .setLongitude(121.8863)))
           .addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
           .setState(VehicleStop.State.NEW)))
    .build();

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

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

REST

Guna memperbarui pengurutan tugas untuk kendaraan dari lingkungan server, lakukan panggilan REST HTTP ke UpdateDeliveryVehicle:

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

&lt;id&gt; adalah ID unik untuk kendaraan pengiriman di armada Anda yang urutan tugasnya ingin Anda perbarui. Ini adalah pengenal yang yang Anda tentukan saat membuat kendaraan.

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

Isi permintaan harus berisi entity DeliveryVehicle:

  • Kolom wajib diisi:

    KolomNilai
    remainingVehicleJourneySegments Daftar segmen perjalanan untuk tugas sesuai urutan pelaksanaannya. Tugas pertama dalam daftar akan dieksekusi terlebih dahulu.
    remainingVehicleJourneySegments[i].stop Perhentian untuk tugas i dalam daftar.
    remainingVehicleJourneySegments[i].stop.plannedLocation Lokasi yang direncanakan untuk perhentian.
    remainingVehicleJourneySegments[i].stop.tasks Daftar tugas yang akan dilakukan di perhentian kendaraan ini.
    remainingVehicleJourneySegments[i].stop.state State.NEW

  • Kolom opsional:

    • Tidak ada

Semua kolom lain dalam entity akan diabaikan untuk update.

Contoh perintah curl:

# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "remainingVehicleJourneySegments": [
    {
      "stop": {
        "state": "NEW",
        "plannedLocation": {
          "point": {
            "latitude": 37.7749,
            "longitude": -122.084061
          }
        },
        "tasks": [
          {
            "taskId": "${TASK1_ID}"
          }
        ]
      }
    },
    {
      "stop": {
        "state": "NEW",
        "plannedLocation": {
          "point": {
            "latitude": 37.3382,
            "longitude": 121.8863
          }
        },
        "tasks": [
          {
            "taskId": "${TASK2_ID}"
          }
        ]
      }
    }
  ]
}
EOM

Kendaraan sedang dalam perjalanan ke perhentian berikutnya

Fleet Engine harus diberi tahu saat kendaraan berangkat dari perhentian atau mulai navigasi. Anda dapat memberi tahu Fleet Engine dari SDK Driver, atau dari lingkungan server menggunakan gRPC atau REST. Jangan gunakan kedua metode tersebut untuk menghindari race kondisi dan untuk mempertahankan satu sumber yang terpercaya.

gRPC

Contoh berikut menunjukkan cara menggunakan Library gRPC Java untuk memberi tahu Fleet Engine bahwa kendaraan sedang menuju ke perhentian berikutnya.

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

    DeliveryServiceBlockingStub deliveryService =
      DeliveryServiceGrpc.newBlockingStub(channel);

    // Vehicle settings
    DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
        // Next stop marked as ENROUTE
        .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // 1st stop
           .setStop(VehicleStop.newBuilder()
               .setPlannedLocation(LocationInfo.newBuilder()
                   .setPoint(LatLng.newBuilder()
                       .setLatitude(37.7749)
                       .setLongitude(122.4194)))
               .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
               .setState(VehicleStop.State.ENROUTE)))
        // All other stops marked as NEW
        .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // 2nd stop
           .setStop(VehicleStop.newBuilder()
               .setPlannedLocation(LocationInfo.newBuilder()
                   .setPoint(LatLng.newBuilder()
                       .setLatitude(37.3382)
                       .setLongitude(121.8863)))
               .addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
               .setState(VehicleStop.State.NEW)))
        .build();

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

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

REST

Untuk memberi tahu Fleet Engine bahwa kendaraan sedang menuju ke perhentian berikutnya dari lingkungan server, lakukan panggilan REST HTTP ke UpdateDeliveryVehicle:

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

&lt;id&gt; adalah ID unik untuk kendaraan pengiriman di armada Anda yang urutan tugasnya ingin Anda perbarui. Ini adalah pengenal yang yang Anda tentukan saat membuat kendaraan.

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

Isi permintaan harus berisi entity DeliveryVehicle:

  • Kolom wajib diisi:

    KolomNilai
    remainingVehicleJourneySegments Daftar perhentian kendaraan yang tersisa dengan negara bagiannya ditandai sebagai State.NEW. Perhentian pertama dalam daftar harus memiliki status yang ditandai sebagai State.ENROUTE.

  • Kolom opsional:

    • Tidak ada

Semua kolom lain dalam entity akan diabaikan untuk notifikasi.

Contoh perintah curl:

# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "remainingVehicleJourneySegments": [
    {
      "stop": {
        "state": "ENROUTE",
        "plannedLocation": {
          "point": {
            "latitude": 37.7749,
            "longitude": -122.084061
          }
        },
        "tasks": [
          {
            "taskId": "${TASK1_ID}"
          }
        ]
      }
    },
    {
      "stop": {
        "state": "NEW",
        "plannedLocation": {
          "point": {
            "latitude": 37.3382,
            "longitude": 121.8863
          }
        },
        "tasks": [
          {
            "taskId": "${TASK2_ID}"
          }
        ]
      }
    }
  ]
}
EOM

Perbarui lokasi kendaraan

Jika tidak menggunakan Driver SDK untuk memperbarui lokasi kendaraan, Anda dapat membuat panggilan langsung ke Fleet Engine dengan lokasi kendaraan. Untuk setiap kendaraan aktif, Fleet Engine mengharapkan pembaruan lokasi setidaknya sekali setiap menit dan maksimal setiap 5 detik sekali.

gRPC

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

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

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

REST

Untuk memperbarui lokasi kendaraan di Fleet Engine menggunakan HTTP REST, lakukan panggilan ke UpdateDeliveryVehicle:

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

&lt;id&gt; adalah ID unik untuk kendaraan pengiriman di perangkat atau perangkat yang ingin Anda perbarui lokasi. Ini adalah pengenal yang yang Anda tentukan saat membuat kendaraan.

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

Isi permintaan harus berisi entity DeliveryVehicle:

  • Kolom wajib diisi:

    KolomNilai
    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:

    KolomNilai
    lastLocation.supplementalLocationAccuracy Akurasi lokasi yang diberikan, dalam meter.

Contoh perintah curl:

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

Kendaraan tiba di perhentian

Fleet Engine harus diberi tahu saat kendaraan tiba di perhentian. Anda dapat memberi tahu Fleet Engine baik dari SDK Driver, atau dari lingkungan server menggunakan gRPC atau REST. Jangan gunakan kedua metode tersebut untuk menghindari race kondisi dan untuk mempertahankan satu sumber yang terpercaya.

gRPC

Contoh berikut menunjukkan cara menggunakan Library gRPC Java untuk memberi tahu Fleet Engine bahwa kendaraan tiba di perhentian:

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
    // Marking the arrival at stop.
    .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()
       .setStop(VehicleStop.newBuilder()
           .setPlannedLocation(LocationInfo.newBuilder()
               .setPoint(LatLng.newBuilder()
                   .setLatitude(37.7749)
                   .setLongitude(122.4194)))
           .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
           .setState(VehicleStop.State.ARRIVED)))
    // All other remaining stops marked as NEW.
    .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // 2nd stop
       .setStop(VehicleStop.newBuilder()
           .setPlannedLocation(LocationInfo.newBuilder()
               .setPoint(LatLng.newBuilder()
                   .setLatitude(37.3382)
                   .setLongitude(121.8863)))
           .addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
           .setState(VehicleStop.State.NEW))) // Remaining stops must be NEW.
    .build();

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

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

REST

Untuk memberi tahu Fleet Engine tentang kedatangan kendaraan di perhentian dari lingkungan server, lakukan panggilan REST HTTP ke UpdateDeliveryVehicle:

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

&lt;id&gt; adalah ID unik untuk kendaraan pengiriman di armada Anda yang urutan tugasnya ingin Anda perbarui. Ini adalah pengenal yang yang Anda tentukan saat membuat kendaraan.

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

Isi permintaan harus berisi entity DeliveryVehicle:

  • Kolom wajib diisi:

    KolomNilai
    remainingVehicleJourneySegments Perhentian yang telah Anda capai dengan statusnya ditetapkan sebagai {i>State.ARRIVED<i}, diikuti dengan daftar perhentian kendaraan yang tersisa dengan negara bagiannya ditandai sebagai State.NEW.

  • Kolom opsional:

    • Tidak ada

Semua kolom lain dalam entity akan diabaikan untuk update.

Contoh perintah curl:

# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "remainingVehicleJourneySegments": [
    {
      "stop": {
        "state": "ARRIVED",
        "plannedLocation": {
          "point": {
            "latitude": 37.7749,
            "longitude": -122.084061
          }
        },
        "tasks": [
          {
            "taskId": "${TASK1_ID}"
          }
        ]
      }
    },
    {
      "stop": {
        "state": "NEW",
        "plannedLocation": {
          "point": {
            "latitude": 37.3382,
            "longitude": 121.8863
          }
        },
        "tasks": [
          {
            "taskId": "${TASK2_ID}"
          }
        ]
      }
    }
  ]
}
EOM

Kendaraan menyelesaikan perhentian

Fleet Engine harus diberi tahu saat kendaraan berhenti. Hal ini menyebabkan semua tugas yang terkait dengan perhentian agar ditetapkan ke status TUTUP. Anda dapat memberi tahu Fleet Engine dari SDK Driver, atau dari lingkungan server menggunakan gRPC atau REST. Jangan gunakan kedua metode tersebut untuk menghindari kondisi race dan untuk mempertahankan satu sumber tepercaya.

gRPC

Contoh berikut menunjukkan cara menggunakan Library gRPC Java untuk memberi tahu Fleet Engine bahwa kendaraan telah selesai berhenti.

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

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

REST

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

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

&lt;id&gt; adalah ID unik untuk kendaraan pengiriman di armada Anda yang urutan tugasnya ingin Anda perbarui. Ini adalah pengenal yang yang Anda tentukan saat membuat kendaraan.

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

Isi permintaan harus berisi entity DeliveryVehicle:

  • Kolom wajib diisi:

    KolomNilai
    remaining_vehicle_journey_segments Perhentian yang telah Anda selesaikan seharusnya tidak lagi ada dalam daftar perhentian kendaraan yang tersisa.

  • Kolom opsional:

    • Tidak ada

Semua kolom lain dalam entity akan diabaikan untuk update.

Contoh perintah curl:

    # Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
    # environment
    curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
      -H "Content-type: application/json" \
      -H "Authorization: Bearer ${JWT}" \
      --data-binary @- << EOM
    {
      "remainingVehicleJourneySegments": [
        {
          "stop": {
            "state": "NEW",
            "plannedLocation": {
              "point": {
                "latitude": 37.3382,
                "longitude": 121.8863
              }
            },
            "tasks": [
              {
                "taskId": "${TASK2_ID}"
              }
            ]
          }
        }
      ]
    }
    EOM

Memperbarui tugas

Sebagian besar kolom tugas tidak dapat diubah. Namun, Anda dapat memodifikasi status, hasil tugas, waktu hasil tugas, lokasi hasil tugas, dan atribut berdasarkan secara langsung memperbarui entity tugas. Misalnya, dalam kasus di mana tugas belum telah ditugaskan ke sebuah kendaraan, Anda dapat menutup tugas dengan memperbarui negara bagian secara langsung.

gRPC

Ini adalah contoh pembaruan tugas melalui gRPC.

REST

Ini adalah contoh pembaruan tugas melalui REST.

Menutup tugas

Untuk menutup tugas yang telah ditetapkan ke kendaraan, beri tahu Fleet Engine bahwa kendaraan telah menyelesaikan perhentian tempat tugas dilakukan atau menghapusnya dari daftar perhentian kendaraan. Untuk melakukannya, Anda dapat mengatur daftar kendaraan yang tersisa akan berhenti tepat saat memperbarui pengurutan tugas untuk kendaraan.

Jika tugas belum ditetapkan untuk kendaraan dan harus ditutup, perbarui tugas ke status TUTUP. Namun, Anda tidak dapat membuka kembali tugas yang TERTUTUP.

Penutupan tugas tidak mengindikasikan keberhasilan atau kegagalan. Ini menunjukkan bahwa tidak lagi dianggap sedang berlangsung. Untuk pelacakan pengiriman, penting untuk menunjukkan hasil aktual dari suatu tugas sehingga pengiriman hasil dapat ditampilkan.

gRPC

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
  .setName(taskName)
  .setState(Task.State.CLOSED) // You can only directly CLOSE a
  .build();                    // task that is NOT assigned to a vehicle.

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

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

REST

Untuk menandai tugas sebagai ditutup dari lingkungan server, buat panggilan REST HTTP untuk UpdateTask:

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

&lt;id&gt; adalah ID unik untuk tugas.

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

Anda harus menyertakan entity Task dalam isi permintaan:

  • Kolom wajib diisi:

    KolomNilai
    dengan status tersembunyi akhir State.CLOSED

  • Kolom opsional:

    KolomNilai
    taskOutcome Results.Berhasil atau Hasil.FAILED
    taskOutcomeTime Waktu saat tugas diselesaikan.
    taskOutcomeLocation Lokasi tempat tugas diselesaikan. Fleet Engine menjadi default untuk ke lokasi kendaraan terakhir, kecuali jika diganti secara manual oleh penyedia.

Semua kolom lain dalam entity akan diabaikan untuk update.

Contoh perintah curl:

    # Set JWT, PROJECT_ID, and TASK_ID in the local environment
    curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=state,taskOutcome,taskOutcomeTime" \
      -H "Content-type: application/json" \
      -H "Authorization: Bearer ${JWT}" \
      --data-binary @- << EOM
    {
      "state": "CLOSED",
      "taskOutcome": "SUCCEEDED",
      "taskOutcomeTime": "$(date -u --iso-8601=seconds)"
    }
    EOM

Menetapkan hasil tugas dan lokasi hasil

Penutupan tugas tidak menunjukkan keberhasilan atau kegagalan, itu menunjukkan bahwa maka tugas tersebut tidak lagi dianggap berjalan. Untuk pelacakan pengiriman, penting untuk menunjukkan hasil aktual dari suatu tugas sehingga hasil pengiriman dapat ditampilkan dan ada penagihan yang tepat untuk layanan. Setelah ditetapkan, Anda tidak dapat mengubah hasil tugas. Namun, Anda dapat memodifikasi waktu hasil tugas dan lokasi hasil tugas setelah mereka ditetapkan.

Tugas yang berstatus DITUTUP dapat memiliki hasil yang ditetapkan ke SUCCEEDED atau GAGAL. Fleet Engine hanya mengenakan biaya pengiriman dengan status SUCCEEDED.

Saat menandai hasil tugas, Fleet Engine otomatis mengisi lokasi hasil tugas dengan lokasi kendaraan terakhir yang diketahui. Anda dapat mengganti perilaku ini.

gRPC

Anda memiliki opsi untuk menetapkan lokasi hasil tugas saat Anda menetapkan hasil proyek. Menyetel lokasi mencegah Fleet Engine menyetelnya ke {i>default <i}dari lokasi kendaraan. Anda juga dapat menimpa lokasi hasil tugas Fleet Engine tetapkan di lain waktu. Fleet Engine tidak pernah menimpa lokasi hasil tugas yang Anda sediakan. Anda tidak dapat menetapkan lokasi hasil tugas untuk tugas yang belum menetapkan hasil tugas. Anda dapat menetapkan kedua hasil tugas dan lokasi hasil tugas dalam permintaan yang sama.

Contoh berikut menunjukkan cara menggunakan Library gRPC Java untuk menetapkan hasil tugas ke SUCCEEDED dan setel lokasi tempat tugas berada selesai:

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
  .setName(taskName)
  .setTaskOutcome(TaskOutcome.SUCCEEDED)
  .setTaskOutcomeTime(now())
  .setTaskOutcomeLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .build();

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

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

REST

Untuk menandai tugas sebagai selesai dari lingkungan server, lakukan panggilan REST HTTP ke UpdateTask:

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=taskOutcome,taskOutcomeTime,taskOutcomeLocation`

&lt;id&gt; adalah ID unik untuk tugas.

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

Isi permintaan harus berisi entity Task:

  • Kolom wajib diisi:

    KolomNilai
    taskOutcome Results.Berhasil atau Hasil.FAILED

  • Kolom opsional:

    KolomNilai
    taskOutcomeLocation Lokasi tempat tugas diselesaikan. Jika tidak ditetapkan, Fleet Engine defaultnya adalah lokasi kendaraan terakhir.
    taskOutcomeTime Stempel waktu saat tugas selesai.

Semua kolom lain dalam entity akan diabaikan untuk update.

Contoh perintah curl:

# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=taskOutcome,taskOutcomeTime,taskOutcomeLocation" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "taskOutcome": "SUCCEEDED",
  "taskOutcomeTime": "$(date -u --iso-8601=seconds)",
  "taskOutcomeLocation": {
    "point": {
      "latitude": -6.195139,
      "longitude": 106.820826
    }
  }
}
EOM

Mengubah rute pengiriman

Setelah tugas pengiriman dibuat, lokasi yang direncanakan tidak dapat diubah. Untuk mengubah rute pengiriman, tutup tugas pengiriman tanpa menyetelnya hasilnya, dan kemudian membuat tugas baru dengan lokasi yang direncanakan yang telah diperbarui. Setelah membuat tugas baru, tetapkan tugas ke kendaraan yang sama. Untuk selengkapnya informasi lainnya, lihat menutup tugas pengiriman dan menetapkan tugas.

Menggunakan kendaraan pengumpan dan pengiriman

Jika Anda menggunakan kendaraan pengumpan untuk mengangkut kiriman ke kendaraan pengiriman sepanjang hari, buat model transfer pengiriman sebagai tugas penghentian terjadwal untuk kendaraan pengiriman. Untuk memastikan pelacakan lokasi yang akurat, hanya tetapkan tugas pengiriman untuk pengiriman yang ditransfer setelah dimuat ke kendaraan pengiriman. Untuk informasi selengkapnya, lihat perhentian terjadwal.

Status pengiriman toko dan informasi meta lainnya

Saat tugas pengiriman selesai, status dan hasil tugas dicatat dalam tugas. Namun, Anda mungkin ingin memperbarui informasi meta yang spesifik untuk pengiriman. Untuk menyimpan informasi meta lain yang dapat Anda di luar layanan Fleet Engine, gunakan tracking_id yang terkait dengan tugas sebagai kunci dalam tabel eksternal.

Untuk informasi selengkapnya, lihat Masa aktif tugas.

Cari kendaraan

Anda bisa mencari kendaraan dari SDK Driver, atau dari lingkungan server menggunakan gRPC atau REST.

gRPC

Contoh berikut menunjukkan cara menggunakan Library gRPC Java untuk mencari kendaraan:

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Vehicle request
String name = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
GetDeliveryVehicleRequest getVehicleRequest = GetDeliveryVehicleRequest.newBuilder()  // No need for the header
    .setName(name)
    .build();

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

REST

Untuk mencari kendaraan dari lingkungan server, lakukan panggilan REST HTTP ke GetVehicle:

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

&lt;id&gt; adalah ID unik untuk tugas.

&lt;vehicleId&gt; adalah ID kendaraan yang akan dicari.

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

Isi permintaan harus kosong.

Jika pencarian berhasil, isi respons berisi entity kendaraan.

Contoh perintah curl:

# Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
  "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}"

Mencari tugas

Anda dapat mencari tugas dari lingkungan server menggunakan gRPC atau REST. Driver SDK tidak dukungan untuk mencari tugas.

gRPC

Contoh berikut menunjukkan cara menggunakan Library gRPC Java untuk mencari tugas:

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task request
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
GetTaskRequest getTaskRequest = GetTaskRequest.newBuilder()  // No need for the header
    .setName(taskName)
    .build();

try {
  Task task = deliveryService.getTask(getTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;

     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Untuk mencari tugas dari lingkungan server, lakukan panggilan REST HTTP ke GetTask:

`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<taskId>`

&lt;id&gt; adalah ID unik untuk tugas.

&lt;taskId&gt; adalah ID tugas yang akan dicari.

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

Isi permintaan harus kosong.

Jika pencarian berhasil, isi respons akan berisi entity tugas.

Contoh perintah curl:

    # Set JWT, PROJECT_ID, and TASK_ID in the local environment
    curl -H "Authorization: Bearer ${JWT}" \
      "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}"

Mencari informasi tugas pengiriman berdasarkan ID pelacakannya

Anda dapat mencari informasi tugas pengiriman dengan cara berikut, yang masing-masing memiliki tujuan berbeda:

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

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

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

Persyaratan pencarian

  • Informasi pengiriman yang diberikan oleh ID pelacakan mematuhi aturan visibilitas dinyatakan di Kontrol visibilitas lokasi yang dilacak.

  • Gunakan Fleet Engine untuk mencari informasi pengiriman berdasarkan ID pelacakan. Pengemudi SDK tidak mendukung pencarian informasi berdasarkan ID pelacakan. Untuk melakukan ini dengan Fleet Google Cloud Platform, Anda menggunakan lingkungan server atau browser.

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

Mencari dengan Java menggunakan gRPC

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

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

     case PERMISSION_DENIED:
       break;
  }
  return;
}

Mencari menggunakan HTTP

Untuk mencari tugas pengiriman dari browser, buat panggilan REST HTTP untuk GetTaskTrackingInfo:

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

&lt;tracking_id&gt; adalah ID pelacakan yang dikaitkan dengan tugas.

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

Jika pencarian berhasil, isi respons berisi taskTrackingInfo entitas.

Contoh perintah curl:

# Set JWT, PROJECT_ID, and TRACKING_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
  "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/taskTrackingInfo/${TRACKING_ID}"

Membuat daftar tugas

Anda dapat membuat daftar tugas dari lingkungan server atau browser. Driver SDK tidak mendukung tugas daftar.

Mencantumkan tugas meminta akses luas ke tugas. Tugas daftar hanya dimaksudkan untuk pengguna tepercaya. Gunakan Pembaca Armada Pengiriman atau Pengiriman Autentikasi Pengguna Super Token saat membuat permintaan tugas daftar.

Kolom berikut pada tugas yang tercantum telah disamarkan:

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

Tugas yang tercantum dapat difilter menurut sebagian besar properti tugas. Untuk sintaks kueri filter, lihat AIP-160. Daftar berikut menunjukkan tugas yang valid yang dapat Anda gunakan untuk memfilter:

  • attribut
  • delivery_vehicle_id
  • dengan status tersembunyi akhir
  • planned_location
  • task_duration
  • task_outcome
  • task_outcome_location
  • task_outcome_location_source
  • task_outcome_time
  • tracking_id
  • jenis

Gunakan format kolom berikut berdasarkan Proposal Peningkatan Google API:

Jenis Kolom Format Contoh
Stempel waktu RFC-3339 task_outcome_time = 2022-03-01T11:30:00-08:00
Durasi Jumlah detik diikuti dengan s task_duration = 120s
Enum String state = CLOSED AND type = PICKUP
Lokasi point.latitude dan point.longitude planned_location.point.latitude > 36.1 AND planned_location.point.longitude < -122.0

Lihat AIP-160 untuk mengetahui daftar lengkap kueri filter operator.

Jika tidak ada kueri filter yang ditentukan, semua tugas akan dicantumkan.

Daftar tugas diberi nomor halaman. Ukuran halaman dapat ditentukan dalam permintaan tugas daftar. Jika ukuran halaman ditentukan, jumlah tugas yang ditampilkan tidak lebih besar dari ukuran halaman yang ditentukan. Jika tidak ada ukuran halaman, setelan default yang wajar digunakan. Jika ukuran halaman yang diminta melebihi nilai maksimum internal, maka nilai maksimum internal akan digunakan.

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

gRPC

Contoh berikut menunjukkan cara menggunakan Library gRPC Java untuk mencantumkan tugas untuk deliveryKendaraanId dan atribut tugas. Iklan respons masih boleh kosong. Respons kosong menunjukkan bahwa tidak ada Tasks yang yang terkait dengan deliveryKendaraanId yang disediakan.

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Tasks request
String parent = "providers/" + PROJECT_ID;
ListTasksRequest listTasksRequest = ListTasksRequest.newBuilder()  // No need for the header
    .setParent(parent)
    .setFilter("delivery_vehicle_id = 123 AND attributes.foo = true")
    .build();

try {
  ListTasksResponse listTasksResponse = deliveryService.listTasks(listTasksRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;

     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

Untuk menampilkan daftar tugas dari browser, lakukan panggilan REST HTTP ke ListTasks:

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

Untuk menerapkan filter ke tugas yang tercantum, sertakan "filter" Parameter URL dengan kueri filter yang di-escape URL sebagai nilainya.

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

Jika pencarian berhasil, isi respons berisi data dengan struktur berikut:

    // JSON representation
    {
      "tasks": [
        {
          object (Task)
        }
      ],
      "nextPageToken": string,
      "totalSize": integer
    }

Respons yang berhasil masih boleh kosong. Respons kosong menunjukkan bahwa tidak tugas yang ditemukan memenuhi kriteria filter yang ditentukan.

Contoh perintah curl:

    # Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
    curl -H "Authorization: Bearer ${JWT}" \
      "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?filter=state%20%3D%20OPEN%20AND%20delivery_vehicle_id%20%3D%20${VEHICLE_ID}"

Buat daftar kendaraan pengiriman

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

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

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

  • CurrentRouteSegment
  • RemainingVehicleJourneySegments

Anda dapat memfilter daftar kendaraan pengiriman menurut properti attributes. Sebagai Misalnya, untuk mengkueri atribut dengan kunci my_key dan nilai my_value, gunakan attributes.my_key = my_value. Untuk membuat kueri beberapa atribut, gabungkan kueri menggunakan operator AND dan OR yang logis seperti di attributes.key1 = value1 AND attributes.key2 = value2. Lihat AIP-160 untuk mengetahui deskripsi sintaksis kueri filter.

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

Daftar kendaraan pengiriman akan dipaginasi secara default menggunakan ukuran halaman yang wajar. Jika Anda menentukan ukuran halaman, permintaan hanya akan menampilkan jumlah kendaraan yang ditetapkan oleh batas, atau lebih sedikit. Jika ukuran halaman yang diminta melebihi nilai maksimum, maka nilai maksimum internal akan digunakan. Halaman default dan maksimum berukuran sama-sama 100 kendaraan.

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

gRPC

Contoh berikut menunjukkan cara menggunakan Library gRPC Java untuk mencantumkan kendaraan pengiriman di region tertentu dengan atribut tertentu. J respons yang berhasil masih boleh kosong. Ketika itu terjadi, itu berarti tidak ada kendaraan dengan atribut yang ditentukan sudah ada di area pandang yang ditentukan.

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Tasks request
String parent = "providers/" + PROJECT_ID;
ListDeliveryVehiclesRequest listDeliveryVehiclesRequest =
  ListDeliveryVehiclesRequest.newBuilder()  // No need for the header
      .setParent(parent)
      .setViewport(
            Viewport.newBuilder()
              .setHigh(LatLng.newBuilder()
                  .setLatitude(37.45)
                  .setLongitude(-122.06)
                  .build())
              .setLow(LatLng.newBuilder()
                  .setLatitude(37.41)
                  .setLongitude(-122.11)
                  .build())
      .setFilter("attributes.my_key = my_value")
      .build();

try {
  ListDeliveryVehiclesResponse listDeliveryVehiclesResponse =
      deliveryService.listDeliveryVehicles(listDeliveryVehiclesRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
      case NOT_FOUND:
          break;

      case PERMISSION_DENIED:
          break;
  }
  return;
}

REST

Untuk menampilkan daftar tugas dari browser, lakukan panggilan REST HTTP ke ListDeliveryVehicles:

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

Untuk menerapkan filter ke tugas yang tercantum, sertakan "filter" parameter URL dengan Kueri filter yang di-escape URL sebagai nilainya.

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

Jika pencarian berhasil, isi respons berisi data dengan struktur berikut:

// JSON representation
{
  "deliveryVehicles": [
    {
      object (DeliveryVehicle)
    }
  ],
  "nextPageToken": string,
  "totalSize": integer
}

Respons yang berhasil masih boleh kosong. Ketika itu terjadi, itu berarti tidak ada kendaraan pengiriman ditemukan memenuhi area pandang dan kueri filter yang ditentukan.

Contoh perintah curl:

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

Pelacakan pengiriman

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

  • Pilihan: Gunakan Library Pelacakan Pengiriman JavaScript. Library memungkinkan Anda memvisualisasikan lokasi kendaraan dan lokasi yang dilacak di Fleet Engine. Berisi komponen peta JavaScript yang merupakan pengganti langsung untuk objek google.maps.Map standar, dan komponen data untuk terhubung dengan Fleet Engine. Komponen ini memungkinkan Anda memberikan pengalaman pelacakan pengiriman animasi yang dapat disesuaikan dari web atau aplikasi seluler.

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

Kuncinya adalah mencari tugas pengiriman berdasarkan ID pelacakan.

Jika Anda menggunakan Peran Konsumen Pengiriman, semua panggilan API Pengiriman Fleet Engine mengembalikan hanya informasi yang relevan dengan pengirim atau penerima. Lainnya informasi dalam respons disamarkan. Anda bertanggung jawab untuk melakukan otentikasi terhadap pengguna akhir. Selanjutnya, informasi lokasi difilter berdasarkan tugas yang sudah dilakukan. Selama tugas ketidaktersediaan, tidak ada informasi lokasi yang dibagikan dengan pengguna akhir.

Logging

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

Peran dan Token Otorisasi

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

Untuk informasi selengkapnya, lihat Autentikasi dan Otorisasi.

Memecahkan masalah umum

Periksa bagian berikut untuk mendapatkan bantuan jika Anda mengalami masalah apa pun.

Ketahanan

Fleet Engine tidak dianggap sebagai sumber kebenaran. Anda bertanggung jawab untuk memulihkan status sistem Anda, jika perlu, tanpa bergantung pada Fleet Engine.

Status hilang di Fleet Engine

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

Dalam skenario kegagalan bencana yang sangat tidak mungkin terjadi di Fleet Engine, Anda mungkin perlu membuat ulang sebagian besar atau semua kendaraan dan tugas. Jika rasio pembuatan menjadi terlalu tinggi, beberapa permintaan mungkin gagal lagi karena masalah kuota Pemeriksaan kuota diterapkan untuk menghindari serangan denial of service (DOS). Dalam hal ini, perlambat laju pembuatan ulang menggunakan strategi backoff untuk percobaan ulang.

Status hilang di aplikasi driver

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

FAQ

Bagaimana jika pengemudi berhenti untuk melakukan tugas secara tidak berurutan?

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