Fleet Engine On-İsteğe Bağlı Yolculuklar ve Teslimatlar API'si, Seyahat ve Sipariş İlerlemesi uygulamalarınız için gezileri 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ç hizmeti, 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 projeniz için kimlik doğrulaması yaptığınızdan emin olun.
shell
gcloud auth login
Şuna benzer bir başarı mesajı görmeniz gerekir:
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 bir hatayla sonuçlanırsa erişim izni almak için proje yöneticinizle ve Google destek temsilcinizle görüşün.
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 etme hakkında genel bilgiler için Cloud Logging belgelerine bakın.
10 Şubat 2022'den önce oluşturulan projeler için günlük kaydı varsayılan olarak etkin olmayabilir. Daha fazla bilgi için günlük kaydı belgelerini inceleyin.
İstemci Kitaplıkları
Yaygın olarak kullanılan birkaç programlama dilinde istemci kitaplıkları yayınlıyoruz. Bu kitaplıklar, ham REST veya gRPC yerine daha iyi bir geliştirici deneyimi sağlamaya 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 belgelerdeki Java örneklerinde gRPC hakkında bilgi sahibi olduğu varsayılır.
Kimlik Doğrulama ve Yetkilendirme
Yolculuk ve Sipariş İlerlemesi tarafından sağlanan özellikleri, Google Cloud Console üzerinden yapılandırabilirsiniz. Bu API'ler ve SDK'lar, Cloud Console'dan oluşturulan hizmet hesaplarıyla imzalanmış JSON Web Jetonlarının kullanılmasını gerektirir.
Bulut projesi kurulumu
Bulut projenizi kurmak için önce projenizi, ardından hizmet hesapları oluşturun.
Google Cloud projenizi oluşturmak için:
- Google Cloud Console'u kullanarak bir Google Cloud projesi oluşturun.
- API'ler ve Hizmetler Kontrol Paneli'ni kullanarak Local Rides and Deliveries API'sini etkinleştirin.
Hizmet hesapları bir veya daha fazla rolle ilişkilendirilmiş. Rollere bağlı olarak farklı izin grupları veren JSON Web Jetonları oluşturmak için kullanılırlar. Genellikle, kötüye kullanım olasılığını azaltmak için her biri gereken minimum rol grubuna sahip birden fazla hizmet hesabı oluşturabilirsiniz.
Gezi ve Sipariş İlerlemesi aşağıdaki rolleri kullanır:
Rol | Açıklama |
---|---|
Fleet Engine Tüketici SDK'sı Kullanıcısı
roles/fleetengine.consumerSdkUser |
Araç arama ve araçlar ile geziler hakkında bilgi alma izni verir. Bu role sahip bir hizmet hesabı tarafından oluşturulan jetonlar genellikle araç paylaşımı veya teslimat tüketici uygulaması mobil cihazlarınızdan kullanılır. |
Fleet Engine Sürücü SDK'sı 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 araç paylaşımı veya teslimat sürücüsü uygulaması mobil cihazlarınızdan kullanılır. |
Fleet Engine İsteğe Bağlı Yönetici
roles/fleetengine.ondemandAdmin |
Tüm araç ve gezi kaynakları için okuma ve yazma izni verir. Bu role sahip ana hesapların JWT kullanmasına gerek yoktur, bunun yerine Uygulama Varsayılan Kimlik Bilgilerini kullanmalıdır. Özel JWT talepleri yoksayılır. Bu rol güvenilir ortamlarla (müşteri arka ucu) sınırlı olmalıdır. |
roles/fleetengine.serviceSuperUser |
Tüm araçlara ve yolculuk API'lerine izin verir. Bu role sahip bir hizmet hesabı tarafından basılan jetonlar genellikle arka uç sunucularınızdan kullanılır. Bu rol kullanımdan kaldırıldı. Bunun yerine
roles/fleetengine.ondemandAdmin tercih edilir. |
Örneğin, üç rolün her biri için birer hizmet hesabı oluşturun ve bunlara ilgili rolleri 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 roller temel alınarak oluşturulmuştur.
Alternatif olarak, rastgele izin grubunun birlikte gruplandırılmasına olanak tanıyan özel roller oluşturabilirsiniz. Sürücü ve Tüketici SDK'ları, gerekli bir izin eksik olduğunda hata mesajları gösterir. Sonuç olarak, yukarıda sunulan standart rol grubunu ve özel rolleri kullanmamanızı önemle öneririz.
Güvenilmeyen istemciler için JWT jetonları oluşturmanız gerekiyorsa kullanıcıları Hizmet Hesabı Jetonu Oluşturucu rolüne ekleyerek gcloud komut satırı araçlarıyla jeton oluşturabilirler.
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 Kimlik Doğrulama Kitaplığı
Fleet Engine, Fleet Engine API'lerine erişimi kısıtlamak için JSON Web Jetonlarını (JWT) kullanır. GitHub'da bulunan yeni Fleet Engine Auth Kitaplığı, Fleet Engine JWT'lerinin oluşturulmasını kolaylaştırır 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 jeton imzalama mekanizmaları sağlar (bir hizmet hesabının kimliğine bürünme gibi).
- İmzalanmış jetonları gRPC saplamasından veya GAPIC istemcisinden yapılan giden isteklere ekler.
Yetkilendirme için JSON Web Token (JWT) oluşturma
Fleet Engine Auth Kitaplığı'nı kullanmadığınızda, JSON Web Jetonlarının (JWT) doğrudan kod tabanınızda oluşturulması gerekir. Bunun için hem JWT'leri hem de Fleet Engine'le olan ilişkilerini iyice kavramanız gerekir. Bu nedenle, Fleet Engine Auth Kitaplığı'ndan yararlanmanızı ÖNEMLE tavsiye ederiz.
Fleet Engine'de JSON Web Jetonları (JWT'lar) kısa ömürlü kimlik doğrulama sağlar ve cihazların yalnızca yetkilendirildikleri araçları, yolculukları 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 elde edilir) ve şifreleme algoritması gibi bilgiler yer alır. Talep bölümünde jetonun oluşturulma zamanı, jeton geçerlilik süresi, erişim talebinde bulunduğu hizmetler ve erişim kapsamını daraltmak için araç kimliği gibi diğer yetkilendirme bilgileri gibi bilgiler yer alır.
JWT başlığı 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ından anahtar kullandığınızdan emin olun. |
JWT hak 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. |
Aud | Hizmet hesabınızın SERVICE_NAME hizmeti (bu örnekte https://fleetengine.googleapis.com/) |
iat | Jetonun oluşturulduğu anı belirten zaman damgası (1 Ocak 1970'te 00:00:00 (UTC) tarihinden itibaren geçen saniye cinsinden belirtilir. Eğiklik için 10 dakika bekleyin. Zaman damgası çok geçmişte veya gelecekteyse sunucu bir hata bildirebilir. |
exp | Jetonun süresinin dolmasına kalan zaman damgası (1 Ocak 1970 00:00:00 UTC itibarıyla geçen saniye cinsinden belirtilir). Zaman damgası gelecekte bir saatten daha ilerideyse 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ını yetkilendirme başlıklı makaleyi inceleyin. Ardından, imzalı bir jeton gRPC çağrılarına veya Fleet Engine'e erişmek için kullanılan diğer yöntemlere 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ğinin veya gezi kimliğinin değerine ayarlandığı ek bir talep ekleyin.
Sürücü SDK'sı, seyahatte veya araçta çalışma fark etmeksizin her zaman vehicleid
iddiasını kullanır. Fleet Engine arka ucu, değişikliği yapmadan önce aracın istenen seyahatle 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 Seyahatleri eşleştirmek için vehicleid
ya da tripid
"*" ile birlikte kullanılmalıdır. JWT'nin gerekli olmasa bile her iki jetonu da içerebileceğini unutmayın. Bu, jeton imzalama uygulamasını basitleştirebilir.
JWT Kullanım Alanları
Aşağıda 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/ değerini belirtin.iat
alanı için jetonun oluşturulduğu sıradaki zaman damgasını kullanın. Bu zaman damgası, 1 Ocak 1970 tarihinde 00:00:00 UTC itibarıyla geçen saniye olarak belirtilir. Eğiklik için 10 dakika bekleyin. Zaman damgası çok geçmişte veya gelecekteyse sunucu bir hata bildirebilir.exp
alanı için jetonun süresi dolduğunda, 1 Ocak 1970 00:00:00 (UTC) tarihinden itibaren saniye cinsinden belirtilen zaman damgasını kullanın. İzin verilen maksimum değeriat
+ 3.600'dür.
Mobil cihaza aktarılacak JWT'yi imzalarken, Sürücü veya Tüketici SDK'sı rolü için hizmet hesabını kullandığınızdan emin olun. Aksi takdirde, mobil cihaz, olmaması gereken durumu değiştirebilir.
Benzer şekilde, ayrıcalıklı çağrılarda kullanılacak JWT'yi imzalarken, hizmet hesabını Süper Kullanıcı rolüne sahip kullandığınızdan emin olun. Aksi takdirde işlem başarısız olur.
Test için JWT oluşturma
Terminalden jeton oluşturmak test sırasında faydalı olabilir.
Bu adımları uygulayabilmek 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, dönemden sonraki saniye cinsinden geçerli zamandır. Terminalinizde date +%s
çalıştırılarak alınabilir. exp
özelliği, dönemden sonraki saniye cinsinden geçerlilik süresidir. Bu süre, iat
öğesine 3.600 değeri eklenerek hesaplanabilir. Geçerlilik süresi, gelecek 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, Süper Kullanıcı hizmet hesabınız adına jetonu 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
İmzalanmış Base64 kodlu bir JWT, artık signed_token.jwt
dosyasında depolanmalıdır. Jeton önümüzdeki bir saat boyunca geçerlidir.
Artık List Vehicles REST uç noktasına 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ç, bir sürücü-araç çiftini temsil eden tüzel kişidir. Şu anda Sürücü ve Araç ayrı ayrı izlenememektedir. Yolculuk Paylaşımı veya Teslimat Sağlayıcısı, bir Sağlayıcı Kimliği (Fleet Engine 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 bir Yolculuk Paylaşımı veya Teslimat Sağlayıcıya ait Araç Kimliği kullanarak Araç oluşturur.
Yedi gün geçmesine rağmen UpdateVehicle
aracılığıyla güncellenmemiş bir Araç
otomatik olarak silinecek ve varsa atanmış yolculukları
atanmadı olarak işaretlenecek. Bir aracı Fleet Engine'de kullanılabilir durumda tutmak için önerilen yaklaşım, aracın konumunu düzenli aralıklarla güncellemektir. Vehicle
varlığındaki diğer alanların çoğunda yapılan güncellemeler de yeni alan değerinin mevcut değerden farklı olması koşuluyla cihazın ömrünü uzatır.
NOT: Vehicle
varlığındaki device_settings
gibi bazı alanlar, Fleet Engine tarafından sürdürülmeyen, tamamen hata ayıklama bilgileridir. Bunları güncellemek Vehicle
varlığının ömrünü uzatmaz.
Halihazırda mevcut bir Sağlayıcı Kimliği/Araç Kimliği çiftiyle CreateVehicle
işlevinin çağrılması hatadır. Sıkça
güncellenmeyen araçlarla ilgili iki şekilde ele alınabilir: CreateVehicle
için beklenen bir sağlayıcı kimliği/araç kimliği çiftiyle sık sık çağrı yapmak ve araç zaten varsa
hatayı silmek veya UpdateVehicle
bir NOT_FOUND
hatasıyla geri döndüğünde CreateVehicle
.
Araç konumu güncellemeleri
Fleet Engine ile en iyi performansı elde etmek için araç konumu güncellemelerinin bir akışını sağlayın. Bu güncellemeleri sağlamak için aşağıdaki yöntemlerden birini kullanın:
- Driver SDK'sını kullanın - Android, iOS - en basit seçenek.
- Özel kod kullanın. Bu kod, konumların arka ucunuz üzerinden aktarıldığı durumlarda 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çeriyor. Bu alanda AUTO
, TAXI
, TRUCK
, TWO_WHEELER
, BICYCLE
veya PEDESTRIAN
olarak belirtilebilen bir Category
sıralaması yer alıyor. Araç türü, SearchVehicles
ve ListVehicles
için filtre ölçütü olarak kullanılabilir.
Kategori AUTO
, TWO_WHEELER
, BICYCLE
veya PEDESTRIAN
olarak ayarlanırsa araçlar için tüm rotalarda ilgili RouteTravelMode
kullanılı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 özellikleri içermesini zorunlu kılan bir alan içerir.
Özellik alanının, Vehicle
mesajında desteklenen diğer birkaç alana (ör. vehicle_type
ve supported_trip_types
) ek olarak yer aldığını unutmayın.
Araç kalan ara noktaları
Araç varlığı, waypoints
(RPC | REST) adlı yinelenen bir TripWaypoint
(RPC | REST alanı içeriyor).
Bu alan, aracın ulaştığı sıraya göre yolculuklardaki kalan ara noktaları içerir. Fleet Engine, bu alanı seyahatler araca atanırken hesaplar ve geziler durumları değiştikçe günceller.
Bu referans noktaları, TripId
alanı ve WaypointType
alanı ile tanımlanabilir.
Bir aracın eşleşmeler için uygunluğunu genişletme
Genellikle, seyahat taleplerinin araçlarla eşleştirilmesinden Araç Paylaşımı veya Teslimat Sağlayıcısı hizmetleri sorumludur. Hizmet, bir aracı daha fazla sayıda aramaya dahil etmek için araç özelliklerini kullanabilir. Örneğin sağlayıcı, bir araç tarafından sağlanan ayrıcalık veya yetenek seviyelerine karşılık gelen bir dizi özellik uygulayabilir. Örneğin, üç düzey, boole değerlerine sahip bir özellik grubu olabilir: is_bronze_level
, is_silver_level
ve is_gold_level
. Bir araç üçü için de uygun olabilir. Fleet Engine, gümüş seviye özellikleri gerektiren bir yolculuk için istek aldığında, arama bu aracı içerir.
Özelliklerin bu şekilde kullanılması, çeşitli yetenekler sunan araçları da kapsar.
Araç özelliklerini güncellemenin iki yolu vardır. Biri, UpdateVehicle
API'dir. Bu API kullanılırken Araç Özellikleri grubunun tamamı değere ayarlanır. Yalnızca tek bir özelliği güncellemek mümkün değildir.
Diğer yöntem UpdateVehicleAttributes
API'sidir. Bu yöntemde yalnızca özelliklerin güncellenmesi gerekir. İstekte yer alan özellikler yeni değere ayarlanır veya eklenir; belirtilmemiş özellikler değiştirilmez.
Nasıl Yapılır?: 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 Projesi'nin Proje Kimliği (ör. isteğe bağlı projesim) olmalıdır. Birden fazla hizmet hesabı, aynı Yolculuk Paylaşımı veya Teslimat Sağlayıcısı için Fleet Engine'e erişebilir ancak Fleet Engine'in, aynı Vehicles
öğesine erişen birden fazla Google Cloud projesinin hizmet hesaplarını şu anda desteklemediğini unutmayın.
Vehicle
, OFFLINE
veya ONLINE
durumunda oluşturulabilir. ONLINE
oluşturulduysa SearchVehicles
sorgularına yanıt olarak hemen döndürülebilir.
CreateVehicle
görüşmesine ilk last_location
dahil edilebilir.
İzin verildiği durumlarda, 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 bölümü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şturma için Google Cloud platform günlükleri
CreateVehicle
uç noktasına çağrı alındığında Fleet Engine API, 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 döndürülen 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şturmayla ilgili Cloud Pub/Sub bildirimleri
Fleet Engine API, yeni bir araç oluşturulduğunda Cloud Pub/Sub aracılığıyla 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 Driver SDK'sını kullanmıyorsanız aracın konumunu belirterek Fleet Engine'e doğrudan çağrı yapabilirsiniz. Fleet Engine, tüm etkin araçlar için en az dakikada bir, en çok 5 saniyede bir konum güncellemesi bekler. Bu güncellemeler için yalnızca Fleet Engine Sürücü SDK'sı Kullanıcısı ayrıcalığı gerekir.
Ö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ına bakın.
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 özelliklerinde yapılan güncellemeler, konum güncellemelerinden daha seyrek gerçekleşir. last_location
dışındaki özelliklerde yapılan güncellemeler, Fleet Engine Süper Kullanıcı ayrıcalıkları gerektirir.
UpdateVehicleRequest
, hangi alanların güncelleneceğini belirtmek için bir update_mask
içerir. Alanın davranışı, alan maskeleri için Protobuf dokümanlarındaki gibidir.
Araç Özellikleri bölümünde belirtildiği gibi, attributes
alanının güncellenmesi için tüm özelliklerin korunması gerekir. UpdateVehicle
çağrısındaki tek bir anahtar/değer çiftinin değeri güncellenemez. Belirli özelliklerin değerlerini güncellemek için UpdateVehicleAttributes
API kullanılabilir.
Örnek
Bu örnekte back_to_back
etkinleştirilir.
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ına bakın.
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
UpdateVehicle
uç noktasına çağrı alındığında Fleet Engine API, 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 döndürülen 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 aracılığıyla 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, bir taksi hizmeti veya teslimat isteği gibi bir göreve en uygun olan yakındaki sürücüleri bulmanızı sağlar. SearchVehicles
API, görev özelliklerini filonuzdaki araçların özellikleriyle eşleşen sürücülerin sıralı bir listesini döndürür. Daha fazla bilgi için Yakındaki sürücüleri bulma bölümüne bakın.
Örnek
Fleet Engine, uygun araçlar ararken varsayılan olarak etkin yolculuklardaki araçları hariç tutar. Araç paylaşma veya teslimat sağlayıcı hizmetleri, bunları arama isteklerine açık bir şekilde dahil etmelidir. Aşağıdaki örnekte, GrandIndonesia East Mall'dan Balai Sidang Jakarta Kongre Merkezi'ne seyahatle eşleşen araçları aramaya bu araçların nasıl dahil edileceği gösterilmektedir.
shell
Öncelikle, önceki adımlarda oluşturduğumuz aracın konumunu güncelleyerek araca uygun hale getirin. Gerçek dünyada bu, araçtaki bir Android veya iOS cihazda çalışan Sürücü 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 gerçekleştirilirse en azından bu araç getirilmelidir.
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ını inceleyin.
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 kullanılarak araç özelliklerinde filtrelemeyi destekler. Filtre sorgusu söz dizimiyle ilgili örnekler için AIP-160'a göz atı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 diğer kısıtlamalarla birlikte bir AND
ifadesi olarak işlev görür.
NASIL YAPILIR?: Araçları listeleme
SearchVehicles
, sıralamadaki az sayıda aracı çok hızlı bir şekilde bulmak için optimize edilmiştir ve çoğunlukla, yakındaki bir göreve en uygun sürücüleri bulmak amacıyla kullanılır. Ancak bazen sonuçları gözden geçirmek 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, belirli istek seçeneklerini karşılayan tüm araçları bulmanızı sağlar. ListVehicles
API, projede bazı gerekliliklerle eşleşen araçların sayfalara ayrılmış bir listesini döndürür.
Araç özelliklerine göre filtreleme yapmak için lütfen Araç filtreleme sorgusu konusuna bakın.
Örnek
Bu örnekte, filter
dizesini kullanarak vehicle_type
ve özellikler üzerinde filtreleme gerçekleştirilmektedir.
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
Triest API ve yaşam döngüsü, Vehicle API ve yaşam döngüsüne benzer.
Yolculuk Paylaşımı Sağlayıcısı, Fleet Engine arayüzlerini kullanarak gezi oluşturmaktan sorumludur. Fleet Engine hem RPC hizmeti hem de
TripService
ve REST kaynakları (provider.trips
) sağlar. Bu arayüzler Seyahat varlığı oluşturma, bilgi isteği, arama işlevi ve güncelleme olanağı sağlar.
Trip
, yaşam döngüsü boyunca ilerlemesini izlemek için bir durum alanına sahiptir.
Değerler NEW
ile COMPLETE
artı CANCELED
ve UNKNOWN_TRIP_STATUS
aralığından taşınır. RPC için trip_status
veya REST için TripStatus'a bakın.
NEW
ENROUTE_TO_PICKUP
ARRIVED_AT_PICKUP
ENROUTE_TO_INTERMEDIATE_DESTINATION
ARRIVED_AT_INTERMEDIATE_DESTINATION
ENROUTE_TO_DROPOFF
COMPLETE
Hizmetiniz, CANCELED
seyahatini bu durumların herhangi birinden 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 atanmamış gezileri de yedi gün sonra güncelleme yapılmadan otomatik olarak siler. Hizmetiniz zaten mevcut bir kimlikle seyahat oluşturmaya çalışırsa hata döndürülür. COMPLETE
veya CANCELED
dışında bir durumda olan geziler "etkin" olarak kabul edilir. Bu ayrım, araç varlığındaki active_trips
alanı ile SearchTripsRequest
alanı için önemlidir.
Hizmetiniz bir geziye atanan vehicle_id
öğesini yalnızca seyahat etkin olduğunda değiştirebilir. Örneğin, sürücü rotadayken bir yolculuğu iptal ettiğinde ve seyahat farklı bir araca yeniden atandığında bunu yaparsınız.
Arka arkaya gezi desteği uygulanırken durum önemlidir. Bu destek Sağlayıcı'nın, Araç aktif bir Seyahat durumundayken araca yeni bir yolculuk atamasına olanak tanır. Arka arkaya seyahat oluşturmak için kullanılan kod, tek yolculukla aynıdır ve aynı araç kimliğini kullanır. Fleet Engine, yeni seyahatin kalkış ve varış noktalarını aracın ara noktalarına ekler. Arka arkaya seyahatler hakkında daha fazla bilgi edinmek için Birden çok ara nokta içeren geziler oluşturma başlıklı makaleyi inceleyin.
Gezinin kalan ara noktaları
Seyahat varlığı, remainingWaypoints
(RPC | REST) adlı yinelenen bir TripWaypoint
(RPC | REST) alanı içeriyor.
Bu alan, aracın bu gezinin son iniş noktasından önce sırayla gitmesi gereken tüm ara noktaları içerir. Aracın kalan ara noktalarından hesaplama yapar.
Arka arkaya ve Araba Paylaşımı kullanım durumlarında bu liste, bu geziden önce geçilecek diğer gezilere ait ara noktaları içerir ancak bu geziden sonraki ara noktaları içermez. Listedeki ara nokta, TripId
ve WaypointType
ile tanımlanabilir.
Yolculuk durumu ile Araçta kalan ara noktalar arasındaki ilişki
Fleet Engine bir gezi durumu değişikliği isteği aldığında Aracın kalan ara noktaları (RPC | REST) güncellenir. tripStatus
(RPC | REST) farklı bir durumdan ENROUTE_TO_XXX olarak değiştirildiğinde önceki ara nokta, aracın kalan ara noktaları listesinden kaldırılacak. Yani yolculuk durumu ENROUTE_TO_PICKUP iken ARRIVED_AT_PICKUP olarak değiştirildiğinde, seyahatin kalkış noktası aracın kalan
ara nokta listesinde yer almaya devam eder. Ancak yolculuk durumu ENROUTE_TO_INTERMEDIATE_VAR veya ENROUTE_TO_DROPOFF olarak değiştirildiğinde, aracın kalan biniş noktası kaldırılır.
Bu, ARRIVED_AT_INTERMEDIATE_ROAS ve ENROUTE_TO_INTERMDEDIATE_ROAS için aynıdır. Mevcut ara hedef, ARRIVED_AT_INTERMEDIATE_ROAS olduğunda, araç bir sonraki ara noktaya yönlendirdiğini bildirene kadar aracın kalan ara nokta listesinden kaldırılmaz.
Yolculuk durumu COMPLETED
olarak değiştirildiğinde, bu geziye ait hiçbir ara nokta Aracın kalan ara noktası listesinde yer almaz.
NASIL YAPILIR?: Gezi oluşturun
Her seyahat isteğinin takip edilmesi ve filodaki Araçlar ile eşleştirilebilmesi için bir Trip
varlığı oluşturulmalıdır. Seyahat oluşturmak için CreateTrip
uç noktasını CreateTripRequest
ile 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 dize.trip_id
- Araç Paylaşımı Sağlayıcısı tarafından oluşturulan bir dize.trip
: Geziyi açıklayan temel meta verileri içeren kapsayıcı.trip_type
: Seyahatte farklı kalkış ve varış noktalarından gelen diğer yolcuların aynı araçta mı (SHARED
) yoksa tek taraflı mı (EXCLUSIVE
) bulunabileceğini gösteren sıralama.pickup_point
- Gezinin başlangıç noktasını temsil eden TerminalLocation. RPC referansına veya REST referansına bakın
Gezi oluştururken number_of_passengers
, dropoff_point
ve vehicle_id
bilgilerini sağlayabilirsiniz. Bu alanlar zorunlu olmasa da girilirse bu alanlar saklanır. Diğer tüm Seyahat alanları yoksayılır. Örneğin, oluşturma isteğinde CANCELED
üzerinden trip_status
geçseniz bile tüm seyahatler trip_status
ile NEW
başlar.
Örnek
Aşağıdaki örnekte Grand Indonesia East Mall'a bir gezi oluşturulmaktadır. Bu seyahat, iki yolcu kapasitelidir. Trip
öğesinin provider_id
değeri, proje kimliğiyle aynı olmalıdır. Örnekte Yolculuk Paylaşımı Sağlayıcısı, project-id adlı Google Cloud projesini oluşturmuştur. Bu projede, Fleet Engine'i çağırmak için kullanılan Hizmet Hesapları bulunmalıdır. Gezinin durumu: NEW
.
Daha sonra hizmet, seyahati bir araçla eşleştirdikten sonra UpdateTrip
numarasını arayabilir ve seyahat bir araca atandığında vehicle_id
değiştirilebilir.
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ını inceleyin.
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 için 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 dahil edilir.
NASIL YAPILIR?: Gezi güncelleme
Seyahat varlığı, hizmet tarafından izlemeyi ve seyahatin Driver SDK'sı ve Tüketici SDK'sı tarafından kaydedilen ilerlemenin raporlanmasını etkinleştiren alanlar içerir. Özellikleri güncellemek için UpdateTripRequest
mesajını kullanın. Bu işlem, Seyahat alanlarını isteğin field_mask
doğrultusunda günceller.
UpdateTripRequest konusuna bakın.
Araç Paylaşımı Sağlayıcısı, aşağıdaki özelliklerin güncellenmesinden sorumludur:
- Gezi durumu.
- Araç kimliği. Oluşturma sırasında veya aracı bir geziyle eşleştirdikten sonra.
- Teslim alma, bırakma veya ara noktalarla ilgili değişiklikler.
Fleet Engine, Sürücü SDK'sı veya Tüketici SDK'sı aracılığıyla Yolculuk 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'de Resource.Trip
bölümünü inceleyin.
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 bilgiler de dahil edilir.
Nasıl yapılır? Gezi arama
Fleet Engine, gezi aramayı destekler. Daha önce de belirtildiği gibi, bir Gezi yedi gün sonra otomatik olarak silinir. Bu nedenle SearchTrips
, tüm Gezilerin geçmişini eksiksiz olarak göstermez.
SearchTrips
esnek bir API olsa da aşağıdaki listede iki kullanım alanı sunulmuştur.
Bir Aracın Aktif Seyahatlerini Belirleme -- Sağlayıcı, bir aracın o anda aktif olan gezileri belirleyebilir.
SearchTripsRequest
içindevehicle_id
, değerlendirilen araca veactive_trips_only
,true
olarak ayarlanmalıdır.Sağlayıcı ile Fleet Engine Durumunun Uzlaşma -- Sağlayıcı, Seyahat durumunun ve Fleet Engine'in durumunun eşleştiğinden emin olmak için
SearchTrips
kullanabilir. Bu, özellikle TripStatus için önemlidir. Bir araca atanan seyahat durumu,COMPLETE
veyaCANCELED
olarak doğru şekilde ayarlanmazsa araçSearchVehicles
tarafından dahil edilmez.
SearchTrips
öğesini bu şekilde kullanmak için vehicle_id
alanını boş bırakın, active_trips_only
değerini true
olarak ayarlayın ve minimum_staleness
öğesini çoğu seyahat süresinden daha uzun bir süreye ayarlayın.
Örneğin, bir saat değerini kullanabilirsiniz. Sonuçlar arasında TAMAMLANMAMIŞ veya İPTAL EDİLMEMİŞ olan ve bir saatten uzun süredir güncellenmeyen Geziler de yer alır. Sağlayıcı, Fleet Engine'deki durumlarının doğru şekilde güncellendiğinden emin olmak için bu Seyahatleri incelemelidir.
Sorun giderme
DEADLINE_EXCEEDED
Hatası durumunda Fleet Engine'in durumu bilinmiyor. Sağlayıcı CreateTrip
işlemini tekrar yapmalıdır. Bu durumda, 201 (CREATED) veya 409 (CONFLICT) döndürülür. İkinci durumda, önceki istek DEADLINE_EXCEEDED
tarihinden önce başarılı olmuştur. Yolculuk hatalarını işleme hakkında daha fazla bilgi için Consumer API kılavuzlarına göz atın: Android veya iOS.
Ortak araba kullanımı desteği
TripType.SHARED
destekleyen bir araca birden fazla SHARED
seyahati atayabilirsiniz.
Paylaşılan bir gezi için vehicle_id
atadığınızda (CreateTrip
veya UpdateTrip
isteğinde) Trip.vehicle_waypoints
aracılığıyla bu paylaşılan yolculukta Araca atanan tüm Seyahatler için geçilmeyen tüm ara noktaların sırasını belirtmeniz gerekir.
RPC için vehicle_waypoints
veya REST için vehicleWaypoints
belgesini inceleyin.
Birden çok hedef desteği
Ara hedef belirleme
Seyahat'teki (RPC | REST) intermediateDestinations
alanı ve intermediateDestinationIndex
alanı, hedefi belirtmek için kullanılmak üzere birleştirilir.
Ara hedefi güncelleyin
Ara hedefleri UpdateTrip
üzerinden güncelleyebilirsiniz. Ara hedefleri güncellerken yalnızca yeni eklenen veya değiştirilecek olanları değil, ziyaret edilenler de dahil olmak üzere ara hedeflerin tam listesini sağlamanız gerekir.
intermediateDestinationIndex
, yeni eklenen/değiştirilmiş ara hedef konumundan sonra bir endekse işaret ederse yeni/güncellenen ara hedef, aracın waypoints
veya Seyahat remainingWaypoints
öğesine eklenmez.
Bunun nedeni, intermediateDestinationIndex
tarihinden önceki ara hedeflerin ziyaret edilmiş olarak değerlendirilmesidir.
Gezi durumu değişiklikleri
Fleet Engine'e gönderilen Seyahat durumu güncelleme isteğinde, ara hedefin geçtiğini belirtmek için (RPC | REST) içindeki intermediateDestinationsVersion
alanı zorunludur. Hedeflenen ara hedef, intermediateDestinationIndex
alanı aracılığıyla belirtilir.
tripStatus
(RPC | REST) ENROUTE_TO_INTERMEDIATE_VAR olduğunda [0..N-1] arasındaki bir sayı, aracın geçeceği ara hedefi belirtir.
tripStatus
değeri ARRIVED_AT_INTERMEDIATE_ROAS olduğunda [0..N-1] arasındaki bir sayı, aracın hangi ara hedefte olduğunu gösterir.
Örnek
Aşağıdaki kod örneğinde, çok hedefli bir seyahat oluşturduğunuz ve seyahatin teslim alma noktasından geçtiği varsayılarak, bir seyahatin ilk ara hedefine giden rota için durumunun nasıl güncelleneceği gösterilmektedir.
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'sinden bildirim mesajlarına abone olma
Fleet Engine API, tüketici Google Cloud Projesi tarafından oluşturulan konuyla ilgili bildirimleri yayınlamak için Google Cloud Pub/Sub'ı kullanır. Google Cloud projenizde Fleet Engine için Pub/Sub varsayılan olarak 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şturulmalı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üzenleyiciyi 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 protobuf
ve json
olmak üzere iki farklı veri biçiminde yayınlar. Her bildirimin veri biçimi PubsubMessage özelliklerinde anahtar data_format
ve değeri protobuf
veya json
olarak 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"
}
}
}