Mulai menggunakan Fleet Engine

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

Prasyarat

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

gcloud auth login

You are now logged in as [my-user@example.com].
Your current project is [project-id].  You ...

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

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

Logging

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

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

Library Klien

Kami menerbitkan library klien dalam beberapa bahasa pemrograman yang umum. Ini library akan membantu memberikan pengalaman developer yang lebih baik melalui REST mentah atau gRPC. Untuk petunjuk cara memperoleh pustaka klien untuk aplikasi server Anda, lihat Library Klien.

Contoh Java dalam dokumentasi ini mengasumsikan bahwa Anda telah memahami 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 Cloud Console.

Penyiapan project cloud

Untuk menyiapkan project cloud, buat project terlebih dahulu, lalu membuat 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. {i>Mockup <i}digunakan untuk membuat Token Web JSON yang memberikan serangkaian izin berbeda bergantung pada peran. Biasanya, untuk mengurangi kemungkinan penyalahgunaan, Anda dapat membuat beberapa akun layanan, masing-masing dengan kumpulan peran minimum yang diperlukan.

Progres Perjalanan dan Pesanan menggunakan peran berikut:

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

gcloud --project=project-id iam service-accounts create fleet-engine-consumer-sdk
gcloud projects add-iam-policy-binding project-id \
       --member=serviceAccount:fleet-engine-consumer-sdk@project-id.iam.gserviceaccount.com \
       --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:fleet-engine-driver-sdk@project-id.iam.gserviceaccount.com \
       --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:fleet-engine-su@project-id.iam.gserviceaccount.com \
       --role=roles/fleetengine.serviceSuperUser

Driver dan Consumer SDK dibuat berdasarkan peran standar ini.

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

Demi kemudahan, jika Anda perlu membuat token JWT untuk klien yang tidak tepercaya, peran Service Account Token Creator memungkinkan mereka membuat token dengan alat command line gcloud.

gcloud projects add-iam-policy-binding project-id \
       --member=user:my-user@example.com \
       --role=roles/iam.serviceAccountTokenCreator

Dengan my-user@example.com adalah email yang digunakan untuk melakukan autentikasi dengan gcloud (gcloud auth list --format='value(account)').

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 akun layanan).
• Melampirkan token yang ditandatangani ke permintaan keluar yang dibuat dari stub gRPC atau klien GAPIC.

Membuat Token Web JSON (JWT) untuk otorisasi

Jika tidak menggunakan Library Auth Fleet Engine, Token Web JSON (JWT) perlu dibuat langsung dalam codebase Anda. Hal ini mengharuskan Anda untuk memiliki memahami JWT dan hubungannya dengan Fleet Engine. Inilah alasan mengapa kita Sangat direkomendasikan untuk memanfaatkan Library Auth Fleet Engine.

Di dalam Fleet Engine, JSON Web Token (JWT) menyediakan autentikasi jangka pendek dan memastikan bahwa perangkat hanya dapat memodifikasi kendaraan, perjalanan, atau tugas untuk mereka diberi otorisasi. JWT berisi header dan bagian klaim. Bagian {i>header<i} berisi informasi seperti kunci pribadi yang digunakan (diperoleh dari akun layanan) dan enkripsi algoritme. Bagian klaim berisi informasi seperti waktu pembuatan token, waktu aktif token, layanan yang mengklaim akses ke, dan informasi otorisasi lainnya untuk cakupan di akses; misalnya, ID kendaraan.

Bagian header JWT berisi kolom-kolom berikut:

Bagian klaim JWT berisi kolom-kolom berikut:

Pembuatan token JWT mengacu pada proses penandatanganannya. Untuk mendapatkan petunjuk dan contoh kode untuk membuat dan menandatangani JWT, lihat Otorisasi akun layanan tanpa OAuth. Kemudian, 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 disetel ke nilai ID kendaraan atau ID perjalanan yang digunakan untuk melakukan panggilan.

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

Consumer SDK selalu menggunakan klaim tripid.

Penyedia Transportasi Online atau Pesan Antar harus menggunakan vehicleid atau tripid dengan tanda "*" dapat cocokkan dengan semua Kendaraan dan Perjalanan. Perhatikan bahwa JWT dapat berisi kedua token, meskipun tidak diperlukan, yang dapat menyederhanakan penerapan penandatanganan token.

Kasus Penggunaan JWT

Berikut adalah contoh token untuk Server penyedia:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_provider_service_account"
}
.
{
  "iss": "provider@yourgcpproject.iam.gserviceaccount.com",
  "sub": "provider@yourgcpproject.iam.gserviceaccount.com",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "authorization": {
     "vehicleid": "*",
     "tripid": "*"
   }
}

Berikut adalah contoh token untuk Consumer app:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_consumer_service_account"
}
.
{
  "iss": "consumer@yourgcpproject.iam.gserviceaccount.com",
  "sub": "consumer@yourgcpproject.iam.gserviceaccount.com",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "authorization": {
     "tripid": "trip_54321"
   }
}

Berikut adalah contoh token untuk Aplikasi pengemudi:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_driver_service_account"
}
.
{
  "iss": "driver@yourgcpproject.iam.gserviceaccount.com",
  "sub": "driver@yourgcpproject.iam.gserviceaccount.com",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "authorization": {
     "vehicleid": "driver_12345"
   }
}

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

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

Selain itu, saat menandatangani JWT yang akan digunakan untuk panggilan dengan hak istimewa, pastikan agar dapat menggunakan akun layanan dengan peran Super User. Jika tidak, operasi akan gagal.

Membuat JWT untuk pengujian

Membuat token dari terminal dapat membantu saat pengujian.

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

gcloud projects add-iam-policy-binding project-id \
       --member=user:my-user@example.com \
       --role=roles/iam.serviceAccountTokenCreator

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

{
  "aud": "https://fleetengine.googleapis.com/",
  "iss": "super-user-service-account@project-id.iam.gserviceaccount.com",
  "sub": "super-user-service-account@project-id.iam.gserviceaccount.com",
  "iat": iat,
  "exp": exp,
  "authorization": {
     "vehicleid": "*",
     "tripid": "*"
   }
}

Lalu, jalankan perintah gcloud berikut untuk menandatangani token atas nama Super Anda Akun layanan pengguna:

gcloud beta iam service-accounts sign-jwt --iam-account=super-user-service-account@project-id.iam.gserviceaccount.com unsigned_token.json signed_token.jwt

JWT berenkode Base64 yang ditandatangani kini seharusnya disimpan dalam file signed_token.jwt. Token berlaku untuk satu jam ke depan.

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

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 entity yang mewakili pasangan pengemudi-kendaraan. Saat ini, Pengemudi dan Kendaraan tidak dapat dilacak secara terpisah. Penyedia Transportasi Online atau Pesan Antar membuat Kendaraan menggunakan ID Penyedia (yang harus sama dengan ID Project dari Project Google Cloud yang berisi akun layanan digunakan untuk memanggil API Fleet Engine) dan ID Kendaraan milik Penyedia Transportasi atau Pengiriman.

Kendaraan yang belum diupdate melalui UpdateVehicle setelah tujuh hari akan otomatis dihapus, dan perjalanan yang ditetapkan, jika ada, akan ditandai sebagai belum ditetapkan. Pendekatan yang direkomendasikan untuk menjaga ketersediaan kendaraan di Fleet Engine adalah memperbarui lokasinya secara berkala. Pembaruan pada sebagian besar kolom lain dalam entitas Vehicle juga akan memperpanjang masa berlakunya, asalkan nilai {i>field<i} baru berbeda dengan yang sudah ada.

CATATAN: Beberapa kolom pada entity Vehicle seperti device_settings sepenuhnya merupakan debug informasi yang tidak disimpan oleh Fleet Engine. Memperbaruinya tidak memperpanjang masa pakai entity Vehicle.

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 ID Penyedia/pasangan ID Kendaraan yang diharapkan dan penghapusan error jika Kendaraan sudah ada; atau, memanggil CreateVehicle setelah UpdateVehicle ditampilkan dengan error NOT_FOUND.

Pembaruan lokasi kendaraan

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.

Entity Kendaraan berisi kolom berulang TripWaypoint (RPC | REST), disebut waypoints(RPC | REST). Bidang ini berisi titik jalan yang tersisa dalam perjalanan, dengan urutan kendaraan mencapai mereka. Fleet Engine menghitung kolom ini sebagai 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 kecocokan

Biasanya, layanan Transportasi Online atau Penyedia Pesan Antar bertanggung jawab untuk mencocokkan perjalanan terhadap kendaraan. Layanan dapat menggunakan atribut kendaraan untuk menyertakan kendaraan dalam jumlah penelusuran yang lebih besar. Misalnya, penyedia bisa mengimplementasikan seperangkat atribut yang sesuai dengan tingkat keuntungan atau kemampuan yang diberikan sebuah kendaraan. Misalnya, tiga tingkat dapat berupa kumpulan atribut dengan boolean nilai: is_bronze_level, is_silver_level, dan is_gold_level. Sebuah kendaraan dapat 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 IT.

Ada dua cara untuk memperbarui atribut kendaraan. Salah satunya adalah UpdateVehicle Compute Engine API. Saat menggunakan API ini, seluruh kumpulan Atribut Kendaraan tetapkan ke nilai. Tidak mungkin hanya memperbarui satu atribut. Metode lainnya adalah UpdateVehicleAttributes API. Metode ini hanya memerlukan atribut yang akan diperbarui. Atribut yang disertakan dalam permintaan akan diatur ke nilai baru atau {i> added<i}; atribut yang tidak ditentukan tidak akan diubah.

PETUNJUK: Membuat Kendaraan

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

Gunakan endpoint CreateVehicle dengan CreateVehicleRequest untuk membuat Kendaraan.

provider_id dari Vehicle harus berupa Project ID (mis. project my-on-demand) 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 Rideshare yang sama atau Penyedia Pengiriman, 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 yang dibuat ONLINE dapat langsung ditampilkan sebagai respons terhadap SearchVehicles terhadap kueri.

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 kendaraan {i>type<i}.

Lihat Atribut Kendaraan untuk mengetahui detailnya pada isian atribut.

Nilai yang ditampilkan dari CreateVehicle adalah entity Vehicle yang dibuat.

Contoh

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

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 tersebut meliputi informasi tentang nilai dalam permintaan CreateVehicle. Jika panggilan berhasil, hal ini juga akan menyertakan informasi tentang Vehicle yang dikembalikan.

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

---
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 dibuat. Untuk menerima notifikasi ini, ikuti petunjuk di sini.

CARANYA: 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. Update ini hanya memerlukan Pengguna SDK Driver Fleet Engine hak istimewa pengguna.

Contoh

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

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.

CARANYA: Perbarui kolom Kendaraan lainnya

Pembaruan pada atribut lain di status Kendaraan lebih jarang terjadi daripada posisi tersebut. Update untuk atribut selain last_location memerlukan Hak istimewa Pengguna Super Fleet Engine.

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

Seperti yang tercantum dalam Atribut Kendaraan, memperbarui Kolom attributes mengharuskan penulisan semua atribut agar dipertahankan. Ini tidak mungkin untuk hanya memperbarui nilai satu pasangan nilai kunci Panggilan UpdateVehicle. Untuk memperbarui nilai atribut tertentu, metode UpdateVehicleAttributes API dapat digunakan.

Contoh

Contoh ini mengaktifkan back_to_back.

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

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 Update Kendaraan

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

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 update Kendaraan

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

PETUNJUK: Telusuri kendaraan

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

Contoh

Saat mencari kendaraan yang tersedia, Fleet Engine mengecualikan kendaraan di perjalanan aktif secara default. Layanan Transportasi Online atau Penyedia Antar-jemput harus secara eksplisit menyertakannya dalam permintaan penelusuran. Contoh berikut menunjukkan cara memasukkan kendaraan tersebut untuk mencari kendaraan yang cocok dengan perjalanan dari Indonesia East Mall ke Balai Sidang Jakarta Convention Center.

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

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

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 sebagai contoh.

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 di SearchVehiclesRequest.

PETUNJUK: Buat daftar kendaraan

SearchVehicles dioptimalkan untuk menemukan sejumlah kecil kendaraan dalam peringkat pesanan dengan sangat cepat dan terutama digunakan untuk menemukan pengemudi terdekat yang paling sesuai pada tugas. Namun, terkadang Anda ingin menemukan semua kendaraan yang memenuhi kriteria yang sama bahkan jika {i>page<i} melalui hasil penelusuran diperlukan. ListVehicles sama dengan yang didesain untuk kasus penggunaan tersebut.

API ListVehicles memungkinkan Anda menemukan semua kendaraan yang memenuhi beberapa opsi permintaan. ListVehicles API menampilkan daftar kendaraan yang diberi nomor halaman di proyek yang sesuai dengan beberapa persyaratan.

Untuk memfilter atribut kendaraan, lihat Kueri pemfilteran kendaraan.

Contoh

Contoh ini melakukan pemfilteran pada vehicle_type dan atribut menggunakan String filter.

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

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;
}

Trip API dan siklus proses mirip dengan Vehicle API dan siklus proses. Penyedia Rideshare bertanggung jawab membuat perjalanan menggunakan Fleet Engine antarmuka. Fleet Engine menyediakan layanan RPC, TripService , dan resource REST, provider.trips kami. Antarmuka ini memungkinkan pembuatan entity Perjalanan, permintaan informasi, penelusuran fungsionalitas, dan kemampuan pembaruan.

Trip memiliki kolom status untuk melacak progresnya selama siklus proses. Nilai akan dipindahkan dari NEW ke COMPLETE plus CANCELED dan UNKNOWN_TRIP_STATUS kami. 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 ini. Saat layanan Anda membuat perjalanan, mesin akan menyetel status sebagai NEW. J vehicle_id bersifat opsional. Seperti kendaraan, layanan ini akan otomatis menghapus perjalanan yang belum ditetapkan setelah tujuh hari tanpa pembaruan. Jika layanan Anda mencoba membuat perjalanan dengan ID sudah ada, pesan error akan muncul. Perjalanan dianggap ‘aktif’ jika dalam status selain COMPLETE atau CANCELED. Perbedaan ini penting di kolom active_trips pada entity Kendaraan dan SearchTripsRequest.

Layanan Anda hanya dapat mengubah vehicle_id yang ditetapkan untuk suatu perjalanan saat perjalanan tersebut aktif. Misalnya, Anda akan melakukan ini saat pengemudi membatalkan perjalanan saat en dan perjalanan akan diatur ulang ke kendaraan yang berbeda.

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

Titik jalan perjalanan yang tersisa

Entitas Perjalanan berisi kolom berulang TripWaypoint (RPC | REST), disebut remainingWaypoints(RPC | REST). Kolom ini menyertakan semua titik jalan yang perlu dilalui kendaraan secara berurutan sebelum titik penurunan terakhir dalam perjalanan ini. Cloud SQL menghitung dari Titik jalan kendaraan yang tersisa. Dalam kasus penggunaan Back-to-back dan Carpool, daftar ini berisi titik jalan dari perjalanan lain yang akan dilewati sebelum perjalanan ini, tetapi tidak menyertakan titik jalan setelah perjalanan ini. Titik jalan dalam daftar dapat diidentifikasi berdasarkan TripId dan WaypointType.

Hubungan antara status perjalanan dan Titik jalan kendaraan yang tersisa

Titik jalan kendaraan yang tersisa (RPC | REST) akan diperbarui saat Fleet Engine menerima permintaan perubahan status perjalanan. Tujuan titik jalan sebelumnya akan dihapus dari daftar titik jalan Kendaraan yang tersisa tripStatus(RPC | REST) diubah dari status lain menjadi ENROUTE_TO_XXX. Artinya, ketika status perjalanan diubah dari ENROUTE_TO_PICKUP menjadi ARRIVED_AT_PICKUP, titik pengambilan akan tetap ada di daftar titik jalan Kendaraan yang tersisa, tetapi saat perjalanan berubah menjadi ENROUTE_TO_INTERMEDIATE_DESTINATION atau ENROUTE_TO_DROPOFF, titik penjemputannya kemudian akan dihapus dari titik jalan kendaraan yang tersisa.

Hal ini juga berlaku untuk ARRIVED_AT_INTERMEDIATE_DESTINATION dan ENROUTE_TO_INTERMDEDIATE_DESTINATION. Jika ARRIVED_AT_INTERMEDIATE_DESTINATION, tujuan perantara saat ini tidak akan dihapus dari sisa daftar titik jalan hingga kendaraan melaporkan rute yang dituju ke titik jalan berikutnya.

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

CARANYA: Buat perjalanan

Entitas Trip harus dibuat agar setiap permintaan perjalanan dapat dilacak dan yang cocok dengan Kendaraan yang ada di armada. Menggunakan endpoint CreateTrip dengan CreateTripRequest untuk membuat Perjalanan.

Atribut berikut diperlukan untuk membuat perjalanan:

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

Saat membuat perjalanan, Anda dapat memberikan number_of_passengers, dropoff_point dan vehicle_id. Meskipun tidak diperlukan, jika Anda mengisinya, dan mempertahankannya. Semua kolom Perjalanan lainnya akan diabaikan. Misalnya, semua perjalanan mulai dengan trip_status dari NEW meskipun Anda meneruskan trip_status dari CANCELED dalam permintaan pembuatan.

Contoh

Contoh berikut membuat perjalanan ke Grand Indonesia East Mall. Perjalanan untuk dua penumpang dan bersifat eksklusif. provider_id dari Trip harus sama dengan Project ID. Dalam contoh, Penyedia {i>Rideshare<i} membuat Project Google Cloud, project-id. Proyek 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 ubah vehicle_id saat perjalanan ditetapkan ke kendaraan.

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

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 tersebut meliputi informasi tentang nilai dalam permintaan CreateTrip. Jika panggilan berhasil, tindakan ini juga akan menyertakan informasi tentang Trip yang ditampilkan.

CARANYA: Memperbarui perjalanan

Entitas Perjalanan berisi bidang yang memungkinkan pelacakan oleh layanan dan untuk melaporkan perkembangan perjalanan melalui Driver SDK dan kepada SDK Konsumen. Untuk memperbarui properti, gunakan UpdateTripRequest untuk membuat pesan email baru. Tindakan ini akan memperbarui kolom Perjalanan sesuai dengan field_mask permintaan. Lihat UpdateTripRequest.

Penyedia Rideshare bertanggung jawab untuk memperbarui atribut berikut:

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

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

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

Lihat Tripdi RPC atau Resource.Trip dalam 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 tersebut meliputi informasi tentang nilai dalam permintaan UpdateTrip. Jika panggilan berhasil, informasi ini juga akan menyertakan informasi tentang Trip yang ditampilkan.

CARA KERJA: Perjalanan penelusuran

Fleet Engine mendukung penelusuran perjalanan. Seperti disebutkan sebelumnya, Perjalanan adalah 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 sedang aktif. Dalam SearchTripsRequest, vehicle_id ditetapkan untuk kendaraan yang sedang dipertimbangkan dan active_trips_only harus disetel ke true.

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

Untuk menggunakan SearchTrips dengan cara ini, kosongkan vehicle_id, 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. Hasil tersebut mencakup Perjalanan yang tidak SELESAI atau DIBATALKAN, dan belum diperbarui selama 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 adalah tidak diketahui. Penyedia harus memanggil CreateTrip lagi, yang akan menampilkan 201 (CREATED) atau 409 (CONFLICT). Dalam kasus terakhir, permintaan sebelumnya berhasil sebelum DEADLINE_EXCEEDED. Lihat panduan Consumer API untuk informasi selengkapnya cara menangani error perjalanan: Android atau iOS.

Dukungan perjalanan Carpool

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

Dukungan beberapa 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 mengupdate tujuan perantara, Anda harus memberikan daftar lengkap tujuan perantara, termasuk yang telah dikunjungi, bukan hanya yang baru yang ditambahkan atau akan dimodifikasi. Saat intermediateDestinationIndex menunjuk ke indeks setelah posisi tujuan perantara yang baru ditambahkan/diubah, tujuan perantara yang baru/diperbarui tujuan tidak akan ditambahkan ke waypoints Kendaraan atau remainingWaypoints Perjalanan. Alasannya adalah setiap tujuan perantara sebelum intermediateDestinationIndex diperlakukan sebagai telah dikunjungi.

Perubahan status perjalanan

Kolom intermediateDestinationsVersion di (RPC | REST) diperlukan dalam permintaan pembaruan status Perjalanan yang dikirim ke Fleet Engine untuk menunjukkan 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 dilalui kendaraan berikutnya. Jika tripStatus adalah ARRIVED_AT_INTERMEDIATE_DESTINATION, angka antara [0..N-1] menunjukkan tujuan perantara kendaraan berada.

Contoh

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

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;
}

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

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

Topik harus dibuat di project Cloud yang sama dengan yang memanggil Fleet Engine Google Cloud Platform.

Setelah topik dibuat, Anda harus memberikan Fleet Engine API izin untuk memublikasikan topik. Untuk melakukannya, klik topik yang baru saja dibuat dan menambahkan izin baru. Anda mungkin harus mengklik TAMPILKAN Panel INFO untuk membuka editor izin. Akun utama harus geo-fleet-engine@system.gserviceaccount.com dan perannya harus Pub/Sub publisher.

Untuk menyiapkan Project Cloud Anda agar berlangganan notifikasi, ikuti petunjuk ini

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

Skema notifikasi:

Protobuf

// 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"
    }
  }
}