Mulai menggunakan Fleet Engine

Fleet Engine On-demand Rides and Deliveries API memungkinkan Anda mengelola perjalanan dan status kendaraan untuk aplikasi Progres Perjalanan dan Pesanan. Layanan ini menangani transaksi antara Driver SDK, Consumer SDK, dan layanan backend Anda, yang dapat berkomunikasi dengan Fleet Engine dengan melakukan panggilan gRPC atau REST.

Prasyarat

Untuk pengembangan, pastikan Anda menginstal Cloud SDK (gcloud) dan diautentikasi ke project Anda.

Catatan: Pertimbangkan untuk menggunakan lingkungan interaktif Cloud Shell tempat Cloud SDK dan dependensi lainnya seperti curl sudah diinstal. Lihat Menggunakan Cloud Shell.

shell

gcloud auth login

Anda akan melihat pesan berhasil seperti:

You are now logged in as [[e-mail]].
Your current project is [project-id].  You ...

Catatan: Edit nilai variabel dalam blok kode untuk menyiapkan perintah berikutnya sehingga dapat langsung disalin dan ditempelkan.

Pastikan API Fleet Engine Solusi Perjalanan dan Pengiriman On-demand dikonfigurasi dengan benar.

shell

gcloud --project=project-id services enable fleetengine.googleapis.com

Jika perintah ini menyebabkan error, hubungi administrator project dan perwakilan dukungan Google Anda untuk mendapatkan akses.

Logging

Feet Engine dapat menulis pesan log tentang panggilan API yang diterimanya ke dalam log platform Google Cloud. Lihat dokumentasi Cloud Logging untuk mengetahui ringkasan cara membaca dan menganalisis log.

Logging mungkin tidak diaktifkan secara default untuk project yang dibuat sebelum 10 Februari 2022. Lihat dokumentasi logging untuk mengetahui detail selengkapnya.

Library Klien

Kami menerbitkan library klien dalam beberapa bahasa pemrograman umum. Library ini akan membantu memberikan pengalaman developer yang lebih baik dibandingkan REST atau gRPC mentah. Untuk mengetahui petunjuk cara mendapatkan library klien bagi aplikasi server Anda, lihat Library Klien.

Contoh Java dalam dokumentasi ini mengasumsikan pemahaman tentang gRPC.

Autentikasi dan Otorisasi

Anda dapat mengonfigurasi kemampuan yang disediakan oleh Progres Perjalanan dan Pesanan melalui Konsol Google Cloud. API dan SDK ini memerlukan penggunaan Token Web JSON yang telah ditandatangani menggunakan akun layanan yang dibuat dari Konsol Cloud.

Penyiapan project cloud

Untuk menyiapkan project cloud, buat project Anda terlebih dahulu, lalu buat akun layanan.

Untuk membuat project Google Cloud:

1. Membuat Project Google Cloud menggunakan Konsol Google Cloud.
2. Dengan menggunakan Dashboard APIs and Services, aktifkan Local Rides and Deliveries API.

Akun layanan dikaitkan dengan satu atau beberapa peran. Token ini digunakan untuk membuat Token Web JSON yang memberikan kumpulan izin yang berbeda, bergantung pada perannya. Biasanya, untuk mengurangi kemungkinan penyalahgunaan, Anda dapat membuat beberapa akun layanan, masing-masing dengan serangkaian peran minimum yang diperlukan.

Progres Perjalanan dan Pesanan menggunakan peran berikut:

Role	Deskripsi
Pengguna SDK Konsumen Fleet Engine roles/fleetengine.consumerSdkUser	Memberikan izin untuk mencari kendaraan dan mengambil informasi tentang kendaraan dan perjalanan. Token yang dibuat oleh akun layanan dengan peran ini biasanya digunakan dari perangkat seluler aplikasi konsumen pengiriman atau transportasi online Anda.
Pengguna SDK Driver Fleet Engine roles/fleetengine.driverSdkUser	Memberikan izin untuk memperbarui lokasi dan rute kendaraan serta untuk mengambil informasi tentang kendaraan dan perjalanan. Token yang dibuat oleh akun layanan dengan peran ini biasanya digunakan dari perangkat seluler aplikasi pengemudi pengiriman atau transportasi online Anda.
Pengguna Super Layanan Fleet Engine roles/fleetengine.serviceSuperUser	Memberikan izin ke semua API kendaraan dan perjalanan. Token yang dibuat oleh akun layanan dengan peran ini biasanya digunakan dari server backend Anda.

Misalnya, buat akun layanan untuk ketiga peran tersebut dan tetapkan perannya masing-masing.

gcloud --project=project-id iam service-accounts create fleet-engine-consumer-sdk
gcloud projects add-iam-policy-binding project-id \
       --member=serviceAccount:[e-mail] \
       --role=roles/fleetengine.consumerSdkUser

gcloud --project=project-id iam service-accounts create fleet-engine-driver-sdk
gcloud projects add-iam-policy-binding project-id \
       --member=serviceAccount:[e-mail] \
       --role=roles/fleetengine.driverSdkUser

gcloud --project=project-id iam service-accounts create fleet-engine-su
gcloud projects add-iam-policy-binding project-id \
       --member=serviceAccount:[e-mail] \
       --role=roles/fleetengine.serviceSuperUser

Driver dan Consumer SDK dibuat berdasarkan peran standar ini.

Atau, Anda dapat membuat peran khusus yang memungkinkan serangkaian izin arbitrer dipaketkan bersama. SDK Driver dan Konsumen akan menampilkan pesan error setiap kali izin yang diperlukan tidak ada. Oleh karena itu, kami sangat merekomendasikan untuk menggunakan kumpulan peran standar yang ditampilkan di atas dan tidak menggunakan peran khusus.

Untuk memudahkan Anda, jika Anda perlu membuat token JWT untuk klien yang tidak tepercaya, menambahkan pengguna ke Service Account Token Creator Role akan memungkinkan mereka membuat token dengan alat command line gcloud.

gcloud projects add-iam-policy-binding project-id \
       --member=user:[e-mail] \
       --role=roles/iam.serviceAccountTokenCreator

Dengan [e-mail] adalah email yang digunakan untuk melakukan autentikasi dengan gcloud (gcloud auth list --format='value(account)').

Catatan: hal ini memberikan izin kepada penerima hibah untuk meniru identitas akun layanan apa pun dalam project. Untuk menetapkan izin yang lebih terperinci, ikuti dokumentasi IAM tentang cakupan peran ke akun layanan tertentu.

Library Auth Fleet Engine

Fleet Engine menggunakan JSON Web Token (JWT) untuk membatasi akses ke Fleet Engine API. Library Auth Fleet Engine baru, tersedia di GitHub, menyederhanakan konstruksi JWT Fleet Engine dan menandatanganinya dengan aman.

Library ini memberikan manfaat berikut:

• Menyederhanakan proses pembuatan Token Fleet Engine.
• Menyediakan mekanisme penandatanganan token selain menggunakan file kredensial (seperti meniru identitas akun layanan).
• Melampirkan token bertanda tangan ke permintaan keluar yang dibuat dari stub gRPC atau klien GAPIC.

Penting: Sebaiknya gunakan Library Auth Fleet Engine dengan semua implementasi Java.

Membuat JSON Web Token (JWT) untuk otorisasi

Jika tidak menggunakan Fleet Engine Auth Library, Token Web JSON (JWT) harus dibuat langsung dalam codebase Anda. Hal ini mengharuskan Anda memiliki pemahaman yang mendalam tentang JWT dan bagaimana kaitannya dengan Fleet Engine. Inilah alasan kami SANGAT merekomendasikan penggunaan Library Auth Fleet Engine.

Dalam Fleet Engine, JSON Web Token (JWT) memberikan autentikasi jangka pendek dan memastikan bahwa perangkat hanya dapat mengubah kendaraan, perjalanan, atau tugas yang diotorisasi. JWT berisi header dan bagian klaim. Bagian header berisi informasi seperti kunci pribadi yang akan digunakan (diperoleh dari akun layanan) dan algoritma enkripsi. Bagian klaim berisi informasi seperti waktu pembuatan token, waktu aktif token, layanan yang aksesnya diklaim, dan informasi otorisasi lainnya untuk menentukan cakupan akses; misalnya, ID kendaraan.

Bagian header JWT berisi kolom-kolom berikut:

Kolom	Deskripsi
alg	Algoritma yang akan digunakan. `RS256`.
typ	Jenis token. `JWT`.
anak	ID kunci pribadi akun layanan Anda. Anda dapat menemukan nilai ini di kolom `private_key_id` pada file JSON akun layanan Anda. Pastikan untuk menggunakan kunci dari akun layanan dengan tingkat izin yang benar.

Bagian klaim JWT berisi kolom-kolom berikut:

Kolom	Deskripsi
iss	Alamat email akun layanan Anda.
sub	Alamat email akun layanan Anda.
aud	SERVICE_NAME akun layanan Anda, dalam hal ini https://fleetengine.googleapis.com/
iat	Stempel waktu saat token dibuat, yang ditentukan dalam detik yang telah berlalu sejak 00:00:00 UTC, 1 Januari 1970. Tunggu 10 menit agar miring. Jika stempel waktu sudah terlalu lampau, atau di masa mendatang, server mungkin melaporkan error.
exp	Stempel waktu saat token berakhir, yang ditentukan dalam detik yang telah berlalu sejak 00:00:00 UTC, 1 Januari 1970. Permintaan gagal jika stempel waktu lebih dari satu jam.
authorization	Bergantung pada kasus penggunaannya, kode dapat berisi `vehicleid` atau `tripid`.

Membuat token JWT mengacu pada penandatanganannya. Untuk petunjuk dan contoh kode guna membuat dan menandatangani JWT, lihat Otorisasi akun layanan tanpa OAuth. Selanjutnya, Anda dapat melampirkan token yang ditandatangani ke panggilan gRPC atau metode lain yang digunakan untuk mengakses Fleet Engine.

Klaim JWT

Saat membuat payload JWT, tambahkan klaim tambahan di bagian otorisasi dengan kunci vehicleid atau tripid yang ditetapkan ke nilai ID kendaraan atau ID perjalanan yang digunakan untuk melakukan panggilan.

Driver SDK selalu menggunakan klaim vehicleid, baik yang beroperasi di perjalanan atau kendaraan. Backend Fleet Engine menjamin bahwa kendaraan dikaitkan dengan perjalanan yang diminta sebelum melakukan modifikasi.

Consumer SDK selalu menggunakan klaim tripid.

Penyedia Transportasi Online atau Pengiriman harus menggunakan vehicleid atau tripid dengan "*" untuk cocok dengan semua Kendaraan dan Perjalanan. Perlu diperhatikan bahwa JWT dapat berisi kedua token, meskipun tidak diperlukan, yang dapat menyederhanakan implementasi penandatanganan token.

Kasus Penggunaan JWT

Berikut ini contoh token untuk Server penyedia:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_provider_service_account"
}
.
{
  "iss": "[e-mail]",
  "sub": "[e-mail]",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "authorization": {
     "vehicleid": "*",
     "tripid": "*"
   }
}

Berikut ini contoh token untuk Consumer app:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_consumer_service_account"
}
.
{
  "iss": "[e-mail]",
  "sub": "[e-mail]",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "authorization": {
     "tripid": "trip_54321"
   }
}

Berikut ini contoh token untuk Driver app:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_driver_service_account"
}
.
{
  "iss": "[e-mail]",
  "sub": "[e-mail]",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "authorization": {
     "vehicleid": "driver_12345"
   }
}

• Untuk kolom kid di header, tentukan ID kunci pribadi akun layanan Anda. Anda dapat menemukan nilai ini di kolom private_key_id pada file JSON akun layanan.
• Untuk kolom iss dan sub, tentukan alamat email akun layanan Anda. Anda dapat menemukan nilai ini di kolom client_email pada file JSON akun layanan.
• Untuk kolom aud, tentukan https://SERVICE_NAME/.
• Untuk kolom iat, gunakan stempel waktu saat token dibuat, yang ditentukan sebagai detik yang berlalu sejak 00:00:00 UTC, 1 Januari 1970. Tunggu 10 menit agar miring. Jika stempel waktu sudah terlalu lampau, atau di masa mendatang, server mungkin akan melaporkan error.
• Untuk kolom exp, gunakan stempel waktu saat masa berlaku token berakhir, yang ditentukan sebagai detik sejak 00:00:00 UTC, 1 Januari 1970. Nilai maksimum yang diizinkan adalah iat + 3600.

Saat menandatangani JWT untuk diteruskan ke perangkat seluler, pastikan Anda menggunakan akun layanan untuk peran Driver atau Consumer SDK. Jika tidak, perangkat seluler dapat mengubah status yang seharusnya tidak dimilikinya.

Demikian pula, saat menandatangani JWT yang akan digunakan untuk panggilan istimewa, pastikan Anda menggunakan akun layanan dengan peran Super User. Jika tidak, operasi akan gagal.

Menghasilkan JWT untuk pengujian

Membuat token dari terminal dapat berguna saat melakukan pengujian.

Untuk mengikuti langkah-langkah ini, akun pengguna Anda harus memiliki peran Service Account Token Creator:

gcloud projects add-iam-policy-binding project-id \
       --member=user:[e-mail] \
       --role=roles/iam.serviceAccountTokenCreator

Buat file baru bernama unsigned_token.json dengan konten di bawah ini. Properti iat adalah waktu saat ini dalam jumlah detik setelah epoch, yang dapat diambil dengan menjalankan date +%s di terminal Anda. Properti exp adalah waktu habis masa berlaku dalam jumlah detik setelah epoch, yang dapat dihitung dengan menambahkan 3.600 ke iat. Waktu habis masa berlaku tidak boleh lebih dari satu jam di masa mendatang.

{
  "aud": "https://fleetengine.googleapis.com/",
  "iss": "[e-mail]",
  "sub": "[e-mail]",
  "iat": iat,
  "exp": exp,
  "authorization": {
     "vehicleid": "*",
     "tripid": "*"
   }
}

Lalu, jalankan perintah gcloud berikut untuk menandatangani token atas nama akun layanan Super User Anda:

gcloud beta iam service-accounts sign-jwt --iam-account=[e-mail] unsigned_token.json signed_token.jwt

JWT berenkode Base64 yang ditandatangani sekarang akan disimpan dalam file signed_token.jwt. Token valid selama satu jam ke depan.

Sekarang Anda dapat menguji token dengan menjalankan perintah curl terhadap endpoint REST Kendaraan Daftar:

curl -X GET "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles" -H "Authorization: Bearer $(cat signed_token.jwt)"

Kendaraan dan siklus prosesnya

Kendaraan adalah entitas yang mewakili pasangan pengemudi-kendaraan. Saat ini, Pengemudi dan Kendaraan tidak dapat dilacak secara terpisah. Penyedia Transportasi Online atau Pengiriman membuat Kendaraan menggunakan ID Penyedia (yang harus sama dengan Project ID Project Google Cloud yang berisi akun layanan yang digunakan untuk memanggil Fleet Engine API) dan ID Kendaraan milik Transportasi Umum atau Penyedia Pengiriman.

Kendaraan yang tidak diupdate melalui UpdateVehicle setelah tujuh hari akan otomatis dihapus. Akan terjadi error saat memanggil CreateVehicle dengan pasangan ID Penyedia/ID Kendaraan yang sudah ada. Kasus kendaraan yang tidak sering diperbarui dapat ditangani dengan dua cara: sering memanggil CreateVehicle dengan pasangan ID Penyedia/ID Kendaraan yang diharapkan dan menghapus error jika Kendaraan sudah ada; atau, memanggil CreateVehicle setelah UpdateVehicle akan menampilkan error NOT_FOUND.

Pembaruan lokasi kendaraan

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

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

Jenis kendaraan

Entity Kendaraan berisi kolom VehicleType yang wajib diisi, yang berisi enum Category yang dapat ditentukan sebagai AUTO, TAXI, TRUCK, TWO_WHEELER, BICYCLE, atau PEDESTRIAN. Jenis kendaraan dapat berfungsi sebagai kriteria filter di SearchVehicles dan ListVehicles.

Semua pemilihan rute untuk kendaraan akan menggunakan RouteTravelMode yang sesuai jika kategori ditetapkan ke AUTO, TWO_WHEELER, BICYCLE, atau PEDESTRIAN. Jika kategori ditetapkan ke TAXI atau TRUCK, perutean akan diperlakukan sama dengan mode AUTO.

Atribut kendaraan

Entitas Kendaraan berisi kolom berulang VehicleAttribute. Atribut ini tidak ditafsirkan oleh Fleet Engine. SearchVehicles API menyertakan kolom untuk mewajibkan Vehicles yang cocok harus berisi semua atribut yang disertakan dan ditetapkan ke nilai yang ditentukan.

Perlu diperhatikan bahwa kolom atribut merupakan tambahan untuk beberapa kolom lain yang didukung dalam pesan Vehicle, seperti vehicle_type dan supported_trip_types.

Sisa titik jalan kendaraan

Entity Vehicle berisi kolom TripWaypoint (RPC | REST), yang disebut waypoints(RPC | REST). Kolom ini menyertakan titik jalan yang tersisa dalam perjalanan, sesuai urutan kendaraan. Fleet Engine menghitung kolom ini saat perjalanan ditetapkan ke kendaraan, dan memperbaruinya saat perjalanan mengubah statusnya. Titik jalan ini dapat diidentifikasi dengan kolom TripId dan kolom WaypointType.

Memperluas kelayakan kendaraan untuk pencocokan

Biasanya, layanan Transportasi Online atau Penyedia Pengiriman bertanggung jawab untuk mencocokkan permintaan perjalanan dengan kendaraan. Layanan dapat menggunakan atribut kendaraan untuk menyertakan kendaraan dalam jumlah penelusuran yang lebih besar. Misalnya, penyedia dapat menerapkan satu set ke atribut yang sesuai dengan tingkat keuntungan atau kemampuan yang disediakan oleh kendaraan. Misalnya, tiga level dapat berupa sekumpulan atribut dengan nilai boolean: is_bronze_level, is_silver_level, dan is_gold_level. Sebuah kendaraan bisa memenuhi syarat untuk ketiganya. Saat Fleet Engine menerima permintaan untuk perjalanan yang memerlukan kemampuan level silver, penelusuran akan menyertakan kendaraan tersebut. Menggunakan atribut dengan cara ini mencakup kendaraan yang menawarkan berbagai kemampuan.

Ada dua cara untuk memperbarui atribut kendaraan. Salah satunya adalah UpdateVehicle API. Saat menggunakan API ini, seluruh kumpulan Atribut Kendaraan ditetapkan ke nilai. Anda tidak dapat memperbarui satu atribut saja. Metode lainnya adalah UpdateVehicleAttributes API. Metode ini hanya memerlukan atribut yang akan diperbarui. Atribut yang disertakan dalam permintaan akan ditetapkan ke nilai baru atau ditambahkan; atribut yang tidak ditentukan tidak akan diubah.

CARA MENGGUNAKAN: Membuat Kendaraan

Entity Vehicle harus dibuat untuk setiap Kendaraan agar dapat dilacak di fleet.

Gunakan endpoint CreateVehicle dengan CreateVehicleRequest untuk membuat Kendaraan.

Catatan: CreateVehicle memerlukan akun dengan peran Fleet Engine Super User.

provider_id dari Vehicle harus berupa Project ID (misalnya, my-on-demand-project) dari Project Google Cloud yang berisi Akun Layanan yang akan digunakan untuk memanggil Fleet Engine. Perhatikan bahwa meskipun beberapa akun layanan dapat mengakses Fleet Engine untuk Penyedia Transportasi Online atau Pengiriman yang sama, Fleet Engine saat ini tidak mendukung akun layanan dari beberapa Project Google Cloud yang mengakses Vehicles yang sama.

Vehicle dapat dibuat dalam status OFFLINE atau ONLINE. Jika dibuat, ONLINE dapat segera ditampilkan sebagai respons terhadap kueri SearchVehicles.

last_location awal dapat disertakan dalam panggilan CreateVehicle. Meskipun diizinkan, Vehicle tidak boleh dibuat dalam status ONLINE tanpa last_location.

Lihat Jenis Kendaraan untuk mengetahui detail tentang kolom jenis kendaraan.

Lihat Atribut Kendaraan untuk mengetahui detail tentang kolom atribut.

Nilai yang ditampilkan dari CreateVehicle adalah entity Vehicle yang dibuat.

Contoh

shell

curl -X POST \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles?vehicleId=vid-8241890" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
    "vehicleState": "OFFLINE",
    "supportedTripTypes": ["EXCLUSIVE"],
    "maximumCapacity": 4,
    "vehicleType": {"category": "AUTO"},
    "attributes": [{"key": "on_trip", "value": "false"}]
}
EOM

Lihat referensi providers.vehicles.create.

Java

static final String PROJECT_ID = "project-id";

VehicleServiceBlockingStub vehicleService =
    VehicleService.newBlockingStub(channel);

String parent = "providers/" + PROJECT_ID;
Vehicle vehicle = Vehicle.newBuilder()
    .setVehicleState(VehicleState.OFFLINE)  // Initial state
    .addSupportedTripTypes(TripType.EXCLUSIVE)
    .setMaximumCapacity(4)
    .setVehicleType(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
    .addAttributes(VehicleAttribute.newBuilder()
        .setKey("on_trip").setValue("false"))  // Opaque to the Fleet Engine
    // Add .setBackToBackEnabled(true) to make this vehicle eligible for trip
    // matching while even if it is on a trip.  By default this is disabled.
    .build();

CreateVehicleRequest createVehicleRequest =
    CreateVehicleRequest.newBuilder()  // no need for the header
        .setParent(parent)
        .setVehicleId("vid-8241890")  // Vehicle ID assigned by Rideshare or Delivery Provider
        .setVehicle(vehicle)  // Initial state
        .build();

// In this case, the Vehicle is being created in the OFFLINE state and
// no initial position is being provided.  When the Driver App checks
// in with the Rideshare or Delivery Provider, the state can be set to ONLINE and
// the Driver App will update the Vehicle Location.

try {
  Vehicle createdVehicle =
      vehicleService.createVehicle(createVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case ALREADY_EXISTS:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}
// If no Exception, Vehicle created successfully.

Log platform Google Cloud untuk pembuatan Kendaraan

Fleet Engine API menulis entri log melalui log platform Google Cloud saat panggilan ke endpoint CreateVehicle diterima. Entri log menyertakan informasi tentang nilai dalam permintaan CreateVehicle. Jika panggilan berhasil, informasi tentang Vehicle yang ditampilkan juga akan disertakan.

shell

gcloud --project=project-id logging read --freshness=1h '
  jsonPayload.request.vehicleId="vid-8241890"
  jsonPayload.@type="type.googleapis.com/maps.fleetengine.v1.CreateVehicleLog"
'

Harus mencetak data yang mirip dengan berikut ini:

---
insertId: c2cf4d3a180251c1bdb892137c14f022
jsonPayload:
  '@type': type.googleapis.com/maps.fleetengine.v1.CreateVehicleLog
  request:
    vehicle:
      attributes:
      - key: on_trip
        value: 'false'
      maximumCapacity: 4
      state: VEHICLE_STATE_OFFLINE
      supportedTrips:
      - EXCLUSIVE_TRIP
      vehicleType:
        vehicleCategory: AUTO
    vehicleId: vid-8241890
  response:
    attributes:
    - key: on_trip
      value: 'false'
    availableCapacity: 4
    currentRouteSegmentHandle: AdSiwAwCO9gZ7Pw5UZZimOXOo41cJTjg/r3SuwVPQmuuaV0sU3+3UCY+z53Cl9i6mWHLoCKbBt9Vsj5PMRgOJ8zX
    maximumCapacity: 4
    name: providers/project-id/vehicles/vid-8241890
    state: VEHICLE_STATE_OFFLINE
    supportedTrips:
    - EXCLUSIVE_TRIP
    vehicleType:
      vehicleCategory: AUTO
labels:
  vehicle_id: vid-8241890
logName: projects/project-id/logs/fleetengine.googleapis.com%2Fcreate_vehicle
receiveTimestamp: '2021-09-22T03:25:16.361159871Z'
resource:
  labels:
    location: global
    resource_container: projects/project-id
  type: fleetengine.googleapis.com/Fleet
timestamp: '2021-09-22T03:25:15.724998Z'

Notifikasi Cloud Pub/Sub untuk pembuatan Kendaraan

Fleet Engine API memublikasikan notifikasi melalui Cloud Pub/Sub saat kendaraan baru dibuat. Untuk menerima notifikasi ini, ikuti petunjuk di sini.

CARA KERJA: Memperbarui lokasi Kendaraan

Jika tidak menggunakan Driver SDK untuk memperbarui lokasi kendaraan, Anda dapat melakukan panggilan langsung ke Fleet Engine dengan lokasi kendaraan. Untuk kendaraan aktif, Fleet Engine mengharapkan pembaruan lokasi minimal sekali setiap menit dan paling banyak sekali setiap 5 detik. Update ini hanya memerlukan hak istimewa Pengguna SDK Pengemudi Fleet Engine.

Contoh

shell

curl -X PUT \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=last_location" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
    "supplementalLocation": {"latitude": 12.1, "longitude": 14.5},
    "supplementalLocationTime": "$(date -u --iso-8601=seconds)",
    "supplementalLocationSensor": "CUSTOMER_SUPPLIED_LOCATION",
    "supplementalLocationAccuracy": 15
}
EOM

Lihat referensi providers.vehicles.update.

Java

static final String PROJECT_ID = "project-id";
static final String VEHICLE_ID = "vid-8241890";

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

String vehicleName = "providers/" + PROJECT_ID + "/vehicles/" + VEHICLE_ID;
Vehicle updatedVehicle = Vehicle.newBuilder()
    .setLastLocation(VehicleLocation.newBuilder()
        .setSupplementalLocation(LatLng.newBuilder()
            .setLatitude(37.3382)
            .setLongitude(121.8863))
        .setSupplementalLocationTime(now())
        .setSupplementalLocationSensor(LocationSensor.CUSTOMER_SUPPLIED_LOCATION)
        .setSupplementalLocationAccuracy(DoubleValue.of(15.0)))  // Optional)
    .build();

UpdateVehicleRequest updateVehicleRequest = UpdateVehicleRequest.newBuilder()
    .setName(vehicleName)
    .setVehicle(updatedVehicle)
    .setUpdateMask(FieldMask.newBuilder()
        .addPaths("last_location"))
    .build();

try {
  Vehicle updatedVehicle =
      vehicleService.updateVehicle(updateVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:
      // Most implementations will call CreateVehicle in this case
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}
// If no Exception, Vehicle updated successfully.

CARA KERJA: Memperbarui kolom Kendaraan lainnya

Pembaruan pada atribut lain status Kendaraan lebih jarang terjadi daripada pembaruan posisi. Pembaruan untuk atribut selain last_location memerlukan hak istimewa Pengguna Super Perangkat Armada.

UpdateVehicleRequest menyertakan update_mask untuk menunjukkan kolom yang akan diperbarui. Perilaku kolom ini seperti dalam dokumentasi Protobuf untuk mask kolom.

Catatan: Kolom update_mask harus selalu ditetapkan. Jika kolom update_mask tidak ditetapkan, semua kolom akan ditulis secara default. Hal ini dapat mengakibatkan perilaku yang tidak diinginkan.

Seperti disebutkan dalam Atribut Kendaraan, memperbarui kolom attributes mengharuskan penulisan semua atribut dipertahankan. Anda tidak dapat hanya memperbarui nilai satu pasangan nilai kunci dalam panggilan UpdateVehicle. Untuk memperbarui nilai atribut tertentu, UpdateVehicleAttributes API dapat digunakan.

Contoh

Contoh ini mengaktifkan back_to_back.

shell

curl -X PUT \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=vehicle_state,attributes,back_to_back_enabled" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
    "vehicleState": "ONLINE",
    "attributes": [
      {"key": "on_trip", "value": "true"},
      {"key": "cash_only", "value": "false"}
    ],
    "backToBackEnabled": true
}
EOM

Lihat referensi providers.vehicles.update.

Java

static final String PROJECT_ID = "project-id";
static final String VEHICLE_ID = "vid-8241890";

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

String vehicleName = "providers/" + PROJECT_ID + "/vehicles/" + VEHICLE_ID;
Vehicle updatedVehicle = Vehicle.newBuilder()
    .setVehicleState(VehicleState.ONLINE)
    .addAllAttributes(ImmutableList.of(
        VehicleAttribute.newBuilder().setKey("on_trip").setValue("true").build(),
        VehicleAttribute.newBuilder().setKey("cash_only").setValue("false").build()))
    .setBackToBackEnabled(true)
    .build();

UpdateVehicleRequest updateVehicleRequest = UpdateVehicleRequest.newBuilder()
    .setName(vehicleName)
    .setVehicle(updatedVehicle)
    .setUpdateMask(FieldMask.newBuilder()
        .addPaths("vehicle_state")
        .addPaths("attributes")
        .addPaths("back_to_back_enabled"))
    .build();

// Attributes and vehicle state are being updated, so both are
// included in the field mask.  Note that of on_trip were
// not being updated, but rather cash_only was being changed,
// the desired value of "on_trip" would still need to be written
// as the attributes are completely replaced in an update operation.

try {
  Vehicle updatedVehicle =
      vehicleService.updateVehicle(updateVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:
      // Most implementations will call CreateVehicle in this case
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}
// If no Exception, Vehicle updated successfully.

Log platform Google Cloud untuk Pembaruan Kendaraan

Fleet Engine API menulis entri log melalui log platform Google Cloud saat panggilan ke endpoint UpdateVehicle diterima. Entri log menyertakan informasi tentang nilai dalam permintaan UpdateVehicle. Jika panggilan berhasil, informasi tentang Vehicle yang ditampilkan juga akan disertakan.

shell

gcloud --project=project-id logging read --freshness=1h '
  jsonPayload.request.vehicleId="vid-8241890"
  jsonPayload.@type="type.googleapis.com/maps.fleetengine.v1.UpdateVehicleLog"
'

Notifikasi Cloud Pub/Sub untuk info terbaru Kendaraan

Fleet Engine API memublikasikan notifikasi melalui Cloud Pub/Sub saat kendaraan yang ada diupdate. Untuk menerima notifikasi ini, ikuti petunjuk di sini.

CARA KERJA: Menelusuri kendaraan

Fleet Engine mendukung pencarian kendaraan. SearchVehicles API memungkinkan Anda menemukan pengemudi di sekitar yang paling sesuai untuk melakukan tugas seperti menyewa transportasi atau permintaan pengiriman. SearchVehicles API menampilkan daftar peringkat pengemudi yang cocok dengan atribut tugas dengan atribut kendaraan di armada Anda. Untuk informasi selengkapnya, lihat Menemukan pengemudi di sekitar.

Contoh

Saat menelusuri kendaraan yang tersedia, Fleet Engine mengecualikan kendaraan pada perjalanan aktif secara default. Layanan Transportasi Online atau Penyedia Pengiriman harus secara eksplisit menyertakannya dalam permintaan penelusuran. Contoh berikut menunjukkan cara menyertakan kendaraan tersebut dalam penelusuran kendaraan yang cocok dengan perjalanan dari Grand Indonesia East Mall ke Balai Sidang Jakarta Convention Center.

shell

Pertama-tama, perbarui lokasi kendaraan yang kami buat pada langkah sebelumnya agar memenuhi syarat. Pada kenyataannya, hal ini akan dilakukan oleh Driver SDK yang berjalan pada perangkat Android atau iOS di dalam kendaraan.

curl -X PUT \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=last_location,attributes" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
  "lastLocation": {
    "updateTime": "$( date -u +"%Y-%m-%dT%H:%M:%SZ" )",
    "location": {
      "latitude": "-6.195139",
      "longitude": "106.820826"
    }
  },
  "attributes": [{"key": "on_trip", "value": "false"}]
}
EOM

Melakukan penelusuran akan menghasilkan setidaknya kendaraan tersebut.

curl -X POST \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles:search" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
  "pickupPoint": {
    "point": {"latitude": "-6.195139", "longitude": "106.820826"}
  },
  "dropoffPoint": {
    "point": {"latitude": "-6.1275", "longitude": "106.6537"}
  },
  "pickupRadiusMeters": 2000,
  "count": 10,
  "minimumCapacity": 2,
  "tripTypes": ["EXCLUSIVE"],
  "vehicleTypes": [{"category": "AUTO"}],
  "filter": "attributes.on_trip=\"false\"",
  "orderBy": "PICKUP_POINT_ETA",
  "includeBackToBack": true
}
EOM

Lihat referensi providers.vehicles.search.

Java

static final String PROJECT_ID = "project-id";

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

String parent = "providers/" + PROJECT_ID;
SearchVehiclesRequest searchVehiclesRequest = SearchVehiclesRequest.newBuilder()
    .setParent(parent)
    .setPickupPoint( // Grand Indonesia East Mall
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
    .setDropoffPoint( // Balai Sidang Jakarta Convention Center
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder().setLatitude(-6.213796).setLongitude(106.807195)))
    .setPickupRadiusMeters(2000)
    .setCount(10)
    .setMinimumCapacity(2)
    .addTripTypes(TripType.EXCLUSIVE)
    .addVehicleTypes(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
    .setFilter("attributes.on_trip=\"false\"")
    .setOrderBy(VehicleMatchOrder.PICKUP_POINT_ETA)
    .setIncludeBackToBack(true) // Fleet Engine includes vehicles that are en route.
    .build();

// Error handling
// If matches are returned and the authentication passed, the request completed
// successfully

try {
  SearchVehiclesResponse searchVehiclesResponse =
      vehicleService.searchVehicles(searchVehiclesRequest);

  // Search results: Each vehicle match contains a vehicle entity and information
  // about the distance and ETA to the pickup point and dropoff point.
  List<VehicleMatch> vehicleMatches = searchVehiclesResponse.getMatchesList();
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

Kueri pemfilteran kendaraan

SearchVehicles dan ListVehicles mendukung pemfilteran pada atribut kendaraan menggunakan kueri filter. Untuk sintaksis kueri filter, lihat AIP-160 untuk mengetahui contohnya.

Perhatikan bahwa kueri filter HANYA mendukung pemfilteran pada atribut kendaraan, dan tidak dapat digunakan untuk kolom lain. Kueri filter berfungsi sebagai klausa AND dengan batasan lain, seperti minimum_capacity atau vehicle_types dalam SearchVehiclesRequest.

Catatan: Sebaiknya gunakan kolom kueri filter pada kolom required_attributes, required_one_of_attributes, dan required_one_of_attributes_sets karena filter dirancang untuk menggantikan kolom ini. Jika nilai yang tidak kosong ditentukan di kolom filter, kolom berikut harus kosong: required_attributes, required_one_of_attributes, dan required_one_of_attributes_sets.

CARA KERJA: Mencantumkan kendaraan

SearchVehicles dioptimalkan untuk menemukan sejumlah kecil kendaraan dalam urutan peringkat dengan sangat cepat dan terutama digunakan untuk menemukan pengemudi terdekat yang paling cocok untuk tugas. Namun, terkadang Anda ingin menemukan semua kendaraan yang memenuhi beberapa kriteria meskipun paging melalui hasil diperlukan. ListVehicles dirancang untuk kasus penggunaan tersebut.

ListVehicles API memungkinkan Anda menemukan semua kendaraan yang memenuhi beberapa opsi permintaan tertentu. ListVehicles API menampilkan daftar kendaraan yang telah diberi nomor halaman dalam project yang sesuai dengan beberapa persyaratan.

Untuk memfilter atribut kendaraan, lihat Kueri pemfilteran kendaraan.

Contoh

Contoh ini menjalankan pemfilteran pada vehicle_type dan atribut menggunakan string filter.

shell

curl -X POST \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles:list" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
  "vehicleTypes": [{"category": "AUTO"}],
  "filter": "attributes.on_trip=\"false\"",
}
EOM

Lihat referensi providers.vehicles.list.

Java

static final String PROJECT_ID = "project-id";

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

String parent = "providers/" + PROJECT_ID;
ListVehiclesRequest listVehiclesRequest = ListVehiclesRequest.newBuilder()
    .setParent(parent)
    .addTripTypes(TripType.EXCLUSIVE)
    .addVehicleTypes(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
    .setFilter("attributes.on_trip=\"false\"")
    .setIncludeBackToBack(true) // Fleet Engine includes vehicles that are en route.
    .build();

// Error handling
// If matches are returned and the authentication passed, the request completed
// successfully

try {
  ListVehiclesResponse listVehiclesResponse =
      vehicleService.listVehicles(listVehiclesRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

Perjalanan dan siklus prosesnya

Trip API dan siklus proses mirip dengan Vehicle API dan siklus proses. Penyedia Transportasi Umum bertanggung jawab untuk membuat perjalanan menggunakan antarmuka Feet Engine. Fleet Engine menyediakan layanan RPC, TripService, dan resource REST, provider.trips . Antarmuka ini memungkinkan pembuatan entity Perjalanan, permintaan informasi, fungsi penelusuran, dan kemampuan update.

Trip memiliki kolom status untuk melacak progresnya selama siklus prosesnya. Nilainya berpindah dari NEW ke COMPLETE serta CANCELED dan UNKNOWN_TRIP_STATUS . Lihat trip_status untuk RPC atau TripStatus untuk REST.

• NEW
• ENROUTE_TO_PICKUP
• ARRIVED_AT_PICKUP
• ENROUTE_TO_INTERMEDIATE_DESTINATION
• ARRIVED_AT_INTERMEDIATE_DESTINATION
• ENROUTE_TO_DROPOFF
• COMPLETE

Layanan Anda dapat memperbarui perjalanan ke CANCELED dari salah satu status berikut. Saat layanan Anda membuat perjalanan, mesin akan menyetel statusnya sebagai NEW. vehicle_id bersifat opsional. Seperti halnya kendaraan, layanan akan otomatis menghapus perjalanan setelah tujuh hari tanpa ada info terbaru. Jika layanan Anda mencoba membuat perjalanan dengan ID yang sudah ada, error akan ditampilkan. Perjalanan dianggap 'aktif' jika dalam status selain COMPLETE atau CANCELED. Perbedaan ini penting pada kolom active_trips dalam entity Kendaraan dan SearchTripsRequest.

Layanan hanya dapat mengubah vehicle_id yang ditetapkan ke Perjalanan jika statusnya NEW atau CANCELED. Jika Pengemudi membatalkan Perjalanan saat dalam perjalanan, status Perjalanan harus ditetapkan ke NEW atau CANCELED sebelum vehicle_id diubah atau dihapus.

Status ini penting saat menerapkan dukungan perjalanan bolak-balik. Dukungan ini memungkinkan Penyedia menetapkan perjalanan baru ke Kendaraan saat Kendaraan tersebut dalam Perjalanan aktif. Kode untuk membuat Perjalanan beruntun sama dengan satu perjalanan dan menggunakan ID kendaraan yang sama. Fleet Engine menambahkan tempat asal dan tujuan perjalanan baru ke titik jalan kendaraan. Untuk informasi selengkapnya tentang perjalanan beruntun, lihat Membuat perjalanan Multi-titik jalan.

Catatan: Fleet Engine tidak mendukung penghapusan perjalanan secara eksplisit. Layanan akan otomatis menghapus perjalanan setelah tujuh hari tanpa pembaruan. Google tidak menyimpan data pribadi. Jika Anda ingin menyimpan data perjalanan, Penyedia Rideshare harus mengimplementasikan fungsi tersebut.

Titik jalan tersisa perjalanan

Entity Trip berisi kolom berulang TripWaypoint (RPC | REST), yang disebut remainingWaypoints(RPC | REST). Kolom ini menyertakan semua titik jalan yang harus dilalui kendaraan secara berurutan sebelum titik pengantaran terakhir dalam perjalanan ini. Metode ini dihitung dari titik jalan kendaraan yang tersisa. Dalam kasus penggunaan Kembali-ke-belakang dan Carpool, daftar ini berisi titik jalan dari perjalanan lain yang akan dilalui sebelum perjalanan ini, tetapi tidak mencakup titik jalan setelah perjalanan ini. Titik jalan dalam daftar dapat diidentifikasi melalui TripId dan WaypointType.

Hubungan antara status perjalanan dan titik jalan yang tersisa Kendaraan

Titik jalan kendaraan yang tersisa (RPC | REST) akan diupdate saat Fleet Engine menerima permintaan perubahan status perjalanan. Titik jalan sebelumnya akan dihapus dari daftar titik jalan kendaraan yang tersisa saat tripStatus(RPC | REST) diubah dari status lain menjadi ENROUTE_TO_XXX. Artinya, saat status perjalanan diubah dari ENROUTE_TO_PICKUP ke ARRIVED_AT_PICKUP, titik pengambilan perjalanan akan tetap berada di daftar titik jalan yang tersisa untuk Kendaraan, tetapi jika status perjalanan diubah menjadi ENROUTE_TO_INTERMEDIATE_DESTINATION atau ENROUTE_TO_DROPOFF, titik penjemputannya akan dihapus dari kendaraan.

Hal ini sama untuk ARRIVED_AT_INTERMEDIATE_DESTINATION dan ENROUTE_TO_INTERMDEDIATE_DESTINATION. Saat ARRIVED_AT_INTERMEDIATE_DESTINATION, tujuan perantara saat ini tidak akan dihapus dari daftar titik jalan Kendaraan yang tersisa hingga kendaraan melaporkan bahwa kendaraan tersebut beralih ke titik jalan berikutnya.

Jika status perjalanan diubah menjadi COMPLETED, titik jalan dari perjalanan ini tidak akan ada dalam daftar titik jalan yang tersisa di Kendaraan.

CARA KERJA: Membuat perjalanan

Entity Trip harus dibuat agar setiap permintaan perjalanan dilacak dan dicocokkan dengan Kendaraan dalam armada. Gunakan endpoint CreateTrip dengan CreateTripRequest untuk membuat Perjalanan.

Atribut berikut diperlukan untuk membuat perjalanan:

• parent - String yang menyertakan ID Penyedia yang dibuat saat Project Google Cloud dibuat.
• trip_id - String yang dibuat oleh Penyedia Transportasi Online.
• trip - Penampung dengan metadata dasar yang mendeskripsikan perjalanan.
  • trip_type - Enum yang menunjukkan apakah perjalanan mungkin memiliki penumpang lain dari asal dan tujuan yang berbeda dalam kendaraan yang sama (SHARED) atau hanya untuk satu pihak (EXCLUSIVE).
  • pickup_point - TerminalLocation yang mewakili titik asal untuk perjalanan. Lihat referensi RPC atau referensi REST

Saat membuat perjalanan, Anda dapat memberikan number_of_passengers, dropoff_point, dan vehicle_id. Meskipun tidak wajib, kolom ini akan dipertahankan. Semua kolom Perjalanan lainnya diabaikan. Misalnya, semua perjalanan dimulai dengan trip_status dari NEW meskipun Anda meneruskan trip_status dari CANCELED dalam permintaan pembuatan.

Catatan: Penggunaan CreateTrip memerlukan kredensial untuk akun dengan hak istimewa yang disebutkan dalam Penyiapan project Cloud.

Contoh

Contoh berikut membuat perjalanan ke Grand Indonesia East Mall. Perjalanan ini untuk dua penumpang dan bersifat eksklusif. provider_id dari Trip harus sama dengan Project ID. Dalam contoh, Penyedia Transportasi Online membuat Project Google Cloud, project-id. Project ini harus memiliki Akun Layanan yang digunakan untuk memanggil Fleet Engine. Status perjalanan adalah NEW.

Kemudian, setelah layanan cocok dengan perjalanan ke kendaraan, layanan dapat memanggil UpdateTrip dan mengubah vehicle_id saat perjalanan ditetapkan ke kendaraan.

shell

curl -X POST \
  "https://fleetengine.googleapis.com/v1/providers/project-id/trips?tripId=tid-1f97" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
  "tripType": "EXCLUSIVE",
  "numberOfPassengers": 2,
  "pickupPoint": {
    "point": {"latitude": "-6.195139", "longitude": "106.820826"}
  },
  "dropoffPoint": {
    "point": {"latitude": "-6.1275", "longitude": "106.6537"}
  }
}
EOM

Lihat referensi providers.trips.create.

Java

static final String PROJECT_ID = "project-id";

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

String parent = "providers/" + PROJECT_ID;
Trip trip = Trip.newBuilder()
    .setTripType(TripType.EXCLUSIVE) // Use TripType.SHARED for carpooling
    .setPickupPoint(                 // Grand Indonesia East Mall
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
    // Provide the number of passengers if available.
    .setNumberOfPassengers(2)
    // Provide the drop-off point if available.
    .setDropoffPoint(
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder().setLatitude(-6.1275).setLongitude(106.6537)))
    .build();

CreateTripRequest createTripRequest =
    CreateTripRequest.newBuilder()  // no need for the header
        .setParent(parent)
        .setTripId("tid-1f97")  // Trip ID assigned by the Provider
        .setTrip(trip)              // Initial state
        .build();

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

try {
  Trip createdTrip =
      tripService.createTrip(createTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case ALREADY_EXISTS:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

Log platform Google Cloud untuk Pembuatan Perjalanan

Fleet Engine API menulis entri log menggunakan log platform Google Cloud saat panggilan ke endpoint CreateTrip diterima. Entri log menyertakan informasi tentang nilai dalam permintaan CreateTrip. Jika panggilan berhasil, informasi tentang Trip yang ditampilkan juga akan disertakan.

CARA KERJA: Memperbarui perjalanan

Entity Perjalanan berisi kolom yang mengaktifkan pelacakan oleh layanan dan untuk melaporkan perkembangan perjalanan oleh Driver SDK dan ke Consumer SDK. Untuk memperbarui properti, gunakan pesan UpdateTripRequest. Tindakan ini akan memperbarui kolom Perjalanan sesuai dengan field_mask permintaan. Lihat UpdateTripRequest.

Catatan: Penggunaan UpdateTripRequest untuk mengupdate trip_status atau vehicle_id Perjalanan memerlukan kredensial untuk akun hak istimewa Penyedia.

Penyedia Transportasi Online bertanggung jawab untuk memperbarui atribut berikut:

• Status perjalanan.
• ID Kendaraan. Baik pada saat pembuatan atau setelah mencocokkan kendaraan dengan perjalanan.
• Perubahan pada penjemputan, penurunan, atau titik jalan.

Fleet Engine secara otomatis memperbarui kolom berikut saat menggunakan fitur Berbagi Perjalanan melalui Driver SDK atau Consumer SDK:

• Rute
• PWT
• Jarak tersisa
• Lokasi kendaraan
• Titik jalan tersisa

Lihat Tripdi RPC atau Resource.Trip di REST.

Log platform Google Cloud untuk Info Terbaru Perjalanan

Fleet Engine API menulis entri log menggunakan log platform Google Cloud saat panggilan ke endpoint UpdateTrip diterima. Entri log menyertakan informasi tentang nilai dalam permintaan UpdateTrip. Jika panggilan berhasil, panggilan juga akan menyertakan informasi tentang Trip yang ditampilkan.

CARA KERJA: Menelusuri perjalanan

Fleet Engine mendukung penelusuran perjalanan. Seperti yang telah disebutkan, Perjalanan otomatis dihapus setelah tujuh hari, sehingga SearchTrips tidak menampilkan histori lengkap semua Perjalanan.

Meskipun SearchTrips adalah API fleksibel, daftar di bawah mempertimbangkan dua kasus penggunaan.

• Menentukan Perjalanan Aktif Kendaraan -- Penyedia dapat menentukan perjalanan kendaraan yang saat ini aktif. Dalam SearchTripsRequest, vehicle_id ditetapkan ke kendaraan yang sedang dipertimbangkan dan active_trips_only harus ditetapkan ke true.

• Merekonsiliasi Penyedia dan Status Fleet Engine -- Penyedia dapat menggunakan SearchTrips untuk memastikan status Perjalanannya dan status Fleet Engine. Hal ini sangat penting untuk TripStatus. Jika status perjalanan yang ditetapkan ke Kendaraan tidak ditetapkan dengan benar ke COMPLETE atau CANCELED, Kendaraan tidak disertakan oleh SearchVehicles.

Untuk menggunakan SearchTrips dengan cara ini, biarkan vehicle_id kosong, setel active_trips_only ke true, dan setel minimum_staleness ke waktu yang lebih lama dari sebagian besar durasi perjalanan. Misalnya, Anda dapat menggunakan satu jam. Hasilnya mencakup Perjalanan yang belum SELESAI atau DIBATALKAN, dan belum diperbarui dalam lebih dari satu jam. Penyedia harus memeriksa Perjalanan ini untuk memastikan statusnya di Fleet Engine diperbarui dengan benar.

Pemecahan masalah

Dalam kasus Error DEADLINE_EXCEEDED, status Fleet Engine tidak diketahui. Penyedia harus memanggil CreateTrip lagi, yang akan menampilkan 201 (CREATED) atau 409 (KONFLIK). Dalam kasus yang terakhir, permintaan sebelumnya berhasil sebelum DEADLINE_EXCEEDED. Lihat panduan Consumer API untuk mengetahui informasi selengkapnya tentang penanganan error perjalanan: Android atau iOS.

Dukungan perjalanan Carpool

Anda dapat menetapkan beberapa perjalanan SHARED ke kendaraan yang mendukung TripType.SHARED. Anda harus menentukan urutan semua titik jalan yang belum dilewati untuk semua Perjalanan yang ditetapkan ke Kendaraan dalam perjalanan bersama ini melalui Trip.vehicle_waypoints saat menetapkan vehicle_id untuk perjalanan bersama (dalam permintaan CreateTrip atau UpdateTrip). Lihat vehicle_waypoints untuk RPC atau vehicleWaypoints untuk REST.

Catatan: Trip.vehicle_waypoints harus berisi semua titik jalan yang tersisa dari semua perjalanan yang ditetapkan ke kendaraan, tetapi tidak memiliki titik jalan tambahan. Titik jalan ini harus diurutkan sedemikian rupa sehingga untuk perjalanan tertentu, titik penjemputan adalah sebelum tujuan perantara dan semua tujuan perantara berada sebelum titik pengantaran. Titik jalan perjalanan EXCLUSIVE tidak boleh disisipkan dengan perjalanan lainnya.

Dukungan multi-tujuan

Mengidentifikasi tujuan perantara

Kolom intermediateDestinations dan kolom intermediateDestinationIndex dalam Perjalanan (RPC | REST) digabungkan untuk digunakan untuk menunjukkan tujuan.

Memperbarui tujuan perantara

Anda dapat memperbarui tujuan perantara melalui UpdateTrip. Saat memperbarui tujuan perantara, Anda harus memberikan daftar lengkap tujuan perantara, termasuk tujuan yang telah dikunjungi, bukan hanya tujuan yang baru ditambahkan atau untuk diubah. Jika intermediateDestinationIndex mengarah ke indeks setelah posisi tujuan perantara yang baru ditambahkan/diubah, tujuan perantara yang baru/diperbarui tidak akan ditambahkan ke waypoints Kendaraan atau remainingWaypoints Perjalanan. Alasannya adalah setiap tujuan perantara sebelum intermediateDestinationIndex dianggap sudah dikunjungi.

Perubahan status perjalanan

Kolom intermediateDestinationsVersion di (RPC | REST) diperlukan dalam permintaan pembaruan status Perjalanan yang dikirim ke Fleet Engine untuk menunjukkan bahwa tujuan perantara telah berlalu. Tujuan perantara yang ditargetkan ditentukan melalui kolom intermediateDestinationIndex. Jika tripStatus (RPC | REST) adalah ENROUTE_TO_INTERMEDIATE_DESTINATION, angka antara [0..N-1] menunjukkan tujuan perantara mana yang akan dilintasi kendaraan berikutnya. Jika tripStatus adalah ARRIVED_AT_INTERMEDIATE_DESTINATION, angka antara [0..N-1] menunjukkan tujuan perantara mana kendaraan berada.

Contoh

Contoh kode berikut menunjukkan cara memperbarui status perjalanan untuk beralih ke tujuan perantara pertamanya, dengan asumsi bahwa Anda telah membuat perjalanan multi-tujuan dan perjalanan telah melewati titik penjemputannya.

Java

static final String PROJECT_ID = "project-id";
static final String TRIP_ID = "multi-destination-trip-A";

String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_ID;
Trip trip = …; // Fetch trip object from FleetEngine or your storage.

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// Trip settings to update.
Trip trip = Trip.newBuilder()
    // Trip status cannot go back to a previous status once it is passed
    .setTripStatus(TripStatus.ENROUTE_TO_INTERMEDIATE_DESTINATION)
    // Enrouting to the first intermediate destination.
    .setIntermediateDestinationIndex(0)
    // intermediate_destinations_version MUST be provided to ensure you
    // have the same picture on intermediate destinations list as FleetEngine has.
    .setIntermediateDestinationsVersion(
        trip.getIntermediateDestinationsVersion())
    .build();

// Trip update request
UpdateTripRequest updateTripRequest =
    UpdateTripRequest.newBuilder()
        .setName(tripName)
        .setTrip(trip)
        .setUpdateMask(
            FieldMask.newBuilder()
                .addPaths("trip_status")
                .addPaths("intermediate_destination_index")
                // intermediate_destinations_version must not be in the
                // update mask.
                .build())
        .build();

// Error handling
try {
  Trip updatedTrip = tripService.updateTrip(updateTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:  // Trip does not exist.
      break;
    case FAILED_PRECONDITION:  // The given trip status is invalid, or the
                                // intermediate_destinations_version
                                // doesn’t match FleetEngine’s.
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

CARA KERJA: Berlangganan pesan notifikasi dari Fleet Engine API

Feet Engine API menggunakan Google Cloud Pub/Sub untuk memublikasikan notifikasi tentang topik yang dibuat oleh Project Google Cloud konsumen. Pub/Sub tidak diaktifkan secara default untuk Fleet Engine di project Google Cloud Anda. Harap ajukan kasus dukungan atau hubungi Customer Engineer Anda untuk mengaktifkan Pub/Sub.

Catatan: Pub/Sub tidak menjamin urutan pesan.

Untuk membuat topik di Project Cloud Anda, ikuti petunjuk ini. ID topik harus berupa 'fleet_engine_notifications'.

Topik harus dibuat di project Cloud yang sama yang memanggil API Fleet Engine.

Setelah topik dibuat, Anda harus memberikan izin kepada Fleet Engine API untuk memublikasikan topik tersebut. Untuk melakukannya, klik topik yang baru saja Anda buat dan tambahkan izin akses baru. Anda mungkin harus mengklik TAMPILKAN Panel INFO untuk membuka editor izin. Akun utama harus [e-mail] dan perannya harus Pub/Sub publisher.

Agar dapat menyiapkan Project Cloud Anda agar berlangganan notifikasi, ikuti petunjuk ini

Fleet Engine API akan memublikasikan setiap notifikasi dalam dua format data yang berbeda, protobuf dan json. Format data untuk setiap notifikasi dilambangkan dalam atribut PubsubMessage dengan kunci sebagai data_format dan nilainya sebagai protobuf atau json.

Skema notifikasi:

{i>Protobuf<i}

// A batch of notifications that is published by the Fleet Engine service using
// Cloud Pub/Sub in a single PubsubMessage.
message BatchNotification {
  // Required. At least one notification must exist.
  // List of notifications containing information related to changes in
  // Fleet Engine data.
  repeated Notification notifications = 1;
}

// A notification related to changes in Fleet Engine data.
// The data provides additional information specific to the type of the
// notification.
message Notification {
  // Required. At least one type must exist.
  // Type of notification.
  oneof type {
    // Notification related to changes in vehicle data.
    VehicleNotification vehicle_notification = 1;
  }
}

// Notification sent when a new vehicle was created.
message CreateVehicleNotification {
  // Required.
  // Vehicle must contain all fields that were set when it was created.
  Vehicle vehicle = 1;
}

// Notification sent when an existing vehicle is updated.
message UpdateVehicleNotification {
  // Required.
  // Vehicle must only contain name and fields that are present in the
  // field_mask field below.
  Vehicle vehicle = 1;

  // Required.
  // Contains vehicle field paths that were specifically requested
  // by the Provider.
  google.protobuf.FieldMask field_mask = 2;
}

// Notification related to changes in vehicle data.
message VehicleNotification {
  // Required. At least one type must be set.
  // Type of notification.
  oneof type {
    // Notification sent when a new vehicle was created.
    CreateVehicleNotification create_notification = 1;
    // Notification sent when an existing vehicle is updated.
    UpdateVehicleNotification update_notification = 2;
  }
}

JSON

• Kendaraan
• FieldMask

BatchNotification: {
  "description": "A batch of notifications that is published by the Fleet Engine service using Cloud Pub/Sub in a single PubsubMessage.",
  "type": "object",
  "required": ["notifications"],
  "properties": {
    "notifications": {
      "description": "At least one notification must exist. List of notifications containing information related to changes in Fleet Engine data.",
      "type": "Notification[]"
    }
  }
}

Notification: {
  "description": "A notification related to changes in Fleet Engine data. The data provides additional information specific to the type of the notification.",
  "type": "object",
  "properties": {
    "vehicleNotification": {
      "description": "Notification related to changes in vehicle data.",
      "type": "VehicleNotification"
    }
  }
}

VehicleNotification: {
  "description": "Notification related to changes in vehicle data.",
  "type": "object",
  "properties": {
    "createNotification": {
      "description": "Notification sent when a new vehicle was created.",
      "type": "CreateVehicleNotification"
    },
    "updateNotification": {
      "description": "Notification sent when an existing vehicle is updated.",
      "type": "UpdateVehicleNotification"
    }
  }
}

CreateVehicleNotification: {
  "description": "Notification sent when a new vehicle was created.",
  "type": "object",
  "required": ["vehicle"],
  "properties": {
    "vehicle": {
      "description": "Vehicle must contain all fields that were set when it was created.",
      "type": "Vehicle"
    }
  }
}

UpdateVehicleNotification: {
  "description": "Notification sent when an existing vehicle is updated.",
  "type": "object",
  "required": ["vehicle", "fieldMask"],
  "properties": {
    "vehicle": {
      "description": "Vehicle must only contain name and fields that are present in the fieldMask field below.",
      "type": "Vehicle"
    },
    "fieldMask": {
      "description": "Contains vehicle field paths that were specifically requested by the Provider.",
      "type": "FieldMask"
    }
  }
}