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:
- Google Cloud Console'u kullanarak Google Cloud projesi oluşturun.
- 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:
Rol | Açı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:
Alan | Açı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:
Alan | Açı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ınprivate_key_id
alanında bulabilirsiniz. iss
vesub
alanları için hizmet hesabınızın e-posta adresini belirtin. Bu değeri, hizmet hesabı JSON dosyanızınclient_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ğeriat
+ 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:
- Sürücü SDK'sını (Android, iOS) kullanın.
- Ö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
Trip
RPC'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çindevehicle_id
, değerlendirilen araca,active_trips_only
isetrue
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 durumuCOMPLETE
veyaCANCELED
olarak doğru bir şekilde ayarlanmadıysaSearchVehicles
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"
}
}
}