Fleet Engine'i kullanmaya başlama

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.

gcloud auth login

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.

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

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:

1. Google Cloud Console'u kullanarak bir Google Cloud projesi oluşturun.
2. 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:

Ö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:

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

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ın private_key_id alanında bulabilirsiniz.
• iss ve sub alanları için hizmet hesabınızın e-posta adresini belirtin. Bu değeri, hizmet hesabı JSON dosyanızın client_email alanında bulabilirsiniz.
• aud alanı için https://SERVICE_NAME/ 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ğer iat + 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üncellenmeyen Araçlar otomatik olarak silinir. 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:

1. Driver SDK'sını kullanın - Android, iOS - en basit seçenek.
2. Ö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ç 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

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

static final String PROJECT_ID = "project-id";

VehicleServiceBlockingStub vehicleService =
    VehicleService.newBlockingStub(channel);

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

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

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

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

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.

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

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

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

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

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

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

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

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

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

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.

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

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

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

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

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

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

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

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.

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.

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

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

static final String PROJECT_ID = "project-id";

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

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

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

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

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

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.

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

static final String PROJECT_ID = "project-id";

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

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

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

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

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 de yedi gün sonra herhangi bir güncelleme yapılmadan yolculukları otomatik olarak siliyor. 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.

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

static final String PROJECT_ID = "project-id";

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

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

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

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

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

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

TripRPC'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çinde vehicle_id, değerlendirilen araca ve active_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 veya CANCELED 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.

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

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

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

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

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

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

Fleet Engine API, 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

• Araç
• FieldMask

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

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

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

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

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