Fleet Engine'i kullanmaya başlama

Fleet Engine İsteğe Bağlı Rides and Deliveries API, Seyahat ve Sipariş İlerlemesi uygulamalarınız için yolculukları ve araç durumunu yönetmenize olanak tanır. Sürücü SDK'sı, Tüketici SDK'sı ve arka uç hizmetiniz arasındaki işlemleri yönetir. Arka uç hizmetiniz gRPC veya REST çağrıları yaparak Fleet Engine ile iletişim kurabilir.

Ön koşullar

Geliştirme için Cloud SDK'yı (gcloud) yüklediğinizden ve projenizde kimlik doğrulaması yapıldığından emin olun.

shell

gcloud auth login

Şuna benzer bir başarı mesajı görürsünüz:

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

İsteğe Bağlı Yolculuklar ve Teslimatlar Çözümü Fleet Engine API'lerinin uygun şekilde yapılandırıldığından emin olun.

shell

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

Bu komut hatayla sonuçlanırsa erişim almak için proje yöneticinize ve Google destek temsilcinize başvurun.

Günlük Kaydı

Fleet Engine, aldığı API çağrılarıyla ilgili günlük mesajlarını Google Cloud Platform günlüklerine yazabilir. Günlükleri okuma ve analiz etmeye genel bakış için Cloud Logging belgelerine bakın.

Günlük kaydı, 10 Şubat 2022'den önce oluşturulmuş projeler için varsayılan olarak etkinleştirilmemiş olabilir. Daha ayrıntılı bilgi için günlük kaydı belgelerine bakın.

İstemci Kitaplıkları

Birkaç yaygın programlama dilinde istemci kitaplıkları yayınlıyoruz. Bu kitaplıklar, ham REST veya gRPC yerine daha iyi bir geliştirici deneyimi sağlamanıza yardımcı olur. Sunucu uygulamanız için istemci kitaplıklarını nasıl edineceğinizle ilgili talimatlar için İstemci Kitaplıkları bölümüne bakın.

Bu belgedeki Java örneklerinde gRPC hakkında bilgi sahibi olduğunuz varsayılır.

Kimlik Doğrulama ve Yetkilendirme

Seyahat ve Sipariş İlerleme Durumu tarafından sağlanan özellikleri Google Cloud Console aracılığıyla yapılandırabilirsiniz. Bu API ve SDK'lar, Cloud Console'dan oluşturulan hizmet hesapları kullanılarak imzalanmış JSON Web Jetonlarının kullanılmasını gerektirir.

Bulut projesi kurulumu

Bulut projenizi ayarlamak için önce projenizi, ardından hizmet hesaplarını oluşturun.

Google Cloud projenizi oluşturmak için:

  1. Google Cloud Console'u kullanarak Google Cloud projesi oluşturun.
  2. API'ler ve Hizmetler Kontrol Paneli'ni kullanarak Yerel Yolculuklar ve Teslimatlar API'sini etkinleştirin.

Hizmet hesapları bir veya daha fazla rol ile ilişkilendirilmiş. Bunlar, rollere bağlı olarak farklı izin grupları veren JSON Web Jetonları oluşturmak için kullanılır. Genelde, kötüye kullanım olasılığını azaltmak için her biri gereken minimum rol sayısına sahip birden fazla hizmet hesabı oluşturabilirsiniz.

Gezi ve Sipariş İlerleme Durumu aşağıdaki rolleri kullanır:

RolAçıklama
Fleet Engine Tüketici SDK Kullanıcısı

roles/fleetengine.consumerSdkUser		 Araç arama ve araçlar ile seyahatler hakkında bilgi alma izni verir. Bu role sahip bir hizmet hesabı tarafından oluşturulan jetonlar genellikle araç paylaşma veya teslimat tüketici uygulaması mobil cihazlarınızdan kullanılır.
Fleet Engine Sürücü SDK Kullanıcısı

roles/fleetengine.driverSdkUser		 Araç konumlarını ve rotalarını güncelleme, araçlar ve geziler hakkında bilgi alma izni verir. Bu role sahip bir hizmet hesabı tarafından oluşturulan jetonlar genellikle yolculuk paylaşımı veya teslimat sürücüsü uygulaması mobil cihazlarınızdan kullanılır.
Fleet Engine Hizmeti Süper Kullanıcısı

roles/fleetengine.serviceSuperUser		 Tüm araçlara ve seyahat API'lerine izin verir. Bu role sahip bir hizmet hesabı tarafından oluşturulan jetonlar genellikle arka uç sunucularınızdan kullanılır.

Örneğin, üç rolün her biri için bir hizmet hesabı oluşturun ve bu rollere ayrı roller atayın.

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

Sürücü ve Tüketici SDK'ları, bu standart rollere uygun şekilde oluşturulmuştur.

Alternatif olarak, rastgele bir izin grubunun bir araya getirilmesine olanak tanıyan özel roller de oluşturulabilir. Sürücü ve Tüketici SDK'ları, gerekli bir izin eksik olduğunda hata mesajı gösterir. Sonuç olarak, yukarıda sunulan standart rol grubunu kullanmanızı ve özel roller kullanmamanızı kesinlikle öneririz.

Güvenilmeyen istemciler için JWT jetonları oluşturmanız gerektiğinde kolaylık olması açısından, kullanıcıları Hizmet Hesabı Jetonu Oluşturucu Rolü'ne eklemek, kullanıcıların gcloud komut satırı araçlarını kullanarak jeton oluşturabilmelerini sağlar.

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

Burada my-user@example.com, gcloud (gcloud auth list --format='value(account)') ile kimlik doğrulamak için kullanılan e-posta adresidir.

Fleet Engine Yetkilendirme Kitaplığı

Fleet Engine, Fleet Engine API'lerine erişimi kısıtlamak için JSON Web Token'ları (JWT) kullanır. GitHub'da bulunan yeni Fleet Engine Yetkilendirme Kitaplığı, Fleet Engine JWT'lerinin oluşturulmasını basitleştirir ve bunları güvenli bir şekilde imzalar.

Kitaplık aşağıdaki avantajları sunar:

  • Fleet Engine Jetonları oluşturma işlemini basitleştirir.
  • Kimlik bilgisi dosyalarını kullanmak dışında (hizmet hesabının kimliğine bürünme gibi) jeton imzalama mekanizmaları sağlar.
  • gRPC saplaması veya GAPIC istemcisinden yapılan giden isteklere imzalı jeton ekler.

Yetkilendirme için JSON Web Jetonu (JWT) oluşturma

Fleet Engine Yetkilendirme Kitaplığı kullanılmadığında, JSON Web Token'ların (JWT) doğrudan kod tabanınızda oluşturulması gerekir. Bunun için hem JWT'leri iyice anlamanız, hem de bunların Fleet Engine ile ilişkisini iyi bilmeniz gerekir. Bu nedenle Fleet Engine Yetkilendirme Kitaplığı'ndan yararlanmanızı önemle tavsiye ederiz.

Fleet Engine'de JSON Web Jetonları (JWT'ler) kısa ömürlü kimlik doğrulama sağlar ve cihazların yalnızca yetkilendirildikleri araçları, gezileri veya görevleri değiştirebilmesini sağlar. JWT'ler bir başlık ve hak talebi bölümü içerir. Başlık bölümünde, kullanılacak özel anahtar (hizmet hesaplarından alınır) ve şifreleme algoritması gibi bilgiler yer alır. İddia bölümünde jetonun oluşturulma zamanı, jetonların geçerlilik süresi, erişim talep ettiği hizmetler ve erişimi daraltmak için diğer yetkilendirme bilgileri (ör. araç kimliği) yer alır.

Bir JWT başlık bölümü aşağıdaki alanları içerir:

AlanAçıklama
alg Kullanılacak algoritma. "RS256".
typ Jetonun türü. "JWT".
çocuk Hizmet hesabınızın özel anahtar kimliği. Bu değeri, hizmet hesabı JSON dosyanızın "private_key_id" alanında bulabilirsiniz. Doğru izin düzeyine sahip bir hizmet hesabındaki anahtarı kullandığınızdan emin olun.

JWT talepleri bölümü aşağıdaki alanları içerir:

AlanAçıklama
ISS Hizmet hesabınızın e-posta adresi.
sub Hizmet hesabınızın e-posta adresi.
kitle Hizmet hesabınızın SERVICE_NAME adresi (bu örnekte https://fleetengine.googleapis.com/)
Iat Jetonun oluşturulduğu zaman damgası. 1 Ocak 1970 tarihinde 00:00:00 (UTC) itibarıyla geçen saniye cinsinden belirtilir. Eğme için 10 dakika bekleyin. Zaman damgası çok eski veya ilerideyse sunucu bir hata bildirebilir.
exp Jetonun süresinin dolacağı zaman damgası. 1 Ocak 1970 tarihinde 00:00:00 UTC tarihinden bu yana geçen saniye cinsinden belirtilir. Zaman damgası gelecekte bir saatten uzunsa istek başarısız olur.
authorization Kullanım alanına bağlı olarak "vehicleid" veya "tripid" içerebilir.

JWT jetonu oluşturmak, jetonun imzalanması anlamına gelir. JWT'yi oluşturma ve imzalamayla ilgili talimatlar ve kod örnekleri için OAuth olmadan hizmet hesabı yetkilendirmesi sayfasına göz atın. Ardından, gRPC çağrılarına veya Fleet Engine'e erişmek için kullanılan diğer yöntemlere imzalı bir jeton ekleyebilirsiniz.

JWT Hak Talepleri

JWT yükünü oluştururken yetkilendirme bölümünde vehicleid veya tripid anahtarının, çağrının yapıldığı araç kimliği veya gezi kimliği değerine ayarlandığı ek bir talep ekleyin.

Sürücü SDK'sı, ister seyahatte ister araçta çalışıyor olsun, her zaman vehicleid hak talebini kullanır. Fleet Engine arka ucu, değişikliği yapmadan önce aracın istenen geziyle ilişkilendirilmesini sağlar.

Tüketici SDK'sı her zaman tripid hak talebini kullanır.

Araç Paylaşımı veya Teslimat Sağlayıcısı, tüm Araçlar ve Seyahatler'i eşleştirmek için vehicleid veya tripid ile birlikte "*" işaretini kullanmalıdır. JWT'nin zorunlu olmasa bile her iki jetonu da içerebileceğini unutmayın. Bu durum, jeton imzalama uygulamasını kolaylaştırabilir.

JWT Kullanım Durumları

Aşağıda, Provider server (Sağlayıcı sunucusu) için örnek bir jeton gösterilmektedir:

{
  "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": "*"
   }
}

Aşağıda Tüketici uygulaması için örnek bir jeton gösterilmektedir:

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

Aşağıda, Sürücü uygulaması için örnek bir jeton gösterilmektedir:

{
  "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"
   }
}
  • Başlıktaki kid alanı için hizmet hesabınızın özel anahtar kimliğini belirtin. Bu değeri, hizmet hesabı JSON dosyanızın private_key_id alanında bulabilirsiniz.
  • iss ve sub alanları için hizmet hesabınızın e-posta adresini belirtin. Bu değeri, hizmet hesabı JSON dosyanızın client_email alanında bulabilirsiniz.
  • aud alanı için https://SERVICE_NAME/ adresini belirtin.
  • iat alanı için jetonun oluşturulduğu anı belirten zaman damgasını kullanın. Bu zaman damgası, 1 Ocak 1970 tarihinde 00:00:00 (UTC) itibarıyla geçen saniye cinsinden belirtilir. Eğme için 10 dakika bekleyin. Zaman damgası çok geçmişte veya çok ilerideyse sunucu bir hata bildirebilir.
  • exp alanı için jetonun süresinin dolduğu anı belirten zaman damgasını kullanın. Bu zaman damgası, 1 Ocak 1970 tarihinde 00:00:00 (UTC) saat diliminden itibaren saniye olarak belirtilir. İzin verilen maksimum değer iat + 3600'dür.

Mobil cihaza aktarılacak JWT'yi imzalarken Sürücü veya Tüketici SDK'sı rolünün hizmet hesabını kullandığınızdan emin olun. Aksi takdirde, mobil cihaz, olmaması gereken durumu değiştirme yeteneğine sahiptir.

Benzer şekilde, ayrıcalıklı çağrılar için kullanılmak üzere JWT'yi imzalarken Süper Kullanıcı rolüne sahip hizmet hesabını kullandığınızdan emin olun. Aksi takdirde işlem başarısız olur.

Test için JWT oluşturma

Terminalden jetonlar oluşturmak, test sırasında faydalı olabilir.

Bu adımları uygulamak için kullanıcı hesabınızın Hizmet Hesabı Jetonu Oluşturucu rolüne sahip olması gerekir:

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

Aşağıdaki içerikle unsigned_token.json adında yeni bir dosya oluşturun. iat özelliği, sıfır zamandan sonra saniye cinsinden geçerli zamandır. Bu bilgiyi terminalinizde date +%s çalıştırılarak alınabilir. exp özelliği, sıfır zamandan itibaren geçen saniye cinsinden geçerlilik bitiş süresidir. Dönemden itibaren geçerli olan süre, iat'a 3600 eklenerek hesaplanabilir. Geçerlilik süresi gelecekteki bir saatten fazla olamaz.

{
  "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": "*"
   }
}

Ardından, jetonu Süper Kullanıcı hizmet hesabınız adına imzalamak için aşağıdaki gcloud komutunu çalıştırın:

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

Artık signed_token.jwt dosyasında Base64 kodlu imzalı bir JWT depolanmalıdır. Jeton önümüzdeki bir saat boyunca geçerlidir.

Artık Araçları Listeleme REST uç noktasına karşı bir curl komutu çalıştırarak jetonu test edebilirsiniz:

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

Araçlar ve yaşam döngüleri

Araç, sürücü-araç çiftini temsil eden tüzel kişidir. Şu anda Sürücü ve Araç ayrı ayrı takip edilememektedir. Araç Paylaşımı veya Teslimat Sağlayıcı, Sağlayıcı Kimliği (Filis Motoru API'lerini çağırmak için kullanılan hizmet hesabını içeren Google Cloud Projesi'nin Proje Kimliği ile aynı olmalıdır) ve Araç Paylaşımı ya da Teslimat Sağlayıcısı'na ait Araç Kimliği kullanarak Araç oluşturur.

Yedi günün ardından UpdateVehicle üzerinden güncellenmemiş Araç otomatik olarak silinir. CreateVehicle, zaten mevcut olan bir sağlayıcı kimliği/araç kimliği çiftiyle çağrılır. Sık sık güncellenmeyen araçlar iki şekilde ele alınabilir: Beklenen bir Sağlayıcı Kimliği/Araç Kimliği çiftiyle sık sık CreateVehicle çağırmak ve Araç zaten varsa hatayı silme; veya UpdateVehicle bir NOT_FOUND hatasıyla döndürüldükten sonra CreateVehicle çağrısı yapmak.

Araç konumu güncellemeleri

Fleet Engine ile en iyi performansı elde etmek için sisteme araç konumu güncellemeleri akışı sağlayın. Bu güncellemeleri sağlamak için aşağıdaki yöntemlerden birini kullanın:

  1. Sürücü SDK'sını (Android, iOS) kullanın.
  2. Özel kod kullanın. Konumlar arka ucunuz üzerinden aktarılıyorsa veya Android ya da iOS dışında cihazlar kullanıyorsanız kullanışlıdır.

Araç türleri

Araç varlığı, zorunlu VehicleType alanını içerir. Bu alan AUTO, TAXI, TRUCK, TWO_WHEELER, BICYCLE veya PEDESTRIAN olarak belirtilebilen bir Category numaralandırması içerir. Araç türü, SearchVehicles ve ListVehicles'de filtre ölçütü olarak kullanılabilir.

Kategori AUTO, TWO_WHEELER, BICYCLE veya PEDESTRIAN olarak ayarlanmışsa araçlar için tüm rotalar ilgili RouteTravelMode öğesini kullanır. Kategori TAXI veya TRUCK olarak ayarlanırsa yönlendirme, AUTO moduyla aynı şekilde değerlendirilir.

Araç özellikleri

Araç varlığı yinelenen bir VehicleAttribute alanı içeriyor. Bu özellikler Fleet Engine tarafından yorumlanmaz. SearchVehicles API, eşleşen Vehicles öğesinin belirtilen değere ayarlanmış tüm dahil edilen özellikleri içermesini zorunlu kılan bir alan içerir.

Özellik alanının, Vehicle mesajında vehicle_type ve supported_trip_types gibi desteklenen diğer birkaç alana ek olduğunu unutmayın.

Araçta kalan referans noktaları

Araç varlığında, waypoints (RPC | REST) adlı tekrarlanan bir TripWaypoint alanı(RPC | REST) bulunuyor. Bu alan, yolculukların diğer ara noktalarını aracın onlara ulaştığı sırayla içerir. Fleet Engine, yolculuklar araca atandıkça bu alanı hesaplar ve seyahat durumları değiştikçe bu alanı günceller. Bu ara noktalar, TripId alanı ve WaypointType alanı tarafından belirlenebilir.

Bir aracın eşleşmeler için uygunluğunu genişletme

Genellikle, yolculuk isteklerini araçlarla eşleştirmekten araç paylaşma veya teslimat sağlayıcı hizmetleri sorumludur. Hizmet, araç özelliklerini kullanarak bir aracı daha fazla sayıda aramaya dahil edebilir. Örneğin, sağlayıcı bir araç tarafından sağlanan ayrıcalık veya kapasite seviyelerine karşılık gelen özelliklere bir grup uygulayabilir. Örneğin, üç düzey, boole değerlerine sahip bir özellik grubu olabilir: is_bronze_level, is_silver_level ve is_gold_level. Araç, bunların üçü için de uygun olabilir. Fleet Engine, gümüş seviye özellikleri gerektiren bir gezi talebi aldığında, aramaya bu araç dahil edilir. Özelliklerin bu şekilde kullanılması, çeşitli özellikler sunan araçları da kapsar.

Araç özelliklerini güncellemenin iki yolu vardır. Bunlardan biri UpdateVehicle API'dir. Bu API'yi kullanırken Araç Özellikleri grubunun tamamı bu değere ayarlanır. Tek bir özelliği güncellemek mümkün değildir. Diğer yöntem ise UpdateVehicleAttributes API'dir. Bu yöntemde yalnızca özellikler güncellenir. İstekteki özellikler yeni değere ayarlanır veya eklenir, belirtilmeyen özellikler değiştirilmez.

NASIL YAPILIR?: Araç Oluşturma

Filoda izlenecek her Araç için bir Vehicle varlığı oluşturulmalıdır.

Araç oluşturmak için CreateVehicleRequest ile CreateVehicle uç noktasını kullanın.

Vehicle öğesinin provider_id öğesi, Fleet Engine'i çağırmak için kullanılacak Hizmet Hesaplarını içeren Google Cloud projesinin Proje Kimliği (ör. istek üzerine-projem) olmalıdır. Aynı Araç Paylaşımı veya Teslimat Sağlayıcısı için birden fazla hizmet hesabı Fleet Engine'e erişebilir ancak Fleet Engine'in şu anda aynı Vehicles alanına erişen birden fazla Google Cloud projesinin hizmet hesaplarını desteklemediğini unutmayın.

Vehicle, OFFLINE veya ONLINE durumunda oluşturulabilir. ONLINE alanı oluşturulursa SearchVehicles sorgularına yanıt olarak hemen döndürülebilir.

CreateVehicle görüşmesine başlangıçtaki bir last_location dahil edilebilir. İzin verilse de, ONLINE durumunda last_location olmadan Vehicle oluşturulmamalıdır.

Araç türü alanıyla ilgili ayrıntılar için Araç Türleri bölümüne bakın.

Özellikler alanıyla ilgili ayrıntılar için Araç Özellikleri'ne bakın.

CreateVehicle öğesinden döndürülen değer, oluşturulan Vehicle varlığıdır.

Örnek

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

providers.vehicles.create referansını inceleyin.

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.

Araç oluşturmayla ilgili Google Cloud Platform günlükleri

Fleet Engine API, CreateVehicle uç noktasına çağrı alındığında Google Cloud platform günlükleri aracılığıyla bir günlük girişi yazar. Günlük girişi, CreateVehicle isteğindeki değerlerle ilgili bilgileri içerir. Arama başarılı olursa geri gelen Vehicle ile ilgili bilgiler de dahil edilir.

shell

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

Aşağıdakine benzer bir kayıt yazdırılmalıdır:

---
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'

Araç oluşturma için Cloud Pub/Sub bildirimleri

Fleet Engine API, yeni bir araç oluşturulduğunda Cloud Pub/Sub üzerinden bildirim yayınlar. Bu bildirimleri almak için lütfen buradaki talimatları uygulayın.

"NASIL YAPILIR?": Bir aracın konumunu güncelleme

Aracın konumunu güncellemek için Sürücü SDK'sını kullanmıyorsanız aracın konumuyla Fleet Engine'e doğrudan çağrı yapabilirsiniz. Fleet Engine, etkin araçlar için en az dakikada bir, en fazla 5 saniyede bir konum güncellemesi yapılmasını bekler. Bu güncellemeler yalnızca Fleet Engine Sürücü SDK'sı Kullanıcı ayrıcalıkları gerektirir.

Örnek

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

providers.vehicles.update referansını inceleyin.

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.

"NASIL YAPILIR?": Diğer Araç alanlarını güncelleme

Araç durumunun diğer niteliklerinde yapılan güncellemeler, konum güncellemelerinden daha seyrek gerçekleşir. last_location dışındaki özelliklerin güncellenmesi için Filo Motoru Süper Kullanıcı ayrıcalıkları gerekir.

UpdateVehicleRequest, hangi alanların güncelleneceğini belirtmek için bir update_mask içerir. Alanın davranışı, alan maskeleriyle ilgili Protobuf dokümanlarındaki gibidir.

Araç Özellikleri bölümünde belirtildiği gibi, attributes alanının güncellenmesi tüm özelliklerin korunmasını gerektirir. Bir UpdateVehicle çağrısında yalnızca tek bir anahtar/değer çiftinin değerini güncellemek mümkün değildir. Belirli özelliklerin değerlerini güncellemek için UpdateVehicleAttributes API kullanılabilir.

Örnek

Bu örnekte back_to_back etkinleştirilmiştir.

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

providers.vehicles.update referansını inceleyin.

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.

Araç Güncellemeleri için Google Cloud Platform günlükleri

Fleet Engine API, UpdateVehicle uç noktasına çağrı alındığında Google Cloud platform günlükleri aracılığıyla bir günlük girişi yazar. Günlük girişi, UpdateVehicle isteğindeki değerlerle ilgili bilgileri içerir. Arama başarılı olursa geri gelen Vehicle ile ilgili bilgiler de dahil edilir.

shell

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

Araç güncellemeleri için Cloud Pub/Sub bildirimleri

Fleet Engine API, mevcut bir araç güncellendiğinde Cloud Pub/Sub üzerinden bildirim yayınlar. Bu bildirimleri almak için lütfen buradaki talimatları uygulayın.

"NASIL YAPILIR?": Araç arama

Fleet Engine, araç aramayı destekler. SearchVehicles API, taksi çağırma veya teslimat isteği gibi görevlere en uygun yakındaki sürücüleri bulmanızı sağlar. SearchVehicles API, filonuzdaki araçların özellikleriyle görev özelliklerini eşleştiren sürücülerin sıralı bir listesini döndürür. Daha fazla bilgi edinmek için Yakındaki sürücüleri bulma başlıklı makaleye göz atın.

Örnek

Mevcut araçlar aranırken Fleet Engine, aktif yolculuklardaki araçları varsayılan olarak hariç tutar. Araç Paylaşımı veya Teslimat Sağlayıcı hizmetlerinin bunları arama isteklerine açıkça dahil etmesi gerekir. Aşağıdaki örnekte, bu araçların GrandIndonesia East Mall'dan Balai Sidang Jakarta Kongre Merkezi'ne yapılan bir seyahatle eşleşen araçlar için aramaya nasıl dahil edileceği gösterilmektedir.

shell

Öncelikle, önceki adımlarda oluşturduğumuz aracın konumunu güncelleyerek aracın uygun olmasını sağlayın. Gerçek dünyada bu, araçtaki bir Android veya iOS cihazda çalışan Driver SDK'sı tarafından yapılır.

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

Arama yapıldığında en azından bu araç sağlanmalıdır.

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

providers.vehicles.search referansına bakın.

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

Araç filtreleme sorgusu

SearchVehicles ve ListVehicles, filtre sorgusu kullanarak araç özelliklerinde filtrelemeyi destekler. Filtre sorgusu söz dizimiyle ilgili örnekler için AIP-160 bölümüne bakın.

Filtre sorgularının YALNIZCA araç özelliklerinde filtrelemeyi desteklediğini ve diğer alanlar için kullanılamayacağını unutmayın. Filtre sorgusu, SearchVehiclesRequest içindeki minimum_capacity veya vehicle_types gibi başka kısıtlamalarla birlikte bir AND ifadesi olarak çalışır.

NASIL YAPILIR?: Araçları listeleme

SearchVehicles, az sayıda aracı çok hızlı bir şekilde sıralı olarak bulmak için optimize edilmiştir ve çoğunlukla yakındaki bir göreve en uygun sürücüleri bulmak için kullanılır. Ancak bazen, sonuçları incelemek gerekli olsa bile bazı kriterleri karşılayan tüm araçları bulmak istersiniz. ListVehicles, bu kullanım alanı için tasarlanmıştır.

ListVehicles API, bazı belirli istek seçeneklerini karşılayan tüm araçları bulmanıza olanak tanır. ListVehicles API, projedeki bazı gereksinimleri karşılayan araçların sayfalara ayrılmış bir listesini döndürür.

Araç özelliklerini filtrelemek için lütfen Araç filtreleme sorgusu bölümüne bakın.

Örnek

Bu örnekte, vehicle_type ve özellikler filter dizesini kullanarak filtreleme gerçekleştirilir.

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

providers.vehicles.list referansını inceleyin.

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

Geziler ve yaşam döngüleri

Trip API ve yaşam döngüsü, Vehicle API'ye ve yaşam döngüsüne benzer. Rideshare Sağlayıcısı, Fleet Engine arayüzlerini kullanarak geziler oluşturmaktan sorumludur. Fleet Engine, hem RPC hizmeti TripService hem de REST kaynakları provider.trips sunar. Bu arayüzler Seyahat varlığı oluşturma, bilgi istekleri, arama işlevi ve güncelleme özelliğini etkinleştirir.

Trip, yaşam döngüsü boyunca ilerlemesini izlemek için bir durum alanına sahiptir. NEW değerinden COMPLETE değerine, ayrıca CANCELED ve UNKNOWN_TRIP_STATUS değerine taşınır. RPC için trip_status veya REST için TripStatus bölümüne bakın.

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

Hizmetiniz, seyahati bu durumlardan herhangi birini kullanarak CANCELED olarak güncelleyebilir. Hizmetiniz bir gezi oluşturduğunda motor, durumu NEW olarak ayarlar. vehicle_id isteğe bağlıdır. Araçlarda olduğu gibi, hizmetler de yedi gün sonra, herhangi bir güncelleme olmadan yolculukları otomatik olarak siler. Hizmetiniz zaten mevcut olan bir kimlikle seyahat oluşturmaya çalışırsa bir hata döndürülür. COMPLETE veya CANCELED dışındaki durumlarda seyahat "etkin" olarak kabul edilir. Bu ayrım, Araç varlığındaki active_trips alanı ve SearchTripsRequest açısından önemlidir.

Hizmet, bir Seyahate atanan vehicle_id değerini yalnızca durum NEW veya CANCELED olduğunda değiştirebilir. Sürücü bir yolculuk sırasında bir Seyahati iptal ederse vehicle_id değiştirilmeden veya silinmeden önce Seyahat durumu NEW veya CANCELED olarak ayarlanmalıdır.

Arka arkaya yolculuk desteği uygulanırken durum önemlidir. Bu destek sayesinde Sağlayıcı, Araç aktif bir Yolculuk devam ederken araca yeni bir gezi atayabilir. Arka arkaya Seyahat oluşturmak için kullanılan kod, tek bir geziyle aynıdır ve aynı araç kimliğini kullanır. Fleet Engine, yeni yolculuğun başlangıç ve varış noktalarını aracın ara noktalarına ekler. Arka arkaya geziler hakkında daha fazla bilgi için Birden çok ara nokta gezileri oluşturma bölümüne bakın.

Yolculuk için kalan ara noktalar

Seyahat varlığı, remainingWaypoints (RPC | REST) adlı yinelenen bir TripWaypoint alanı(RPC | REST) içerir. Bu alan, bu yolculuğun son teslim noktasından önce aracın sırasıyla gitmesi gereken tüm ara noktaları içerir. Aracın kalan ara noktalarını temel alarak hesaplama yapar. Arka arkaya ve Ortak Araba Kullanımı kullanım örneklerinde bu liste, bu yolculuktan önce katedilecek diğer yolculuklardan ara noktaları içerir, ancak bu geziden sonraki ara noktaları içermez. Listedeki referans noktası, TripId ve WaypointType değerlerine göre belirlenebilir.

Yolculuk durumu ve Araçta kalan ara noktalar arasındaki ilişki

Fleet Engine, gezi durumu değişikliği isteği aldığında aracın kalan ara noktaları (RPC | REST) güncellenir. tripStatus(RPC | REST) diğer durum olan ENROUTE_TO_XXX olarak değiştirildiğinde, önceki referans noktası Aracın kalan ara noktalar listesinden kaldırılacaktır. Yani yolculuk durumu ENROUTE_TO_PICKUP iken ARRIVED_AT_PICKUP olarak değiştirildiğinde, yolculuğun başlangıç noktası Aracın kalan ara nokta listesinde kalmaya devam eder ancak gezi durumu ENROUTE_TO_INTERMEDIATE_DESTINATION veya ENROUTE_TO_DROPOFF şeklinde değiştirildiğinde aracın başlangıç noktası kaldırılır.

Bu, ARRIVED_AT_INTERMEDIATE_DESTINATION ve ENROUTE_TO_INTERMDEDIATE_DESTINATION için de aynıdır. ARRIVED_AT_INTERMEDIATE_DESTINATION olduğunda, araç bir sonraki ara noktaya gittiğini bildirene kadar mevcut ara hedef, Aracın kalan ara nokta listesinden kaldırılmaz.

Yolculuk durumu COMPLETED olarak değiştirildiğinde, bu yolculuktaki ara nokta Aracın kalan ara nokta listesinde yer almaz.

"NASIL YAPILIR?": Gezi oluşturun

Her seyahat isteğinin izlenebilmesi ve filodaki Araçlar ile eşleştirilebilmesi için Trip varlığı oluşturulmalıdır. Gezi oluşturmak için CreateTripRequest ile CreateTrip uç noktasını kullanın.

Gezi oluşturmak için aşağıdaki özellikler gereklidir:

  • parent: Google Cloud projesi oluşturulurken oluşturulan Sağlayıcı kimliğini içeren bir dize.
  • trip_id: Araç Paylaşımı Sağlayıcısı tarafından oluşturulan dize.
  • trip: Geziyi açıklayan temel meta verileri içeren kapsayıcı.
    • trip_type - Yolculukta farklı kalkış ve varış noktalarından aynı araçta (SHARED) veya yalnızca tek taraflı (EXCLUSIVE) yolcuların bulunabileceğini gösteren sıralama.
    • pickup_point - Yolculuğun başlangıç noktasını temsil eden TerminalLocation. RPC referansı veya REST referansı sayfasına bakın

Bir gezi oluşturduğunuzda, number_of_passengers, dropoff_point ve vehicle_id bilgilerini sağlayabilirsiniz. Bu alanlar zorunlu değildir, ancak sağlarsanız korunurlar. Diğer tüm Seyahat alanları yok sayılır. Örneğin, oluşturma isteğinde CANCELED öğesinin trip_status değerini geçirseniz bile tüm geziler NEW trip_status ile başlar.

Örnek

Aşağıdaki örnek, Grand Indonesia East Mall'a gezi oluşturmaktadır. Gezi iki yolculu ve özeldir. Trip öğesinin provider_id öğesi, proje kimliğiyle aynı olmalıdır. Örnekte, Rideshare Provider project-id adlı Google Cloud projesini oluşturdu. Bu projede, Fleet Engine'i çağırmak için kullanılan Hizmet Hesapları bulunmalıdır. Gezinin durumu: NEW.

Daha sonra hizmet, geziyi bir araçla eşleştirdikten sonra UpdateTrip numarasını arayabilir ve yolculuk bir araca atandığında vehicle_id değerini değiştirebilir.

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

providers.trips.create referansına bakın.

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

Seyahat Oluşturma ile ilgili Google Cloud platform günlükleri

Fleet Engine API, CreateTrip uç noktasına çağrı alındığında Google Cloud platform günlüklerini kullanarak bir günlük girişi yazar. Günlük girişi, CreateTrip isteğindeki değerlerle ilgili bilgileri içerir. Arama başarılı olursa döndürülen Trip ile ilgili bilgiler de eklenir.

"NASIL YAPILIR?": Bir geziyi güncelleme

Seyahat varlığı, hizmet tarafından izlemeyi ve Sürücü SDK'sı ile Tüketici SDK'sı tarafından seyahat ilerlemesinin raporlanmasını sağlayan alanlar içerir. Özellikleri güncellemek için UpdateTripRequest mesajını kullanın. Bu işlemle Seyahat alanları, isteğin field_mask değerine göre güncellenir. UpdateTripRequest konusuna bakın.

Rideshare Sağlayıcısı aşağıdaki özelliklerin güncellenmesinden sorumludur:

  • Gezi durumu.
  • Araç kimliği. Bu, oluşturma sırasında veya aracı bir geziyle eşleştirdikten sonra gerçekleştirilir.
  • Teslim alma, bırakma veya ara noktalarla ilgili değişiklikler.

Fleet Engine, Driver SDK'sı veya Tüketici SDK'sı üzerinden Juourney Paylaşımı özelliğini kullanırken aşağıdaki alanları otomatik olarak günceller:

  • Rotalar
  • TVS
  • Kalan mesafe
  • Araç konumu
  • Kalan ara noktalar

TripRPC'de veya REST'te Resource.Trip bölümüne bakın.

Seyahat Güncellemeleri için Google Cloud Platform günlükleri

Fleet Engine API, UpdateTrip uç noktasına çağrı alındığında Google Cloud platform günlüklerini kullanarak bir günlük girişi yazar. Günlük girişi, UpdateTrip isteğindeki değerlerle ilgili bilgileri içerir. Çağrı başarılı olursa döndürülen Trip ile ilgili bilgileri de içerir.

NASIL YAPILIR?: Gezi arama

Fleet Engine, seyahat aramayı destekler. Daha önce de belirtildiği gibi, bir Seyahat yedi gün sonra otomatik olarak silinir. Bu nedenle, SearchTrips tüm Seyahatlerin geçmişini tam olarak göstermez.

SearchTrips esnek bir API olsa da, aşağıdaki listede iki kullanım alanı dikkate alınmıştır.

  • Bir Aracın Aktif Seyahatlerini Belirleme -- Sağlayıcı, aracın o anda aktif olan yolculuklarını belirleyebilir. SearchTripsRequest içinde vehicle_id, değerlendirilen araca, active_trips_only ise true olarak ayarlanmalıdır.

  • Sağlayıcı ile Filo Motoru Durumunu Uzlaştırma -- Sağlayıcı, SearchTrips ile kendi Seyahat durumunun ve Fleet Engine'in durumunu eşleştirmesini sağlayabilir. Bu, özellikle TripStatus için önemlidir. Bir Araca atanan gezinin durumu COMPLETE veya CANCELED olarak doğru bir şekilde ayarlanmadıysa SearchVehicles aracı bu listeye dahil edilmez.

SearchTrips parametresini bu şekilde kullanmak için vehicle_id öğesini boş bırakın, active_trips_only değerini true olarak ayarlayın ve minimum_staleness değerini çoğu gezi süresinden daha uzun bir süreye ayarlayın. Örneğin, bir saat kullanabilirsiniz. Sonuçlar, TAMAMLANMAYAN veya İPTAL EDİLMEYEN ve bir saatten uzun süredir güncellenmemiş Seyahatleri içerir. Sağlayıcı, Fleet Engine'deki durumlarının doğru şekilde güncellendiğinden emin olmak için bu Gezileri incelemelidir.

Sorun giderme

DEADLINE_EXCEEDED Hatası durumunda Fleet Engine'in durumu bilinmiyor. Sağlayıcı CreateTrip öğesini tekrar çağırmalıdır. Bu çağrı, 201 (OLUŞTURULDU) veya 409 (ÇAKIŞMA) döndürür. İkinci durumda, önceki istek DEADLINE_EXCEEDED tarihinden önce başarılı olmuştur. Gezi hatalarını ele alma hakkında daha fazla bilgi için Consumer API kılavuzlarına bakın: Android veya iOS.

Ortak araba kullanımı desteği

TripType.SHARED destekleyen bir araca birden fazla SHARED gezisi atayabilirsiniz. vehicle_id öğesini paylaşılan bir seyahat için atadığınızda (CreateTrip veya UpdateTrip isteğinde) Trip.vehicle_waypoints üzerinden, bu ortak yolculukta Araca atanmış tüm Seyahatler için geçilmemiş tüm ara noktaların sırasını belirtmeniz gerekir. RPC için vehicle_waypoints veya REST için vehicleWaypoints bağlantısını inceleyin.

Birden çok hedef desteği

Ara hedef belirleme

Seyahat'teki intermediateDestinations alanı ve intermediateDestinationIndex alanı (RPC | REST) hedefi belirtmek için kullanılmak üzere birleştirilir.

Ara hedefi güncelle

Ara hedefleri UpdateTrip üzerinden güncelleyebilirsiniz. Ara hedefleri güncellerken, yalnızca yeni eklenen veya değiştirilecek hedefler değil, ziyaret edilenler de dahil olmak üzere ara hedeflerin tam bir listesini sağlamanız gerekir. intermediateDestinationIndex, yeni eklenen/değiştirilmiş ara hedefin konumundan sonraki bir dizini işaret ettiğinde, yeni/güncellenen ara hedef, aracın waypoints veya gezi remainingWaypoints değerine eklenmez. Bunun nedeni, intermediateDestinationIndex tarihinden önceki tüm ara hedeflerin önceden ziyaret edilmiş olarak değerlendirilmesidir.

Gezi durumundaki değişiklikler

(RPC | REST) içindeki intermediateDestinationsVersion alanı, Fleet Engine'e gönderilen Seyahat durumu güncelleme isteğinde, ara bir hedefin geçtiğini belirtmek için gereklidir. Hedeflenen ara hedef, intermediateDestinationIndex alanı aracılığıyla belirtilir. tripStatus (RPC | REST) ENROUTE_TO_INTERMEDIATE_DESTINATION olduğunda [0..N-1] arasındaki bir sayı, aracın bundan sonra hangi ara hedefi geçeceğini belirtir. tripStatus ARRIVED_AT_INTERMEDIATE_DESTINATION olduğunda, [0..N-1] arasında bir sayı, aracın hangi ara hedefte olduğunu gösterir.

Örnek

Aşağıdaki kod örneği, çok varışlı bir gezi oluşturduğunuzu ve gezinin başlangıç noktasını geçtiğini varsayarak ilk ara varış noktasına giden bir gezi durumunun nasıl güncelleneceğini gösterir.

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

NASIL YAPILIR?: Fleet Engine API'den bildirim mesajlarına abone olun

Fleet Engine API, tüketici Google Cloud Projesi tarafından oluşturulan konu hakkında bildirimler yayınlamak için Google Cloud Pub/Sub'ı kullanır. Google Cloud projenizde Fleet Engine için Pub/Sub etkin değildir. Pub/Sub'ı etkinleştirmek için lütfen bir destek kaydı oluşturun veya Müşteri Mühendisinizle iletişime geçin.

Cloud Projenizde konu oluşturmak için bu talimatları uygulayın. Konu kimliği "fleet_engine_notifications" olmalıdır.

Konu, Fleet Engine API'lerini çağıran Cloud projesinde oluşturulmuş olmalıdır.

Konu oluşturulduktan sonra, Fleet Engine API'ye konu hakkında yayın yapma izni vermeniz gerekir. Bunu yapmak için az önce oluşturduğunuz konuyu tıklayın ve yeni izin ekleyin. İzin düzenleyicisini açmak için BİLGİ PANELİNİ GÖSTER'i tıklamanız gerekebilir. Ana hesap geo-fleet-engine@system.gserviceaccount.com, rol ise Pub/Sub publisher olmalıdır.

Cloud projenizi bildirimlere abone olacak şekilde ayarlamak için bu talimatları uygulayın.

Fleet Engine API, her bildirimi iki farklı veri biçiminde (protobuf ve json) yayınlar. Her bildirimin veri biçimi PubsubMessage özelliklerinde anahtar data_format, değer ise protobuf veya json ile belirtilir.

Bildirim şeması:

Protokol Arabelleğ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

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