Fleet Engine Deliveries API'yi kullanarak teslimatların ilk ve son kilometresi için filo etkinliklerinizi modelleme. Bu API'yi Android ve iOS için Driver SDK'yı kullanarak veya doğrudan HTTP REST ya da gRPC çağrılarını kullanarak kullanabilirsiniz.
İlk kurulum
Fleet Engine Deliveries API'yi Google Cloud Console'da yapılandırırsınız.
Konsolda atılacak adımlar ve yetkilendirme için JSON Web Jetonu oluşturma hakkında bilgi edinmek için Kimlik doğrulama ve yetkilendirme bölümüne bakın.
Konsolu kullanma hakkında ayrıntılı bilgi için Google Cloud Console belgelerine bakın.
Ayarlarınızı doğrulama
Hizmet hesaplarını oluşturduktan sonra kurulumunuzun tamamlandığını doğrulayın ve teslimat aracı oluşturun. Kurulumunuzu hemen doğrulayarak projenizi oluştururken ortaya çıkabilecek yaygın yetkilendirme sorunlarını gidermiş olursunuz. Ayarlarınızı doğrulamanın iki yolu vardır:
Kurulumunuzun iki önemli bölümünü test edin:
gcloud
komut satırı yardımcı programıyla yetkilendirme jetonu imzalama ve deneme teslim aracı oluşturma. Ayrıntılar için Kurulumunuzu doğrulama kılavuzuna göz atın.Fleet Engine Auth Örnek Komut Dosyaları ile kurulumunuzu test edin.
İstemci Kitaplıkları
Ham gRPC veya REST'e kıyasla daha iyi bir geliştirici deneyimi için bazı yaygın programlama dillerindeki istemci kitaplıklarını kullanın. 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ğunuz varsayılır.
Veri yapıları
Fleet Engine Deliveries API, gönderilerin teslim alınmasını ve teslimini modellemek için iki veri yapısı kullanır:
- Gönderiyi taşımak için kullanılan teslimat aracı.
- Gönderinin teslim alma ve teslimat görevleri.
Sürücü aralarını ve gün boyunca planlanmış durakları modellemek için görevleri de kullanırsınız.
Teslimat araçları
Teslimat araçları, gönderileri bir depodan teslimat konumuna ve teslim alma konumundan depoya taşır. Bazı durumlarda bir gönderiyi doğrudan teslim alma konumundan teslimat konumuna da taşıyabilirler.
Sürücü SDK'sını kullanarak Fleet Engine'de bir DeliveryVehicle
nesnesi oluşturun ve gönderim ile filo takibi için konum güncellemeleri gönderin.
Görevler
Bir aracın gün içinde gerçekleştirdiği işlemler için görevleri işlemin türüne göre atarsınız:
- Teslim almalar ve teslimatlar için Gönderim görevleri atayın.
- Sürücülerin müsait olmadığı zamanlar (ör. zorunlu aralar) için Müsaitlik durumu görevleri atayın.
- Açılır kutularda veya müşteri konumlarındaki sürüş harici görevler için Planlı durdurma görevleri atayın.
Atadığınız her görevin benzersiz bir görev kimliği olmalıdır ancak görevler aynı izleme kimliğini paylaşabilir. Fleet Engine her görev için tahmini varış zamanlarını hesaplarken tüm görevleri ve tahminde bulunmak üzere bunların planlandığı sırayı kullanır. Görev kimlikleri hakkında daha fazla bilgi edinmek için Görev kimliği yönergeleri bölümüne bakın.
Fleet Engine'de görev oluşturmak için Driver SDK Görev Yöneticisi'ni kullanın.
Gönderim görevleri
Bir gönderinin hem teslim alınması hem de teslimi için kargo görevleri oluşturun ve aşağıdaki bilgileri ekleyin:
- Teslim alma veya teslimat konumu.
- Takip numarası veya kimliği.
- Görevi tamamlamak, park yeri aramak veya aktarma yerine yürümek için ek süre sağlamak amacıyla bekleme süresi.
- Benzersiz bir görev kimliği. Görev Kimliği yönergeleri bölümüne bakın.
Daha fazla bilgi için aşağıdaki konulara bakın:
Android
iOS
- GMTD DeliveryTaskManager'da oturum açın.
- GMTSTaskType
Kullanılabilir olmayan görevler
Kullanılamama görevleri, aracın teslim alınmak veya teslimat için uygun olmadığı zamanları kapsar. Örneğin, araca yakıt vermek için aralar veya sürücü dinlenme molaları.
Aşağıdaki bilgilerle bir "kullanmama" görevi oluşturun:
- Aranın uzunluğu.
- İsteğe bağlı olarak, aranın konumu. Belirli bir konum belirtmeniz gerekmez, ancak bunu yapmak gün boyunca daha doğru TVS aralıkları sağlar.
Daha fazla bilgi için aşağıdaki konulara bakın:
Android
iOS
- GMTD DeliveryTaskManager'da oturum açın.
- GMTSTaskType
Planlanmış durdurma görevleri
Bir teslimat aracının yapması gereken durakları modellemek için planlanmış durak görevleri oluşturun. Örneğin, aynı konumdaki diğer teslimatlardan veya teslim almalardan bağımsız olarak, belirli bir yerdeki günlük planlanmış bir teslim noktası için planlanmış bir durdurma görevi oluşturun. Ayrıca açılır kutulardan toplama yapmak veya servis merkezleri ve hizmet noktalarındaki durakları ya da besleyici-araç aktarımlarını modellemek için planlanmış durma görevleri oluşturabilirsiniz.
Daha fazla bilgi için aşağıdaki konulara bakın:
Android
iOS
- GMTD DeliveryTaskManager'da oturum açın.
- GMTSTaskType
Görev Kimliği yönergeleri
Görev kimlikleri oluştururken aşağıdaki içerik ve biçim yönergelerine uyun:
- Benzersiz görev kimlikleri oluşturun
- Kimliği tanımlayabilecek bilgileri (PII) veya net metin verilerini göstermeyin.
- Geçerli Unicode dizeleri kullanın.
- En fazla 64 karakter kullanın.
- Şu ASCII karakterlerden hiçbirini eklemeyin: "/", ":", "\", "?" veya "#".
- Unicode Normalleştirme Formu C'ye göre normalleştirin.
Aşağıda, iyi Görev Kimliklerine ilişkin bazı örnekler verilmiştir:
- 566c33d9-2a31-4b6a-9cd4-80ba1a0c643b
- e4708eabcfa39bf2767c9546c9273f747b4626e8cc44e9630d50f6d129013d38
- NTA1YTliYWNkYmViMTI0ZmMzMWFmOWY2NzNkM2Jk
Aşağıdaki tabloda desteklenmeyen görev kimliği örnekleri gösterilmektedir:
Desteklenmeyen Görev Kimlikleri | Neden |
---|---|
8/31/2019-20:48-46.70746,-130.10807,-85.17909,61.33680 | Kimliği tanımlayabilecek bilgiler (PII) ve karakter gereksinimlerini (virgül, nokta, iki nokta, eğik çizgi) ihlal ediyor. |
JohnDoe-577b484da26f-Cupertino-SantaCruz | Kimliği tanımlayabilecek bilgiler (PII) koşullarını ihlal ediyor. |
4R0oXLToF"112 Yaz Dr. East Hartford, CT06118"577b484da26f8a | Kimliği tanımlayabilecek bilgiler (PII) ve karakter gereksinimlerini ihlal ediyor: boşluk, virgül ve tırnak işareti. 64 karakterden uzun olmalıdır. |
Daha fazla kaynak
Her bir veri yapısında yer alan belirli alanları görmek için DeliveryVehicle
(gRPC, REST) ve Task
(gRPC, REST) için API Referans belgelerini inceleyin.
Bir aracın ömrü
DeliveryVehicle
nesnesi, bir ilk veya son mil teslimat aracını temsil eder.
Şunları kullanarak bir DeliveryVehicle
nesnesi oluşturursunuz:
- Fleet Engine API'lerini çağırmak için kullanılan hizmet hesabını içeren Google Cloud projesinin proje kimliği.
- Müşteriye ait araç kimliği.
Her araç için benzersiz olan araç kimlikleri kullanın. Orijinal araç için etkin bir görev yoksa araç kimliğini yeniden kullanmayın.
Fleet Engine, UpdateDeliveryVehicle
kullanılarak güncellenmemiş DeliveryVehicle
nesneyi yedi gün sonra otomatik olarak siler. Bir aracı Fleet Engine'de kullanılabilir durumda tutmak için önerilen yaklaşım, aracın konumunu düzenli aralıklarla güncellemektir. DeliveryVehicle
varlığındaki diğer çoğu alanda yapılan güncellemeler, yeni alan değerinin mevcut değerden farklı olması koşuluyla öğenin ömrünü de uzatır.
Bir aracın mevcut olup olmadığını öğrenmek için:
UpdateDeliveryVehicle
numaralı telefonu arayın.- NOT_FOUND hatası alırsanız aracı yeniden oluşturmak için
CreateDeliveryVehicle
yöntemini çağırın. Aramada araç iade edilirse araç güncellenebilir.
Araç türleri
VehicleType
varlığı, AUTO
, TWO_WHEELER
, BICYCLE
veya PEDESTRIAN
olarak belirtebileceğiniz bir Category
sıralaması içeren isteğe bağlı VehicleType
alanını içerir. Alanı ayarlamazsanız varsayılan olarak AUTO
olur.
Araçlarla ilgili tüm rotalarda, araç türüne karşılık gelen RouteTravelMode
kullanılır.
Araç özellikleri
DeliveryVehicle
varlığı, DeliveryVehicleAttribute
öğesinin yinelenen bir alanını içeriyor. ListDeliveryVehicles
API, döndürülen DeliveryVehicle
varlıklarını belirtilen özelliklere sahip olanlarla sınırlayabilen bir filter
alanı içerir. DeliveryVehicleAttribute
, Fleet Engine yönlendirme davranışını etkilemez.
Özelliklere kimliği tanımlayabilecek bilgiler (PII) veya hassas bilgiler eklemeyin çünkü bu alanlar kullanıcılar tarafından görülebilir.
Bir görevin ömrü
Deliveries API gRPC veya REST arayüzleriyle Fleet Engine'de görev oluşturabilir, güncelleyebilir ve sorgulayabilirsiniz.
Bir Task
nesnesi, yaşam döngüsü boyunca ilerlemesini izlemek için bir durum alanına sahiptir. Değerler OPEN ile KAPALI konumuna taşınır. Yeni görevler AÇIK durumda oluşturulur. Bu durum aşağıdakilerden birini gösterir:
- Görev henüz bir teslimat aracına atanmadı.
- Teslimat aracı, göreve atanan araç durağından henüz geçmedi.
Görev yönergeleri
Bir aracı yalnızca AÇIK durumunda olan bir araca atayabilirsiniz.
Bir görevi araç durakları listesinden kaldırarak iptal edebilirsiniz. Bu işlem, görev durumunu otomatik olarak KAPATILDI şeklinde ayarlar.
Görevin aracı görevin araç durmasını tamamladığında:
Görevin sonuç alanını BAŞARILI veya BAŞARISIZ olarak güncelleyin.
Etkinliğin zaman damgasını belirtin.
Böylece JavaScript Gönderim İzleme kitaplığı görevin sonucunu belirtir ve görev durumu otomatik olarak KAPALI değerine ayarlanır. Daha fazla bilgi için JavaScript Gönderim İzleme kitaplığıyla Gönderiminizi takip etme bölümüne bakın.
Araçlarda olduğu gibi, Fleet Engine yedi gün sonra güncellenmemiş görevleri siler ve zaten mevcut bir kimlikle görev oluşturmaya çalışırsanız hata döndürür.
Not: Fleet Engine, görevlerin açıkça silinmesini desteklemez. Hizmet, yedi gün sonra güncelleme olmadan görevleri otomatik olarak siler. Görev verilerini yedi günden daha uzun süre saklamak istiyorsanız bu özelliği kendiniz uygulamanız gerekir.
Görev özellikleri
Task
varlığı, şu 3 türden bir değere sahip olabilen yinelenen bir TaskAttribute
alanı içeriyor: dize, sayı ve bool. ListTasks
API, döndürülen Task
varlıklarını belirtilen özelliklere sahip öğelerle sınırlayabilen bir filter
alanı içerir. Görev özellikleri, Fleet Engine yönlendirme davranışını etkilemez.
Özelliklere kimliği tanımlayabilecek bilgiler (PII) veya diğer hassas bilgiler eklemeyin çünkü bu özellikler kullanıcılar tarafından görülebilir.
Araç ve görev yaşam döngüsünü yönetin
Hatırlatma: Dahili sisteminiz, Fleet Engine Deliveries API'nin sizin adınıza topladığı verilerin güvenilir kaynağı olarak işlev görür.
Sisteminizdeki araç ve görev yaşam döngülerini yönetmek için Fleet Engine Deliveries API'yi kullanarak araçlarınızı ve bunlarla ilişkili görevleri oluşturabilir, güncelleyebilir ve takip edebilirsiniz.
Sürücü uygulaması aynı zamanda cihaz konumu ve rota bilgilerini güncellemek için doğrudan Fleet Engine ile iletişim kurar. Bu model, Fleet Engine'in gerçek zamanlı konumu verimli bir şekilde yönetmesini sağlar. Konumu doğrudan izleme kitaplığına gönderir. Daha sonra bu kitaplığı, tüketicileri siparişlerinin durumu hakkında bilgilendirmek için kullanabilirsiniz.
Örneğin, aşağıdaki senaryoyu izlediğinizi varsayalım:
- Teslimat durağına yaklaşan bir sürücü. Sürücü uygulaması, konumunu Fleet Engine'e gönderir.
- Fleet Engine, cihaz konumunu izleme kitaplığına gönderir. Tüketici uygulamanız, bu kitaplığı tüketiciyi paketlerine yakın konusunda uyarmak için kullanır.
- Sürücü gönderimi tamamladıktan sonra sürücü uygulamasındaki "Gönderim teslim edildi" düğmesini tıklıyor.
- "Gönderim teslim edildi" işlemi, bilgileri arka uç sisteminize gönderir ve bu sistem de gerekli işletme doğrulama ve doğrulama adımlarını gerçekleştirir.
- Sisteminiz görevi BAŞARILI olarak onaylar ve Deliveries API'yi kullanarak Fleet Engine'i günceller.
Aşağıdaki şemada bu süreçler genel olarak gösterilmektedir. Ayrıca sisteminiz, istemciniz ve Fleet Engine arasındaki standart ilişkiyi de gösterir.
İstemci jetonlarını yönet
Sürücü uygulamasından gelen ve doğrudan Fleet Engine'e gönderilen konum güncellemeleri için yetkilendirme jetonları gerekir. İstemciden Fleet Engine'e yapılan güncellemeleri işlemek için önerilen yaklaşım şu şekildedir:
Fleet Engine Delivery Güvenilmeyen Sürücü Kullanıcısı hizmet hesabı rolünü kullanarak jetonu oluşturun.
Sürücü uygulamasına sınırlı kapsamlı bir jeton sağlayın. Bu kapsam, yalnızca Fleet Engine'de cihaz konumunu güncellemesine izin verir.
Bu yaklaşım, düşük güven ortamı olarak değerlendirilen mobil cihazlardan gelen çağrıların en az ayrıcalık ilkesine uygun olmasını sağlar.
Diğer hizmet hesabı rolleri
Bunun yerine, sürücü uygulamalarını, Güvenilmeyen Sürücü rolüyle sınırlı olanların dışında (örneğin, belirli görev güncellemeleri için) doğrudan Fleet Engine güncellemeleri yapmaya yetkilendirmek isterseniz, Güvenilir Sürücü rolünü kullanabilirsiniz. Güvenilir Sürücü rolünü kullanan bir model hakkında bilgi edinmek için Güvenilir Sürücü modeli sayfasına göz atın.
Güvenilir olmayan ve güvenilir sürücü rollerinin kullanım alanları hakkında daha fazla bilgi için Cloud projesi kurulumu sayfasına bakın.
Bir iş günü modeli oluşturun
Aşağıdaki tabloda bir teslimat ve lojistik şirketinde ilk veya son adım şoförlerinin bir iş gününün nasıl olabileceği açıklanmaktadır. Şirketiniz ayrıntılarda farklılık gösterebilir ancak bir iş gününü nasıl modelleyebileceğinizi görebilirsiniz.
Saat | Etkinlik | Modelleme |
---|---|---|
Gün başlangıcından önceki 24 saat içinde | Sevk görevlisi, sevkiyatları teslimat araçlarına veya rotalarına atar. | Fleet Engine'de kargo teslimatları, teslim almalar, molalar ve diğerleri için önceden görev oluşturabilirsiniz. Örneğin, kargo teslim alma görevi, gönderim teslim görevi, planlanmış stok dışı kalma veya planlı durdurma oluşturabilirsiniz.
Teslimat paketleri grubu ve bunların teslim edilmesi gereken sıra kesinleştikten sonra bir araca görev atayın. |
Gün başlangıcı | Sürücü, Sürücü uygulamasına giriş yaparak güne depoda başlar. | Delivery Driver API'yi başlatın. Gerektiğinde Fleet Engine'de teslimat aracını oluşturun. |
Sürücü, kargoları tararak teslimat aracına yükler. | Gönderim teslimatı görevleri önceden oluşturulmadıysa tarama sırasında gönderim teslimatı görevleri oluşturun. | |
Sürücü, gerçekleştirilecek görevlerin sırasını teyit eder. | Önceden oluşturulmamışsa kargo teslim alma görevleri, planlanmış stok olmaması ve planlanmış duraklar oluşturun. | |
Sürücü depodan ayrılır ve tamamlanması gereken bir sonraki görev sayısına katılır. | Tamamlanma sırasını taahhüt ederek tüm görevleri veya görevlerin bir alt kümesini araca atayın. | |
Sürücü bir gönderi teslim ediyor. | Teslimat durağına vardıktan sonra durağa inen bir araç ile ilgili işlemler yapın. Gönderimi teslim ettikten sonra teslimat görevini kapatın ve isteğe bağlı olarak mağaza gönderim durumu ile diğer meta bilgileri kapatın. Durdurmada tüm görevleri tamamladıktan sonra ve bir sonraki durağa sürüşe başlamadan önce araç molayı tamamlar ve araç rotadaki bir sonraki durağa gider ile ilgili işlemler gerçekleştirin. | |
Sürücü, ek sevkiyatları teslimat aracına aktarmak için bir besleyici aracıyla karşılaşır. | Besleyici ve teslimat araçları arasındaki aktarımın buluşma noktası, planlı durak olarak modellenmelidir.
Gönderimleri aktarıp taradıktan sonra henüz oluşturulmamışsa teslimat görevleri oluşturun. Ardından, görevleri bir araca atayarak ve görev sıralamasını güncelleyerek görev tamamlama sırasını güncelleyin. |
|
Sürücü, teslim alma isteğiyle ilgili bildirim alır. | Teslim alma isteğini kabul ettikten sonra bir kargo teslim alma görevi oluşturun. Ardından, görevleri bir araca atayarak ve görev sıralamasını güncelleyerek görev yürütme sırasını güncelleyin. | |
Öğle | Sürücü öğle molası veriyor. | Bir konum, kullanılamıyor olma göreviyle ilişkiliyse bunu diğer görevler gibi değerlendirin. Bir aracın
durağa varması,
aracın durmasını tamamlaması
ve araçla bir sonraki durağa gitmesi ile ilgili işlemler gerçekleştirin.
Aksi takdirde, aranın sonuna kadar başka bir işlem yapmanız gerekmez. Sonraki ve kalan görevleri onaylayıp görev sıralamasını güncelleyerek görevi kaldırın. |
Sürücü bir gönderiyi alıyor. | Bu, tıpkı bir teslimat noktası gibi modellenir. Bir aracın durağa ulaşması ve bir görevin kapatılması ile ilgili işlemler gerçekleştirin. İsteğe bağlı olarak, gönderim durumunu ve diğer meta bilgileri depolama. Durdurmada tüm görevleri tamamladıktan sonra ve bir sonraki durağa sürüşe başlamadan önce araç molayı tamamlama ve araçla bir sonraki durağa gitme ile ilgili işlemleri gerçekleştirin. Not: Faturalandırmanın doğru olması için tüm teslim almalara karşılık gelen bir teslimat görevi bulunmalıdır. Teslim alma, o gün sürücünün aynı rota üzerindeki başka bir konuma teslim edilecekse bu teslimat görevinin rotadaki diğer tüm teslimat görevleriyle aynı şekilde modellemesini öneririz. Sürücü, teslim almayı depoya geri getiriyorsa depo varış noktasında bir teslimat görevi oluşturmanızı öneririz. | |
Sürücü, kargo şirketlerinden kargoları almak için planlı bir duraklama yapıyor. | Bu araç, tıpkı diğer teslim alma noktaları gibi modellenmiştir. Aracın bir durağa ulaşması ve bir görevin kapatılması ile ilgili işlemler gerçekleştirin. Durdurmada tüm görevleri tamamlayıp bir sonraki durağa doğru yola çıkmaya başladıktan sonra araç molayı tamamladığında ve arabanın rotadaki bir sonraki durağa gitmesiyle ilgili işlemler yapın. | |
Sürücü, bir gönderinin alternatif bir konuma yönlendirildiğine dair bildirim alıyor. | Orijinal kargo teslimatı görevi durumunu TAMAMLANDI olarak ayarlayın ve yeni teslimat konumu için yeni bir kargo teslimatı görevi oluşturun. Daha fazla bilgi için Kargoyu yeniden yönlendirme bölümünü inceleyin. | |
Sürücü, bir paketi teslim etmeyi denedi ancak bunu yapamadı. | Bu, başarılı bir teslim durdurmasına benzer şekilde modellenir ve teslim görevini tamamlandı olarak işaretler. Durmaya ulaşan bir araç ile ilgili işlemler gerçekleştirin. Kargoyu teslim edemediğinizde görevi kapatın ve isteğe bağlı olarak gönderim durumunu ve diğer meta bilgileri depolayın. Durdurmada tüm görevleri tamamladıktan sonra ve bir sonraki durağa sürüşe başlamadan önce araç molayı tamamlama ve araçla bir sonraki durağa gitme ile ilgili işlemleri gerçekleştirin. | |
Sürücüye bir gönderiyi bekletmesi (teslim etmemesi) konusunda bildirim gönderildi. | Bildirim alınıp onaylandıktan sonra görev durumunu TAMAMLANDI olarak ayarlayın. | |
Sürücü, bir sonraki gönderiyi teslim etmesi için bilgilendirildi ve taahhüt edilen teslimat siparişi değiştirildi. | Görev sıralamasını güncelleyin. | |
Sürücü, bir kargoyu yanlışlıkla teslim etmeyi seçiyor. | Görev sıralamasını güncelleyin, ardından normal bir şekilde devam edin. | |
Sürücü, tek bir konuma birden fazla gönderi teslim ediyor. | Bu model, tek gönderi teslimat durağına benzer şekilde modellenir. Durağa geldikten sonra, durağa inen bir araç ile ilgili işlemler yapın. Her gönderiyi teslim ettikten sonra her görevi kapatın ve isteğe bağlı olarak mağaza gönderim durumunu ve diğer meta bilgileri kapatın. Durdurmada tüm görevleri tamamladıktan sonra ve bir sonraki durağa sürüşe başlamadan önce araç molayı tamamlama ve araçla bir sonraki durağa gitme ile ilgili işlemleri gerçekleştirin. | |
Gün sonu | Sürücü depoya döner. | Sürücü, kargoları rotalarında teslim almış olarak depoya dönerse faturalandırmanın doğru olması için her bir paketi bir teslimat görevi olarak oluşturmanız ve kapatmanız gerekir. Bunu, depoyu diğer herhangi bir teslimat noktası gibi modelleyerek yapabilirsiniz. Depo, teslimat noktası olarak kullanılmıyorsa isteğe bağlı olarak depoyu planlanmış bir durak olarak modelleyebilirsiniz. Durağın modellenmesi, sürücülerinizin depoya dönüş rotasını görmelerini ve tahmini varış zamanlarını görmelerini sağlar. |
Konum güncellemelerinin işleyiş şekli
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ç konumu güncellemelerini nasıl sağladığınızdan bağımsız olarak, bir teslimat aracı bir durağa yönlendirildiğinde (depo dahil) ve bir durağa vardığında Fleet Engine'i güncellemekten arka ucunuz sorumludur. Fleet Engine bu etkinlikleri otomatik olarak algılamaz.
Araç durakları ve teslimat konumları
Araç durağı, bir teslimat aracının bir sevkiyat görevini veya başka bir görevi tamamladığı yerdir. Yükleme iskelesi gibi bir erişim noktası veya yola tutturulmuş bir konumdur.
Teslimat konumu, kargonun teslim edildiği veya teslim alındığı konumdur. Teslimat konumuna gidip oradan oraya gitmek için aracın durağından biraz yürümek gerekebilir.
Örneğin, bir sürücü alışveriş merkezindeki bir mağazaya gönderi teslim ederken teslimat aracı, mağazanın en yakın girişinin yakınındaki alışveriş merkezinin otoparkında durur. Burası araç durağı. Ardından sürücü, araç durağından çıkıp alışveriş merkezinin içinde mağazanın bulunduğu konuma doğru gider. Bu, teslimat konumudur.
Kullanıcılarınıza en iyi kargo takibi deneyimi için sevkiyat görevlerinin araç duraklarına nasıl atanacağını düşünün ve gönderimin ilerleme durumunu görüntülemesine yardımcı olmak amacıyla kullanıcıya sevkiyat görevleri için kalan araç duraklarının sayısının raporlandığını unutmayın.
Örneğin, bir sürücü tek bir ofis binasına çok sayıda teslimat yapıyorsa tüm teslimat görevlerini tek bir araç durağına atamayı düşünebilirsiniz. Her teslimat görevi kendi araç durağına atanırsa kargo takibi deneyiminiz kullanıcılarınız için daha az faydalı olur. Bunun nedeni, takip özelliğinin yalnızca aracın varış noktasına ulaşmadan önce sınırlı sayıda araç durduğunda kullanılabilmesidir. Çok sayıda aracın kısa süre içinde tamamlanması, teslimatın ilerlemesini takip etmek için kullanıcıya fazla zaman tanımaz.
Mobil SDK'ları kullanma
Sürücü SDK'sına çağrı yapmadan önce SDK'yı başlattığınızdan emin olun.
Delivery Driver API'yi başlatma
Sürücü SDK'sında Delivery Driver API'yi başlatmadan önce Navigasyon SDK'sını ilk kullanıma hazırladığınızdan emin olun. Ardından, aşağıdaki örnekte gösterildiği gibi Delivery Driver API'yi başlatın:
static final String PROVIDER_ID = "provider-1234";
static final String VEHICLE_ID = "vehicle-8241890";
NavigationApi.getNavigator(
this, // Activity.
new NavigatorListener() {
@Override
public void onNavigatorReady(Navigator navigator) {
DeliveryDriverApi.createInstance(DriverContext.builder(getApplication())
.setNavigator(navigator)
.setProviderId(PROVIDER_ID)
.setVehicleId(VEHICLE_ID)
.setAuthTokenFactory((context) -> "JWT") // AuthTokenFactory returns JWT for call context.
.setRoadSnappedLocationProvider(NavigationApi.getRoadSnappedLocationProvider(getApplication()))
.setNavigationTransactionRecorder(NavigationApi.getNavigationTransactionRecorder(getApplication()))
.setStatusListener((statusLevel,statusCode,statusMsg) -> // Optional, surfaces polling errors.
Log.d("TAG", String.format("New status update. %s, %s, %s", statusLevel, statusCode, statusMsg)))
.build));
}
@Override
public void onError(int errorCode) {
Log.e("TAG", String.format("Error loading Navigator instance: %s", errorCode));
}
});
Kullanım alanları
Bu bölümde, yaygın kullanım alanlarını modellemek için Deliveries API'nin nasıl kullanılacağı açıklanmaktadır.
Benzersiz varlık tanımlayıcıları
REST çağrılarında kullanılan benzersiz varlık tanımlayıcılarının biçimi ve değeri Fleet Engine için opaktır. Otomatik artan kimlikler kullanmaktan kaçının ve tanımlayıcının, sürücünün telefon numarası gibi kimliği tanımlayabilecek bilgiler (PII) içermediğinden emin olun.
Araç oluştur
Sürücü SDK'sından veya gRPC ya da REST kullanarak bir sunucu ortamından araç oluşturabilirsiniz.
gRPC
Yeni araç oluşturmak için Fleet Engine'e CreateDeliveryVehicle
araması yaparsınız.
Yeni teslimat aracının özelliklerini tanımlamak için CreateDeliveryVehicleRequest
nesnesini kullanın. Name
alanı için belirtilen tüm değerin, kullanıcı tarafından belirtilen kimlikler ile ilgili API rehberine göre yoksayılacağını unutmayın.
Aracın kimliğini ayarlamak için DeliveryVehicleId
alanını kullanmanız gerekir.
DeliveryVehicle
oluştururken isteğe bağlı olarak şu alanları belirtebilirsiniz:
- Özellikler
- LastLocation
- Tür
Başka alan ayarlamayın. Bunu yaparsanız Fleet Engine, bu alanlar salt okunur olduğu veya yalnızca UpdateDeliveryVehicle
çağrısıyla güncellenebileceği için bir hata döndürür.
İsteğe bağlı alanlar ayarlamadan araç oluşturmak için CreateDeliveryVehicleRequest
içindeki DeliveryVehicle
alanını ayarlamadan bırakabilirsiniz.
Aşağıdaki örnekte, araç oluşturmak için Java gRPC kitaplığının nasıl kullanılacağı gösterilmektedir:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890"; // Avoid auto-incrementing IDs.
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String parent = "providers/" + PROJECT_ID;
DeliveryVehicle vehicle = DeliveryVehicle.newBuilder()
.addAttributes(DeliveryVehicleAttribute.newBuilder()
.setKey("route_number").setValue("1")) // Opaque to the Fleet Engine
.build();
// Vehicle request
CreateDeliveryVehicleRequest createVehicleRequest =
CreateDeliveryVehicleRequest.newBuilder() // No need for the header
.setParent(parent)
.setDeliveryVehicleId(VEHICLE_ID) // Vehicle ID assigned by the Provider
.setDeliveryVehicle(vehicle)
.build();
// Error handling
// If Fleet Engine does not have vehicle with that ID and the credentials of the
// requestor pass, the service creates the vehicle successfully.
try {
DeliveryVehicle createdVehicle =
deliveryService.createDeliveryVehicle(createVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Sunucu ortamından araç oluşturmak için CreateDeliveryVehicle
öğesine HTTP REST çağrısı yapın:
POST https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles?deliveryVehicleId=<id>
<id>, filonuzdaki bir teslimat aracına ait benzersiz tanımlayıcıdır.
İstek başlığında, Bearer <token> değerine sahip bir Yetkilendirme alanı bulunmalıdır. Burada <token>, Fleet Engine jeton fabrikası tarafından verilen bir jetondur.
POST gövdesi, oluşturulacak DeliveryVehicle
varlığını temsil eder. Aşağıdaki isteğe bağlı alanları belirtebilirsiniz:
- attributes
- lastLocation
- tür
Örnek curl
komutu:
# Set $JWT, $PROJECT_ID, and $VEHICLE_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?deliveryVehicleId=${VEHICLE_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"attributes": [{"key": "model", "value": "sedan"}],
"lastLocation": {"location": {"latitude": 12.1, "longitude": 14.5}}
}
EOM
Fleet Engine, kullanıcı tarafından belirtilen kimlikler için API kılavuzu başına DeliveryVehicle
öğesinin name
alanını yoksayar.
Başka alan ayarlamayın. Bunu yaparsanız Fleet Engine, bu alanlar salt okunur olduğu veya yalnızca UpdateDeliveryVehicle
öğesine yapılan bir çağrıyla güncellenebileceği için bir hata döndürür.
Herhangi bir alan ayarlamadan araç oluşturmak için POST isteğinin gövdesini boş bırakın. Yeni oluşturulan araç daha sonra POST URL'sindeki deliveryVehicleId
parametresinden bir araç kimliği ayıklar.
Örnek curl
komutu:
# Set $JWT, $PROJECT_ID, and $VEHICLE_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?deliveryVehicleId=${VEHICLE_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}"
Kargo teslim alma görevi oluşturma
Sürücü SDK'sından veya gRPC ya da REST kullanarak bir sunucu ortamından kargo teslim alma görevi oluşturabilirsiniz.
gRPC
Aşağıdaki örnekte bir kargo teslim alma görevi oluşturmak için Java gRPC kitaplığının nasıl kullanılacağı gösterilmektedir:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
.setType(Task.Type.PICKUP)
.setState(Task.State.OPEN)
.setTrackingId("my-tracking-id")
.setPlannedLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setTaskDuration(
Duration.newBuilder().setSeconds(2 * 60))
.setTargetTimeWindow(
TimeWindow.newBuilder()
.setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
.setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
.addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
.addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
.addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
.build();
// Task request
CreateTaskRequest createTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header
.setParent(parent) // Avoid using auto-incrementing IDs for the taskId
.setTaskId("task-8241890") // Task ID assigned by the Provider
.setTask(task) // Initial state
.build();
// Error handling
// If Fleet Engine does not have a task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.
try {
Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Bir sunucu ortamından kargo teslim alma görevi oluşturmak için CreateTask
öğesine HTTP REST çağrısı yapın:
`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`
<id>, görev için benzersiz bir tanımlayıcıdır. Bu, kargonun takip numarası olmamalıdır. Sisteminizde görev kimlikleri yoksa evrensel olarak benzersiz bir tanımlayıcı (UUID) oluşturabilirsiniz.
İstek başlığında, Bearer <token> değerine sahip bir Yetkilendirme alanı bulunmalıdır. Burada <token>, Fleet Engine jeton fabrikası tarafından verilen bir jetondur.
İstek gövdesinde bir Task
varlığı bulunmalıdır:
Zorunlu alanlar:
Alan Değer tür Type.PICKUP state State.OPEN trackingId Bir gönderiyi takip etmek için kullandığınız numara veya tanımlayıcı. plannedLocation Görevin tamamlanacağı konum (bu örnekte, kargonun teslim alınacağı konum). taskDuration Gönderiyi teslim alma noktasından teslim almak için gereken saniye cinsinden beklenen süre. İsteğe bağlı alanlar:
Alan Değer targetTimeWindow Görevin tamamlanması gereken zaman aralığı. Bu durum, yönlendirme davranışını etkilemez. attributes Özel Görev özelliklerinin listesi. Her özelliğin benzersiz bir anahtarı olmalıdır.
Öğedeki diğer tüm alanlar oluşturma işlemi için yoksayılır. İstekte atanmış bir deliveryVehicleId
varsa Fleet Engine bir istisna uygular. Görevleri UpdateDeliveryVehicleRequest
kullanarak atarsınız. Daha fazla bilgi için Bir araca görev atama ve UpdateDeliveryVehicleRequest konularına bakın.
Örnek curl
komutu:
# Set $JWT, $PROJECT_ID, $TRACKING_ID, and $TASK_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"type": "PICKUP",
"state": "OPEN",
"trackingId": "${TRACKING_ID}",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "90s",
"targetTimeWindow": {
"startTime": "2023-03-29T21:00:00Z",
"endTime": "2023-03-29T23:00:00Z"
}
}
EOM
Gönderim teslimat görevi oluşturma
Sürücü SDK'sından veya gRPC ya da REST kullanarak bir sunucu ortamından gönderi teslim görevi oluşturun.
gRPC
Aşağıdaki örnekte bir kargo teslimat görevi oluşturmak için Java gRPC kitaplığının nasıl kullanılacağı gösterilmektedir:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
.setType(Task.Type.DELIVERY)
.setState(Task.State.OPEN)
.setTrackingId("my-tracking-id")
.setPlannedLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setTaskDuration(
Duration.newBuilder().setSeconds(2 * 60))
.setTargetTimeWindow(
TimeWindow.newBuilder()
.setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
.setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
.addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
.addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
.addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
.build();
// Task request
CreateTaskRequest createTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header
.setParent(parent) // Avoid using auto-incrementing IDs for the taskId
.setTaskId("task-8241890") // Task ID assigned by the Provider
.setTask(task) // Initial state
.build();
// Error handling
// If Fleet Engine does not have task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.
try {
Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
gRPC veya REST kullanarak bir sunucu ortamından gönderi teslim görevi oluşturmak için CreateTask
öğesine HTTP REST çağrısı yapın:
`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`
<id>, görev için benzersiz bir tanımlayıcıdır. Bu, kargonun takip numarası olmamalıdır. Sisteminizde görev kimlikleri yoksa evrensel olarak benzersiz bir tanımlayıcı (UUID) oluşturabilirsiniz.
İstek başlığında, Bearer <token> değerine sahip bir Yetkilendirme alanı bulunmalıdır. Burada <token>, Fleet Engine jeton fabrikası tarafından verilen bir jetondur.
İstek gövdesinde bir Task
varlığı bulunmalıdır:
Zorunlu alanlar:
Alan Değer tür Type.DELIVERY state State.OPEN trackingId Bir gönderiyi takip etmek için kullandığınız numara veya tanımlayıcı. plannedLocation Görevin tamamlanacağı konum (bu örnekte, bu gönderinin teslimat konumu). taskDuration Gönderinin teslimat konumuna teslim edilmesi için geçen saniye cinsinden beklenen süre. İsteğe bağlı alanlar:
Alan Değer targetTimeWindow Görevin tamamlanması gereken zaman aralığı. Bu durum, yönlendirme davranışını etkilemez. attributes Özel Görev özelliklerinin listesi. Her özelliğin benzersiz bir anahtarı olmalıdır.
Öğedeki diğer tüm alanlar oluşturma işlemi için yoksayılır. İstekte atanmış bir deliveryVehicleId varsa Fleet Engine bir istisna uygular. Görevleri UpdateDeliveryVehicleRequest
kullanarak atarsınız. Daha fazla bilgi için Bir araca görev atama ve UpdateDeliveryVehicleRequest konularına bakın.
Örnek curl
komutu:
# Set $JWT, $PROJECT_ID, $TRACKING_ID, and $TASK_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"type": "DELIVERY",
"state": "OPEN",
"trackingId": "${TRACKING_ID}",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "90s",
"targetTimeWindow": {
"startTime": "2023-03-29T21:00:00Z",
"endTime": "2023-03-29T23:00:00Z"
}
}
EOM
Toplu Görevler Oluşturma
gRPC veya REST kullanarak bir sunucu ortamından toplu görev oluşturabilirsiniz.
gRPC
Aşağıdaki örnekte biri teslimat, diğeri aynı konumda teslim alma için olmak üzere iki görev oluşturmak için Java gRPC kitaplığının nasıl kullanılacağı gösterilmektedir:
static final String PROJECT_ID = "my-delivery-co-gcp-project"; DeliveryServiceBlockingStub deliveryService = DeliveryServiceGrpc.newBlockingStub(channel); // Delivery Task settings Task deliveryTask = Task.newBuilder() .setType(Task.Type.DELIVERY) .setState(Task.State.OPEN) .setTrackingId("delivery-tracking-id") .setPlannedLocation( // Grand Indonesia East Mall LocationInfo.newBuilder().setPoint( LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826))) .setTaskDuration( Duration.newBuilder().setSeconds(2 * 60)) .build(); // Delivery Task request CreateTaskRequest createDeliveryTaskRequest = CreateTaskRequest.newBuilder() // No need for the header or parent fields .setTaskId("task-8312508") // Task ID assigned by the Provider .setTask(deliveryTask) // Initial state .build(); // Pickup Task settings Task pickupTask = Task.newBuilder() .setType(Task.Type.PICKUP) .setState(Task.State.OPEN) .setTrackingId("pickup-tracking-id") .setPlannedLocation( // Grand Indonesia East Mall LocationInfo.newBuilder().setPoint( LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826))) .setTaskDuration( Duration.newBuilder().setSeconds(2 * 60)) .build(); // Pickup Task request CreateTaskRequest createPickupTaskRequest = CreateTaskRequest.newBuilder() // No need for the header or parent fields .setTaskId("task-8241890") // Task ID assigned by the Provider .setTask(pickupTask) // Initial state .build(); // Batch Create Tasks settings String parent = "providers/" + PROJECT_ID; // Batch Create Tasks request BatchCreateTasksRequest batchCreateTasksRequest = BatchCreateTasksRequest.newBuilder() .setParent(parent) .addRequests(createDeliveryTaskRequest) .addRequests(createPickupTaskRequest) .build(); // Error handling // If Fleet Engine does not have any task(s) with these task ID(s) and the // credentials of the requestor pass, the service creates the task(s) // successfully. try { BatchCreateTasksResponse createdTasks = deliveryService.batchCreateTasks( batchCreateTasksRequest); } catch (StatusRuntimeException e) { Status s = e.getStatus(); switch (s.getCode()) { case ALREADY_EXISTS: break; case PERMISSION_DENIED: break; } return; }
REST
Sunucu ortamından teslim ve alma görevi oluşturmak için BatchCreateTasks
öğesine HTTP REST çağrısı yapın:
POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks:batchCreate
İstek başlığında, Bearer <token> değerine sahip bir Authorization alanı bulunmalıdır. Burada <token>, Fleet Engine jeton fabrikası tarafından verilen bir jetondur.
İstek gövdesinde bir BatchCreateTasksRequest
varlığı bulunmalıdır:
Zorunlu alanlar:
Alan Değer istek Dizi< CreateTasksRequest
>İsteğe bağlı alanlar:
Alan Değer başlık "DeliveryRequestHeader"
parent
ve header
alanlarının isteğe bağlı olması dışında, requests
içindeki her CreateTasksRequest
öğesi bir CreateTask
isteğiyle aynı doğrulama kurallarını geçmelidir. Ayarlanırsa üst düzey BatchCreateTasksRequest
olan ilgili alanlarıyla aynı olmalıdır. Her bir kargoya özel doğrulama kuralları için kargo teslim alma görevi oluşturma ve kargo teslimat görevi oluşturma bölümünü inceleyin.
Daha fazla bilgi için BatchCreateTasks
API Referansı belgelerini (gRPC, REST) inceleyin.
Örnek curl
komutu:
# Set $JWT, $PROJECT_ID, $DELIVERY_TRACKING_ID, $DELIVERY_TASK_ID,
# $PICKUP_TRACKING_ID, and $PICKUP_TASK_ID in the local environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks:batchCreate" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"requests" : [
{
"taskId": "${DELIVERY_TASK_ID}",
"task" : {
"type": "DELIVERY",
"state": "OPEN",
"trackingId": "${DELIVERY_TRACKING_ID}",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "90s"
}
},
{
"taskId": "${PICKUP_TASK_ID}",
"task" : {
"type": "PICKUP",
"state": "OPEN",
"trackingId": "${PICKUP_TRACKING_ID}",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "90s"
}
}
]
}
EOM
Planlanan kullanım dışı kalma
Sürücü SDK'sından veya gRPC ya da REST kullanan bir sunucu ortamından, kullanılamadığını gösteren (örneğin, sürücü arızaları veya araç doldurma için) bir görev oluşturabilirsiniz. Planlanmış bir kullanılabilir olmama görevi, izleme kimliği içermemelidir. İsterseniz bir konum da belirtebilirsiniz.
gRPC
Aşağıdaki örnekte, kullanılamıyor olma görevi oluşturmak için Java gRPC kitaplığının nasıl kullanılacağı gösterilmektedir:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
.setType(Task.Type.UNAVAILABLE)
.setState(Task.State.OPEN)
.setTaskDuration(
Duration.newBuilder().setSeconds(60 * 60)) // 1hr break
.build();
// Task request
CreateTaskRequest createTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header
.setParent(parent) // Avoid using auto-incrementing IDs for the taskId
.setTaskId("task-8241890") // Task ID assigned by the Provider
.setTask(task) // Initial state
.build();
// Error handling
// If Fleet Engine does not have task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.
try {
Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Bir sunucu ortamından kullanılamama görevi oluşturmak için CreateTask
öğesine HTTP REST çağrısı yapın:
`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`
<id>, görev için benzersiz bir tanımlayıcıdır. Sisteminizde görev kimlikleri yoksa evrensel olarak benzersiz bir tanımlayıcı (UUID) oluşturabilirsiniz.
İstek başlığında, Bearer <token> değerine sahip bir Yetkilendirme alanı bulunmalıdır. Burada <token>, Fleet Engine jeton fabrikası tarafından verilen bir jetondur.
İstek gövdesinde bir Task
varlığı bulunmalıdır:
Zorunlu alanlar:
Alan Değer tür Type.UNAVAILABLE state State.OPEN taskDuration Aranın saniye cinsinden uzunluğu. İsteğe bağlı alanlar:
Alan Değer plannedLocation Belirli bir konumda çekilmesi gerekiyorsa aranın konumu.
Öğedeki diğer tüm alanlar oluşturma işlemi için yoksayılır. İstekte atanmış bir deliveryVehicleId varsa Fleet Engine bir istisna uygular. Görevleri UpdateDeliveryVehicleRequest
kullanarak atarsınız. Daha fazla bilgi için Bir araca görev atama ve UpdateDeliveryVehicleRequest konularına bakın.
Örnek curl
komutu:
# Set $JWT, $PROJECT_ID, and $TASK_ID in the local environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"type": "UNAVAILABLE",
"state": "OPEN",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "300s"
}
EOM
Planlanan aktarmalar
Sürücü SDK'sından veya gRPC ya da REST kullanan bir sunucu ortamından planlanmış bir durdurma görevi oluşturabilirsiniz. Planlanan bir durdurma görevi, izleme kimliği içeremez.
gRPC
Aşağıdaki örnekte, planlanmış bir durdurma görevi oluşturmak için Java gRPC kitaplığının nasıl kullanılacağı gösterilmektedir:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
.setType(Task.Type.SCHEDULED_STOP)
.setState(Task.State.OPEN)
.setPlannedLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setTaskDuration(
Duration.newBuilder().setSeconds(2 * 60))
.build();
// Task request
CreateTaskRequest createTaskRequest =
CreateTaskRequest.newBuilder() // No need for the header
.setParent(parent)
.setTaskId("task-8241890") // Task ID assigned by the Provider
.setTrip(task) // Initial state
.build();
// Error handling
// If Fleet Engine does not have task with that ID and the credentials of the
// requestor pass, the service creates the task successfully.
try {
Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Sunucu ortamından planlanmış bir durdurma görevi oluşturmak için CreateTask
öğesine HTTP REST çağrısı yapın:
`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`
<id>, görev için benzersiz bir tanımlayıcıdır. Sisteminizde görev kimlikleri yoksa evrensel olarak benzersiz bir tanımlayıcı (UUID) oluşturabilirsiniz.
İstek başlığında, Bearer <token> değerine sahip bir Yetkilendirme alanı bulunmalıdır. Burada <token>, Fleet Engine jeton fabrikası tarafından verilen bir jetondur.
İstek gövdesinde bir Task
varlığı bulunmalıdır:
Zorunlu alanlar:
Alan Değer tür Type.SCHEDULED_STOP state State.OPEN plannedLocation Durağın konumu. taskDuration Durmanın saniye cinsinden öngörülen uzunluğu. İsteğe bağlı alanlar:
- Yok
Öğedeki diğer tüm alanlar oluşturma işlemi için yoksayılır. İstekte atanmış bir deliveryVehicleId varsa Fleet Engine bir istisna uygular. Görevleri UpdateDeliveryVehicleRequest
kullanarak atarsınız. Daha fazla bilgi için Bir araca görev atama ve UpdateDeliveryVehicleRequest konularına bakın.
Örnek curl
komutu:
# Set $JWT, $PROJECT_ID, and $TASK_ID in the local environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"type": "SCHEDULED_STOP",
"state": "OPEN",
"plannedLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
},
"taskDuration": "600s"
}
EOM
Hedef zaman aralığı belirleyin
Hedef zaman aralığı, görevin tamamlanması gereken TimeWindow'dır. Örneğin, teslim alıcılarına bir teslimat süresi aralığı bildirirseniz bu zaman aralığını yakalamak ve alanı kullanarak uyarılar oluşturmak ya da seyahat sonrası performansı analiz etmek için görev hedef zaman aralığını kullanabilirsiniz.
Hedef zaman aralığı, başlangıç ve bitiş zamanından oluşur ve herhangi bir görev türüne ayarlanabilir. Hedef zaman aralığı, yönlendirme davranışını etkilemez.
gRPC
Aşağıdaki örnekte, görev zaman aralığı ayarlamak için Java gRPC kitaplığının nasıl kullanılacağı gösterilmektedir:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
.setName(taskName)
.setTargetTimeWindow(
TimeWindow.newBuilder()
.setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
.setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
.build();
// Task request
UpdateTaskRequest updateTaskRequest =
UpdateTaskRequest.newBuilder() // No need for the header
.setTask(task)
.setUpdateMask(FieldMask.newBuilder().addPaths("targetTimeWindow"))
.build();
try {
Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
HTTP kullanarak görev zaman aralığı ayarlamak için UpdateTask
komutunu çağırın:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=targetTimeWindow`
<id>, görev için benzersiz bir tanımlayıcıdır.
İstek başlığında, Bearer <token> değerine sahip bir Yetkilendirme alanı bulunmalıdır. Burada <token>, Fleet Engine jeton fabrikası tarafından verilen bir jetondur.
İstek gövdesinde bir Task
varlığı bulunmalıdır:
Zorunlu alanlar:
Alan Değer targetTimeWindow Görevin tamamlanması gereken zaman aralığı. Bu ayar, yönlendirme davranışını etkilemez İsteğe bağlı alanlar:
- Yok
Öğedeki diğer tüm alanlar güncelleme için yoksayılır.
Örnek curl
komutu:
# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=targetTimeWindow" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"targetTimeWindow": {
"startTime": "2023-03-29T21:00:00Z",
"endTime": "2023-03-29T23:00:00Z"
}
}
EOM
Görev izleme görünürlük yapılandırmasını ayarla
Gönderim İzleme kitaplığındaki verilerin ve GetTaskTrackingInfo
çağrısından döndürülen bu verilerin görünürlüğü, göreve bir TaskTrackingViewConfig
ayarlanarak görev bazında kontrol edilebilir. Daha fazla bilgi için Etkin araç görevleri bölümüne bakın. Bu, görev oluştururken ya da güncellerken
yapılabilir. Aşağıda, bu yapılandırmayla görevin güncellenmesine ilişkin bir örnek verilmiştir:
gRPC
Aşağıdaki örnekte, görev izleme görünümü yapılandırmasını ayarlamak için Java gRPC kitaplığının nasıl kullanılacağı gösterilmektedir:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
.setName(taskName)
.setTaskTrackingViewConfig(
TaskTrackingViewConfig.newBuilder()
.setRoutePolylinePointsVisibility(
VisibilityOption.newBuilder().setRemainingStopCountThreshold(3))
.setEstimatedArrivalTimeVisibility(
VisibilityOption.newBuilder().remainingDrivingDistanceMetersThreshold(5000))
.setRemainingStopCountVisibility(
VisibilityOption.newBuilder().setNever(true)))
.build();
// Task request
UpdateTaskRequest updateTaskRequest =
UpdateTaskRequest.newBuilder() // No need for the header
.setTask(task)
.setUpdateMask(FieldMask.newBuilder().addPaths("taskTrackingViewConfig"))
.build();
try {
Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Görev izleme görünümü yapılandırma penceresini HTTP kullanarak ayarlamak için UpdateTask
komutunu çağırın:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=taskTrackingViewConfig`
<id>, görev için benzersiz bir tanımlayıcıdır.
İstek başlığında, Bearer <token> değerine sahip bir Yetkilendirme alanı bulunmalıdır. Burada <token>, Fleet Engine jeton fabrikası tarafından verilen bir jetondur.
İstek gövdesinde bir Task
varlığı bulunmalıdır:
Zorunlu alanlar:
Alan Değer taskTrackingViewConfig Hangi veri öğelerinin hangi durumlarda son kullanıcılar tarafından görülebileceğini belirten görev izleme yapılandırması. İsteğe bağlı alanlar:
- Yok
Öğedeki diğer tüm alanlar güncelleme için yoksayılır.
Örnek curl
komutu:
# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=taskTrackingViewConfig" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"taskTrackingViewConfig": {
"routePolylinePointsVisibility": {
"remainingStopCountThreshold": 3
},
"estimatedArrivalTimeVisibility": {
"remainingDrivingDistanceMetersThreshold": 5000
},
"remainingStopCountVisibility": {
"never": true
}
}
}
EOM
Bir araca görev atama
Araç için görev sırasını güncelleyerek bir teslimat aracına görev atarsınız. Bir aracın görev sıralaması, teslimat aracı için araç duraklarının listesine göre belirlenir ve her araç durağına bir veya daha fazla görev atayabilirsiniz. Ayrıntılar için Görev sıralamasını güncelleme bölümüne bakın.
Bir araçtan diğerine gönderi değiştirmek için orijinal görevi kapatın ve yeni araca atamadan önce yeniden oluşturun. Halihazırda farklı bir araca atanmış bir görev için görev sıralamasını güncellerseniz bir hata alırsınız.
Görev sıralamasını güncelleyin
Bir araca atanan sipariş görevlerini Sürücü SDK'sından veya sunucu ortamından güncelleyebilirsiniz. Yarış koşullarının önüne geçmek ve doğru bilgiye sahip olmak için her iki yöntemi de kullanmayın.
Bir araç için görev sıralamasını güncellediğinizde, araç şunları da yapar:
- Araca yeni görevler atar.
- Araca daha önce atanmış ancak güncellenmiş sıralamada yer almayan tüm görevleri kapatır.
Bir araçtan diğerine gönderi değiştirmek için orijinal görevi kapatın ve yeni araca atamadan önce yeniden oluşturun. Halihazırda farklı bir araca atanmış bir görev için görev sıralamasını güncellerseniz bir hata alırsınız.
Görev sıralamasını istediğiniz zaman güncelleyebilirsiniz.
gRPC
Aşağıdaki örnekte, aracın görev sıralamasını güncellemek için Java gRPC kitaplığının nasıl kullanılacağı gösterilmektedir:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
static final String TASK1_ID = "task-756390";
static final String TASK2_ID = "task-849263";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 1st stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.7749)
.setLongitude(122.4194)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
.setState(VehicleStop.State.NEW)))
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 2nd stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
.setState(VehicleStop.State.NEW)))
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryRequest =
UpdateDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(vehicleName)
.setDeliveryVehicle(deliveryVehicle)
.setUpdateMask(FieldMask.newBuilder().addPaths("remaining_vehicle_journey_segments"))
.build();
try {
DeliveryVehicle updatedDeliveryVehicle =
deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Sunucu ortamından bir aracın görev sıralamasını güncellemek için UpdateDeliveryVehicle
öğesine HTTP REST çağrısı yapın:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`
<id>, filonuzda görev sıralamasını güncellemeyi düşündüğünüz bir teslimat aracına ait benzersiz bir tanımlayıcıdır. Bu, aracı oluştururken belirttiğiniz tanımlayıcıdır.
İstek başlığında, Bearer <token> değerine sahip bir Yetkilendirme alanı bulunmalıdır. Burada <token>, Fleet Engine jeton fabrikası tarafından verilen bir jetondur.
İstek gövdesinde bir DeliveryVehicle
varlığı bulunmalıdır:
Zorunlu alanlar:
Alan Değer remainingVehicleJourneySegments Görevlerin yürütülmesi gereken sırayla bir yolculuk segmentleri listesi. Listedeki ilk görev ilk olarak yürütülür. kalanVehicleJourneySegments[i].stop Listede i görevinin durağı. geri kalanVehicleJourneySegments[i].stop.plannedLocation Durak için planlanan konum. VehicleJourneySegments[i].stop.tasks Bu araç durağında yapılacak görevlerin listesi. remainingVehicleJourneySegments[i].stop.state State.NEW İsteğe bağlı alanlar:
- Yok
Öğedeki diğer tüm alanlar güncelleme için yoksayılır.
Örnek curl
komutu:
# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"remainingVehicleJourneySegments": [
{
"stop": {
"state": "NEW",
"plannedLocation": {
"point": {
"latitude": 37.7749,
"longitude": -122.084061
}
},
"tasks": [
{
"taskId": "${TASK1_ID}"
}
]
}
},
{
"stop": {
"state": "NEW",
"plannedLocation": {
"point": {
"latitude": 37.3382,
"longitude": 121.8863
}
},
"tasks": [
{
"taskId": "${TASK2_ID}"
}
]
}
}
]
}
EOM
Araç sonraki durakta
Bir araç duraktan ayrıldığında veya navigasyona başladığında Fleet Engine'e bilgi verilmelidir. Fleet Engine'e Sürücü SDK'sından veya gRPC ya da REST kullanarak bir sunucu ortamından bildirim gönderebilirsiniz. Irk koşullarından kaçınmak ve tek doğruluk kaynağı olmak için her iki yöntemi birden kullanmayın.
gRPC
Aşağıdaki örnekte, Fleet Engine'e bir aracın sonraki durağına doğru ilerlediğini bildirmek için Java gRPC kitaplığının nasıl kullanılacağı gösterilmektedir.
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
// Next stop marked as ENROUTE
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 1st stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.7749)
.setLongitude(122.4194)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
.setState(VehicleStop.State.ENROUTE)))
// All other stops marked as NEW
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 2nd stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
.setState(VehicleStop.State.NEW)))
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
UpdateDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(vehicleName)
.setDeliveryVehicle(deliveryVehicle)
.setUpdateMask(FieldMask.newBuilder().addPaths("remaining_vehicle_journey_segments"))
.build();
try {
DeliveryVehicle updatedDeliveryVehicle =
deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Fleet Engine'e bir aracın sunucu ortamından sonraki durağına doğru yolda olduğunu bildirmek için UpdateDeliveryVehicle
öğesine HTTP REST çağrısı yapın:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`
<id>, filonuzda görev sıralamasını güncellemeyi düşündüğünüz teslimat aracına ait benzersiz bir tanımlayıcıdır. Bu, aracı oluştururken belirttiğiniz tanımlayıcıdır.
İstek başlığında, Bearer <token> değerine sahip bir Yetkilendirme alanı bulunmalıdır. Burada <token>, Fleet Engine jeton fabrikası tarafından verilen bir jetondur.
İstek gövdesinde bir DeliveryVehicle
varlığı bulunmalıdır:
Zorunlu alan:
Alan Değer remainingVehicleJourneySegments Durumları eyalet olarak işaretlenmiş kalan araç duraklarının listesi.YENİ. Listedeki ilk durağın durumu State.ENROUTE olarak işaretlenmiş olmalıdır. İsteğe bağlı alanlar:
- Yok
Öğedeki diğer tüm alanlar bildirim için yoksayılır.
Örnek curl
komutu:
# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"remainingVehicleJourneySegments": [
{
"stop": {
"state": "ENROUTE",
"plannedLocation": {
"point": {
"latitude": 37.7749,
"longitude": -122.084061
}
},
"tasks": [
{
"taskId": "${TASK1_ID}"
}
]
}
},
{
"stop": {
"state": "NEW",
"plannedLocation": {
"point": {
"latitude": 37.3382,
"longitude": 121.8863
}
},
"tasks": [
{
"taskId": "${TASK2_ID}"
}
]
}
}
]
}
EOM
Aracın konumunu güncelleyin
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.
gRPC
Aşağıdaki örnekte, Fleet Engine'de bir aracın konumunu güncellemek için Java gRPC kitaplığının nasıl kullanılacağı gösterilmektedir:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle myDeliveryVehicle = DeliveryVehicle.newBuilder()
.setLastLocation(DeliveryVehicleLocation.newBuilder()
.setSupplementalLocation(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863))
.setSupplementalLocationTime(now())
.setSupplementalLocationSensor(DeliveryVehicleLocationSensor.CUSTOMER_SUPPLIED_LOCATION)
.setSupplementalLocationAccuracy(DoubleValue.of(15.0))) // Optional
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
UpdateDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(vehicleName)
.setDeliveryVehicle(myDeliveryVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("last_location"))
.build();
try {
DeliveryVehicle updatedDeliveryVehicle =
deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
HTTP REST kullanarak Fleet Engine'de bir aracın konumunu güncellemek için UpdateDeliveryVehicle
çağrısı yapın:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=last_location`
<id>, filonuzdaki teslimat aracı için veya konumu güncellemeyi düşündüğünüz benzersiz bir tanımlayıcıdır. Bu, aracı oluştururken belirttiğiniz tanımlayıcıdır.
İstek başlığında, Bearer <token> değerine sahip bir Yetkilendirme alanı bulunmalıdır. Burada <token>, Fleet Engine jeton fabrikası tarafından verilen bir jetondur.
İstek gövdesinde bir DeliveryVehicle
varlığı bulunmalıdır:
Zorunlu alan:
Alan Değer lastLocation.supplementalLocation Aracın konumu. lastLocation.supplementalLocationTime Aracın bu konumda olduğu bilinen son zaman damgası. lastLocation.supplementalLocationSensor CUSTOMER_supPLIED_LOCATION ile doldurulmalıdır. İsteğe bağlı alanlar:
Alan Değer lastLocation.supplementalLocationAccuracy Sağlanan konumun metre cinsinden doğruluğu.
Örnek curl
komutu:
# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"lastLocation": {
"supplementalLocation": {"latitude": 12.1, "longitude": 14.5},
"supplementalLocationTime": "$(date -u --iso-8601=seconds)",
"supplementalLocationSensor": "CUSTOMER_SUPPLIED_LOCATION",
"supplementalLocationAccuracy": 15
}
}
EOM
Araç durağa geldiğinde
Bir araç durağa geldiğinde Fleet Engine'e bilgi verilmelidir. Fleet Engine'e Sürücü SDK'sından veya gRPC ya da REST kullanarak bir sunucu ortamından bildirim gönderebilirsiniz. Irk koşullarından kaçınmak ve tek doğruluk kaynağı olmak için her iki yöntemi birden kullanmayın.
gRPC
Aşağıdaki örnekte, Fleet Engine'e bir aracın durmada olduğunu bildirmek için Java gRPC kitaplığının nasıl kullanılacağı gösterilmektedir:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
// Marking the arrival at stop.
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.7749)
.setLongitude(122.4194)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
.setState(VehicleStop.State.ARRIVED)))
// All other remaining stops marked as NEW.
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // 2nd stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
.setState(VehicleStop.State.NEW))) // Remaining stops must be NEW.
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
UpdateDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(vehicleName)
.setDeliveryVehicle(deliveryVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("remaining_vehicle_journey_segments"))
.build();
try {
DeliveryVehicle updatedDeliveryVehicle =
deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Fleet Engine'e bir aracın sunucu ortamından duruşta geldiğini bildirmek için UpdateDeliveryVehicle
öğesine HTTP REST çağrısı yapın:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`
<id>, filonuzda görev sıralamasını güncellemeyi düşündüğünüz teslimat aracına ait benzersiz bir tanımlayıcıdır. Bu, aracı oluştururken belirttiğiniz tanımlayıcıdır.
İstek başlığında, Bearer <token> değerine sahip bir Yetkilendirme alanı bulunmalıdır. Burada <token>, Fleet Engine jeton fabrikası tarafından verilen bir jetondur.
İstek gövdesinde bir DeliveryVehicle
varlığı bulunmalıdır:
Zorunlu alanlar:
Alan Değer remainingVehicleJourneySegments Vardığınız durak, durumu State.ARRIVED olarak ayarlandı ve ardından durumları eyalet.YENİ olarak işaretlenmiş kalan araç duraklarının listesi. İsteğe bağlı alanlar:
- Yok
Öğedeki diğer tüm alanlar güncelleme için yoksayılır.
Örnek curl
komutu:
# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"remainingVehicleJourneySegments": [
{
"stop": {
"state": "ARRIVED",
"plannedLocation": {
"point": {
"latitude": 37.7749,
"longitude": -122.084061
}
},
"tasks": [
{
"taskId": "${TASK1_ID}"
}
]
}
},
{
"stop": {
"state": "NEW",
"plannedLocation": {
"point": {
"latitude": 37.3382,
"longitude": 121.8863
}
},
"tasks": [
{
"taskId": "${TASK2_ID}"
}
]
}
}
]
}
EOM
Araç durma işlemini tamamlar
Bir araç durma işlemini tamamladığında Fleet Engine'e bilgi verilmelidir. Bu durum, durakla ilişkili tüm görevlerin KAPALI durumuna ayarlanmasına neden olur. Fleet Engine'i Sürücü SDK'sından veya gRPC ya da REST kullanarak bir sunucu ortamından bilgilendirebilirsiniz. Irk koşullarından kaçınmak ve tek bir doğruluk kaynağı sağlamak için her iki yöntemi de kullanmayın.
gRPC
Aşağıdaki örnekte bir aracın durma işleminin tamamlandığını Fleet Engine'e bildirmek için Java gRPC kitaplığının nasıl kullanılacağı gösterilmektedir.
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
// This stop has been completed and is commented out to indicate it
// should be removed from the list of vehicle journey segments.
// .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()
// .setStop(VehicleStop.newBuilder()
// .setPlannedLocation(LocationInfo.newBuilder()
// .setPoint(LatLng.newBuilder()
// .setLatitude(37.7749)
// .setLongitude(122.4194)))
// .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
// .setState(VehicleStop.State.ARRIVED)))
// All other remaining stops marked as NEW.
// The next stop could be marked as ENROUTE if the vehicle has begun
// its journey to the next stop.
.addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder() // Next stop
.setStop(VehicleStop.newBuilder()
.setPlannedLocation(LocationInfo.newBuilder()
.setPoint(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863)))
.addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
.setState(VehicleStop.State.NEW)))
.build();
// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
UpdateDeliveryVehicleRequest.newBuilder() // no need for the header
.setName(vehicleName)
.setDeliveryVehicle(deliveryVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("remaining_vehicle_journey_segments"))
.build();
try {
DeliveryVehicle updatedDeliveryVehicle =
deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Fleet Engine'e bir sunucu ortamından yapılan durdurma işleminin tamamlandığını bildirmek için UpdateDeliveryVehicle
öğesine bir HTTP REST çağrısı yapın:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remaining_vehicle_journey_segments`
<id>, filonuzda görev sıralamasını güncellemeyi düşündüğünüz teslimat aracına ait benzersiz bir tanımlayıcıdır. Bu, aracı oluştururken belirttiğiniz tanımlayıcıdır.
İstek başlığında, Bearer <token> değerine sahip bir Yetkilendirme alanı bulunmalıdır. Burada <token>, Fleet Engine jeton fabrikası tarafından verilen bir jetondur.
İstek gövdesinde bir DeliveryVehicle
varlığı bulunmalıdır:
Zorunlu alanlar:
Alan Değer remaining_vehicle_journey_segments Tamamladığınız durak, artık kalan araç durakları listesinde olmamalıdır. İsteğe bağlı alanlar:
- Yok
Öğedeki diğer tüm alanlar güncelleme için yoksayılır.
Örnek curl
komutu:
# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"remainingVehicleJourneySegments": [
{
"stop": {
"state": "NEW",
"plannedLocation": {
"point": {
"latitude": 37.3382,
"longitude": 121.8863
}
},
"tasks": [
{
"taskId": "${TASK2_ID}"
}
]
}
}
]
}
EOM
Görev güncelleme
Çoğu görev alanı değiştirilemez. Bununla birlikte, görev varlığını doğrudan güncelleyerek durumu, görev sonucunu, görev sonucu zamanını, görev sonucu konumunu ve özellikleri değiştirebilirsiniz. Örneğin, bir görevin bir araca atanmadığı durumlarda, durumu doğrudan güncelleyerek görevi kapatabilirsiniz.
gRPC
Bu, gRPC aracılığıyla bir görev güncelleme örneğidir.
REST
Bu, REST aracılığıyla bir görev güncelleme örneğidir.
Görevi kapatma
Bir araca atanan bir görevi kapatmak için Fleet Engine'e, aracın görevin gerçekleştiği yerde duruşunu tamamladığını bildirin veya aracı araç durakları listesinden kaldırın. Bunu yapmak için kalan araç duraklarının listesini, bir araç için görev sıralamasını güncellerken olduğu gibi ayarlayabilirsiniz.
Bir göreve henüz araç atanmamışsa ve kapatılması gerekiyorsa görevi KAPALI durumuna güncelleyin. Ancak KAPALI bir görevi yeniden açamazsınız.
Bir görevin kapatılması, başarılı veya başarısız olduğu anlamına gelmez. Görevin artık devam ediyor olarak kabul edilmediğini gösterir. Kargo takibinde bir teslimat sonucunun gösterilebilmesi için bir görevin asıl sonucunu belirtmek önemlidir.
gRPC
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
.setName(taskName)
.setState(Task.State.CLOSED) // You can only directly CLOSE a
.build(); // task that is NOT assigned to a vehicle.
// Task request
UpdateTaskRequest updateTaskRequest =
UpdateTaskRequest.newBuilder() // No need for the header
.setTask(task)
.setUpdateMask(FieldMask.newBuilder().addPaths("state"))
.build();
try {
Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Bir görevi sunucu ortamından kapalı olarak işaretlemek için UpdateTask
öğesine HTTP REST çağrısı yapın:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=state`
<id>, görev için benzersiz bir tanımlayıcıdır.
İstek başlığınızda, Bearer <token> değerine sahip bir Yetkilendirme alanı bulunmalıdır. Burada <token>, Fleet Engine jeton fabrikası tarafından verilen bir jetondur.
İstek gövdesine bir Task
varlığı eklemeniz gerekir:
Zorunlu alanlar:
Alan Değer state State.CLOSED İsteğe bağlı alanlar:
Alan Değer taskOutcome Result.SUCCEEDED veya Result.FAILED taskOutcomeTime Görevin tamamlandığı zaman. taskOutcomeLocation Görevin tamamlandığı konum. Fleet Engine, sağlayıcı tarafından manuel olarak geçersiz kılınmadığı sürece bu ayarı varsayılan olarak son araç konumuna getirir.
Öğedeki diğer tüm alanlar güncelleme için yoksayılır.
Örnek curl
komutu:
# Set JWT, PROJECT_ID, and TASK_ID in the local environment curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=state,taskOutcome,taskOutcomeTime" \ -H "Content-type: application/json" \ -H "Authorization: Bearer ${JWT}" \ --data-binary @- << EOM { "state": "CLOSED", "taskOutcome": "SUCCEEDED", "taskOutcomeTime": "$(date -u --iso-8601=seconds)" } EOM
Görevin sonucunu ve sonucun yerini belirleyin
Bir görevin kapatılması, görevin başarılı ya da başarısız olduğu anlamına gelmez, görevin artık devam etmekte olmadığını gösterir. Kargo takibinde bir görevin asıl sonucunun belirtilmesi önemlidir. Böylece, teslimat sonucunun görüntülenebilir ve hizmetler için uygun faturalandırma yapılabilir. Ayarlandıktan sonra görev sonucunu değiştiremezsiniz. Bununla birlikte, görev sonucu zamanını ve görev sonucu konumunu belirlendikten sonra değiştirebilirsiniz.
KAPALI durumdaki görevlerin sonuçları BAŞARILI veya BAŞARISIZ olarak ayarlanabilir. Fleet Engine, yalnızca SUCCEEDED durumundaki teslimat görevlerini ücretlendirir.
Fleet Engine, bir görevin sonucunu işaretlerken görev sonucu konumunu bilinen son araç konumuyla otomatik olarak doldurur. Bu davranışı geçersiz kılabilirsiniz.
gRPC
Sonucu belirlerken görev sonucunun konumunu da belirleyebilirsiniz. Konumun ayarlanması, Fleet Engine'in konumu son araç konumunun varsayılan değerine ayarlamasını engeller. Ayrıca, daha sonra Fleet Engine adlı görev sonucu konumunun üzerine yazabilirsiniz. Fleet Engine, hiçbir zaman sizin sağladığınız bir görev sonucu konumunun üzerine yazmaz. Bir görev sonucu ayarlanmamış bir görev için görev sonucu konumu ayarlayamazsınız. Aynı istek içinde hem görev sonucunu hem de görev sonucu konumunu belirleyebilirsiniz.
Aşağıdaki örnekte, bir görev sonucunu SUCCEEDED olarak ayarlamak ve görevin tamamlandığı konumu ayarlamak için Java gRPC kitaplığının nasıl kullanılacağı gösterilmektedir:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
.setName(taskName)
.setTaskOutcome(TaskOutcome.SUCCEEDED)
.setTaskOutcomeTime(now())
.setTaskOutcomeLocation( // Grand Indonesia East Mall
LocationInfo.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.build();
// Task request
UpdateTaskRequest updateTaskRequest =
UpdateTaskRequest.newBuilder() // No need for the header
.setTask(task)
.setUpdateMask(FieldMask.newBuilder().addPaths("task_outcome", "task_outcome_time", "task_outcome_location"))
.build();
try {
Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Bir görevi sunucu ortamından tamamlandı olarak işaretlemek için UpdateTask
öğesine HTTP REST çağrısı yapın:
`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=taskOutcome,taskOutcomeTime,taskOutcomeLocation`
<id>, görev için benzersiz bir tanımlayıcıdır.
İstek başlığında, Bearer <token> değerine sahip bir Yetkilendirme alanı bulunmalıdır. Burada <token>, Fleet Engine jeton fabrikası tarafından verilen bir jetondur.
İstek gövdesinde bir Task
varlığı bulunmalıdır:
Zorunlu alanlar:
Alan Değer taskOutcome Result.SUCCEEDED veya Result.FAILED İsteğe bağlı alanlar:
Alan Değer taskOutcomeLocation Görevin tamamlandığı konum. Politika ayarlanmazsa Fleet Engine varsayılan olarak bu ayarı en son araç konumuna ayarlar. taskOutcomeTime Görevin tamamlandığı zaman damgası.
Öğedeki diğer tüm alanlar güncelleme için yoksayılır.
Örnek curl
komutu:
# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=taskOutcome,taskOutcomeTime,taskOutcomeLocation" \
-H "Content-type: application/json" \
-H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
"taskOutcome": "SUCCEEDED",
"taskOutcomeTime": "$(date -u --iso-8601=seconds)",
"taskOutcomeLocation": {
"point": {
"latitude": -6.195139,
"longitude": 106.820826
}
}
}
EOM
Gönderimi yeniden yönlendirme
Bir kargo görevi oluşturulduktan sonra planlanan konumu değiştirilemez. Bir gönderiyi yeniden yönlendirmek için, sonuç belirlemeden gönderim görevini kapatın ve ardından güncellenen planlanan konumla yeni bir görev oluşturun. Yeni görevi oluşturduktan sonra görevi aynı araca atayın. Daha fazla bilgi için gönderim görevini kapatma ve görevi atama bölümünü inceleyin.
Besleyici ve teslimat araçlarını kullanma
Gün içinde gönderileri teslimat araçlarına taşımak için besleyici araçları kullanıyorsanız sevkiyatların transferini teslimat aracı için planlanmış bir durdurma görevi olarak modelleyin. Doğru konum takibini sağlamak amacıyla, aktarılan bir gönderi için yalnızca teslimat aracına yüklendikten sonra bir gönderi teslimat görevi atayın. Daha fazla bilgi için planlanan duraklama bölümünü inceleyin.
Mağaza gönderim durumu ve diğer meta bilgiler
Bir sevkiyat görevi tamamlandığında görev durumu ve sonuç göreve kaydedilir. Ancak gönderime özgü diğer meta bilgileri güncellemek isteyebilirsiniz. Fleet Engine hizmeti dışında referans verebileceğiniz diğer meta bilgileri depolamak için görevle ilişkili tracking_id parametresini harici bir tabloda anahtar olarak kullanın.
Daha fazla bilgi edinmek için Görevlerin yaşam döngüsü başlıklı makaleyi inceleyin.
Araç arayın
Sürücü SDK'sından veya gRPC ya da REST kullanarak bir sunucu ortamından araç arayabilirsiniz.
gRPC
Aşağıdaki örnekte, araç aramak için Java gRPC kitaplığının nasıl kullanılacağı gösterilmektedir:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Vehicle request
String name = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
GetDeliveryVehicleRequest getVehicleRequest = GetDeliveryVehicleRequest.newBuilder() // No need for the header
.setName(name)
.build();
try {
DeliveryVehicle vehicle = deliveryService.getDeliveryVehicle(getVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Sunucu ortamından araç aramak için GetVehicle
öğesine HTTP REST çağrısı yapın:
`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<vehicleId>`
<id>, görev için benzersiz bir tanımlayıcıdır.
<vehicleId>, aranacak aracın kimliğidir.
İstek başlığında, Bearer <token> değerine sahip bir Yetkilendirme alanı bulunmalıdır. Burada <token>, Fleet Engine jeton fabrikası tarafından verilen bir jetondur.
İstek metni boş olmalıdır.
Arama başarılı olursa yanıt gövdesi, bir araç varlığı içerir.
Örnek curl
komutu:
# Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
"https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}"
Görev arama
gRPC veya REST kullanarak bir sunucu ortamından görev arayabilirsiniz. Sürücü SDK'sı görev aramayı desteklemez.
gRPC
Aşağıdaki örnekte, görev aramak için Java gRPC kitaplığının nasıl kullanılacağı gösterilmektedir:
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8597549";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Task request
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
GetTaskRequest getTaskRequest = GetTaskRequest.newBuilder() // No need for the header
.setName(taskName)
.build();
try {
Task task = deliveryService.getTask(getTaskRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Sunucu ortamında görev aramak için GetTask
öğesine HTTP REST çağrısı yapın:
`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<taskId>`
<id>, görev için benzersiz bir tanımlayıcıdır.
<taskId>, aranacak görevin kimliğidir.
İstek başlığında, Bearer <token> değerine sahip bir Yetkilendirme alanı bulunmalıdır. Burada <token>, Fleet Engine jeton fabrikası tarafından verilen bir jetondur.
İstek metni boş olmalıdır.
Arama başarılı olursa yanıt gövdesi, bir görev varlığı içerir.
Örnek curl
komutu:
# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
"https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}"
Takip kimliğine göre kargo görevi bilgilerini arama
Gönderim görevi bilgilerini aşağıdaki şekillerde arayabilirsiniz. Her birinin farklı bir amacı vardır:
- bir görev kimliği tarafından: Görev verilerinin tam görünümüne erişimi olan filo operatörleri gibi kullanıcılar tarafından kullanılır.
- izleme kimliği tarafından: İstemci yazılımınız tarafından son kullanıcıya sınırlı bilgi (örneğin, evinde paket olması planlandığı zaman) sunmak için kullanılır.
Bu bölümde, izleme kimliğiyle görev bilgilerini arama konuları ele alınmaktadır. Bir görevi görev kimliğine göre aramak istiyorsanız Görev arama bölümüne gidin.
İzleme kimliğine göre bilgi aramak için aşağıdakilerden birini kullanabilirsiniz:
Arama koşulları
Takip kimliği tarafından sağlanan gönderim bilgileri, Takip edilen konumların görünürlüğünü kontrol etme bölümünde belirtilen görünürlük kurallarına uygundur.
İzleme kimliğiyle kargo bilgilerini aramak için Fleet Engine'i kullanın. Driver SDK, izleme kimliğiyle bilgi aramalarını desteklemez. Fleet Engine ile bunu yapmak için bir sunucu veya tarayıcı ortamı kullanırsınız.
Güvenlik risklerini sınırlandırmak için mümkün olan en dar jetonu kullanın. Örneğin, Delivery Consumer Token kullanırsanız Fleet Engine Deliveries API çağrıları, yalnızca kargo şirketi veya gönderi alıcısı gibi son kullanıcıyla alakalı bilgileri döndürür. Yanıtlardaki diğer tüm bilgiler çıkartılır. Jetonlar hakkında daha fazla bilgi için Yetkilendirme için JSON Web Token (JWT) oluşturma bölümüne bakın.
gRPC kullanarak Java ile arama
Aşağıdaki örnekte, bir kargo göreviyle ilgili izleme kimliğine göre bilgi aramak için Java gRPC kitaplığının nasıl kullanılacağı gösterilmektedir.
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TRACKING_ID = "TID-7449w087464x5";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Tasks request
String parent = "providers/" + PROJECT_ID;
GetTaskTrackingInfoRequest getTaskTrackingInfoRequest = GetTaskTrackingInfoRequest.newBuilder() // No need for the header
.setParent(parent)
.setTrackingId(TRACKING_ID)
.build();
try {
TaskTrackingInfo taskTrackingInfo = deliveryService.getTaskTrackingInfo(getTaskTrackingInfoRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
HTTP kullanarak arama yapar
Tarayıcıdan kargo görevi aramak için GetTaskTrackingInfo
öğesine HTTP REST çağrısı yapın:
`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/taskTrackingInfo/<tracking_id>`
<tracking_id>, görevle ilişkilendirilen izleme kimliğidir.
İstek başlığında, Bearer <token> değerine sahip bir Yetkilendirme alanı bulunmalıdır. Burada <token>, Fleet Engine jeton fabrikası tarafından verilen bir jetondur.
Arama başarılı olursa yanıt gövdesi, bir taskTrackingInfo varlığı içerir.
Örnek curl
komutu:
# Set JWT, PROJECT_ID, and TRACKING_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
"https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/taskTrackingInfo/${TRACKING_ID}"
Görevleri listeleyin
Bir sunucu veya tarayıcı ortamındaki görevleri listeleyebilirsiniz. Sürücü SDK'sı görevleri listelemeyi desteklemez.
Görevleri listelemek, görevlere geniş kapsamlı erişim gerektirir. Giriş görevleri yalnızca güvenilir kullanıcılar içindir. Liste görevleri için istekte bulunurken Teslim Filosu Okuyucu veya Yayınlama Süper Kullanıcı Kimlik Doğrulama Jetonlarını kullanın.
Listelenen görevlere aşağıdaki alanlar çıkartılır:
- VehicleStop.planned_location
- VehicleStop.state
- VehicleStop.TaskInfo.taskId
Listedeki görevler, çoğu görev özelliğine göre filtrelenebilir. Filtre sorgusu söz dizimi için AIP-160'a göz atın. Aşağıdaki listede filtreleme için kullanabileceğiniz geçerli görev özellikleri gösterilmektedir:
- attributes
- delivery_vehicle_id
- state
- planned_location
- task_duration
- task_outcome
- task_outcome_location
- task_outcome_location_source
- task_outcome_time
- tracking_id
- tür
Google API İyileştirme Teklifleri'ne dayalı olarak aşağıdaki alan biçimlerini kullanın:
Alan Türü | Biçim | Örnek |
---|---|---|
Zaman damgası | RFC-3339 | task_outcome_time = 2022-03-01T11:30:00-08:00 |
Süre | Saniyenin ardından s gelmelidir |
task_duration = 120s |
Enum | Dize | state = CLOSED AND type = PICKUP |
Konum | point.latitude ve point.longitude |
planned_location.point.latitude > 36.1 AND planned_location.point.longitude < -122.0 |
Filtre sorgusu operatörlerinin tam listesi için AIP-160 web sitesine bakın.
Filtre sorgusu belirtilmemişse tüm görevler listelenir.
Görev listeleri sayfalara ayrılır. Liste görevleri isteklerinde sayfa boyutu belirtilebilir. Bir sayfa boyutu belirtilirse döndürülen görevlerin sayısı belirtilen sayfa boyutundan fazla olmaz. Sayfa boyutu yoksa makul bir varsayılan kullanılır. İstenen sayfa boyutu dahili bir maksimum değeri aşarsa dahili maksimum değer kullanılır.
Görev listesi, sonuçların sonraki sayfasını okumak için bir jeton içerebilir. Görevlerin sonraki sayfasını almak için önceki isteğe benzer bir istekle sayfa jetonunu kullanın. Döndürülen sayfa jetonu boş olduğunda, alınabilecek başka görev olmaz.
gRPC
Aşağıdaki örnekte, deliveryAraçId ve görev özelliğiyle ilgili görevleri listelemek için Java gRPC kitaplığının nasıl kullanılacağı gösterilmektedir. Başarılı bir yanıt hâlâ boş olabilir. Boş bir yanıt, sağlanan deliveryAraçId ile ilişkili bir Görev olmadığını gösterir.
static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TRACKING_ID = "TID-7449w087464x5";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Tasks request
String parent = "providers/" + PROJECT_ID;
ListTasksRequest listTasksRequest = ListTasksRequest.newBuilder() // No need for the header
.setParent(parent)
.setFilter("delivery_vehicle_id = 123 AND attributes.foo = true")
.build();
try {
ListTasksResponse listTasksResponse = deliveryService.listTasks(listTasksRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Bir tarayıcıdan görevleri listelemek için ListTasks
öğesine HTTP REST çağrısı yapın:
`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks`
Listelenen görevlere filtre uygulamak için değer olarak URL çıkışlı filtre sorgusu içeren bir "filtre" URL parametresi ekleyin.
İstek başlığında, Bearer <token> değerine sahip bir Yetkilendirme alanı bulunmalıdır. Burada <token>, Fleet Engine jeton fabrikası tarafından verilen bir jetondur.
Arama başarılı olursa yanıt gövdesi, aşağıdaki yapıya sahip verileri içerir:
// JSON representation
{
"tasks": [
{
object (Task)
}
],
"nextPageToken": string,
"totalSize": integer
}
Başarılı bir yanıt yine de boş olabilir. Boş bir yanıt, belirtilen filtre ölçütlerini karşılayan hiçbir görevin bulunamadığını gösterir.
Örnek curl
komutu:
# Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
"https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?filter=state%20%3D%20OPEN%20AND%20delivery_vehicle_id%20%3D%20${VEHICLE_ID}"
Teslimat araçlarını listeleme
Teslimat araçlarını bir sunucu veya tarayıcı ortamından listeleyebilirsiniz. Driver SDK, teslimat araçlarının listelenmesini desteklemez.
Teslimat araçlarını listelemek, teslimat araçlarına geniş kapsamlı erişim gerektirir ve yalnızca güvenilir kullanıcılar içindir. Liste teslimi araçları için istekte bulunurken Teslim Filosu Okuyucu veya İletim Süper Kullanıcı Kimlik Doğrulama Jetonlarını kullanın.
Listedeki teslimat araçlarında, yanıt boyutu üzerindeki etkileri nedeniyle aşağıdaki alanlar çıkartılır:
- CurrentRouteSegment
- RemainingVehicleJourneySegments
Liste yayınlama araçlarını attributes
özelliklerine göre filtreleyebilirsiniz. Örneğin, my_key
anahtarı ve my_value
değerine sahip bir özelliği sorgulamak için attributes.my_key = my_value
değerini kullanın. Birden fazla özelliği sorgulamak için sorguları, attributes.key1 = value1 AND
attributes.key2 = value2
'deki gibi mantıksal AND
ve OR
operatörlerini kullanarak birleştirin. Filtre sorgusu söz diziminin tam açıklaması için AIP-160 adresine bakın.
viewport
istek parametresini kullanarak listelenen teslimat araçlarını konuma göre filtreleyebilirsiniz. viewport
istek parametresi, iki sınırlayıcı koordinat kullanarak görüntü alanları tanımlar: high
(kuzeydoğu) ve low
(Güneybatı) enlem ve boylam koordinat çifti. Coğrafi olarak düşük enlemden daha düşük bir yüksek enlem içeren istekler reddedilir.
Teslimat aracı listeleri, varsayılan olarak makul bir sayfa boyutu kullanılarak sayfalara ayrılır. Bir sayfa boyutu belirtirseniz istek yalnızca sınır tarafından belirtilen araç sayısını veya daha azını döndürür. İstenen sayfa boyutu dahili bir maksimum değeri aşarsa dahili maksimum değer kullanılır. Varsayılan ve maksimum sayfa boyutları 100 araçtır.
Teslimat araçları listesi, bir sonraki sonuç sayfasını okumak için bir jeton içerebilir. Sayfa jetonu yalnızca alınabilecek daha fazla teslimat aracı sayfası olduğunda yanıtta bulunur. Görevlerin bir sonraki sayfasını almak için sayfa jetonunu, önceki istekle aynı olan bir istekle birlikte kullanın.
gRPC
Aşağıdaki örnekte, belirli bir bölgede belirli özelliğe sahip teslimat araçlarını listelemek için Java gRPC kitaplığının nasıl kullanılacağı gösterilmektedir. Başarılı bir yanıt yine de boş olabilir. Bu durum, belirtilen özelliğe sahip hiçbir aracın belirtilen görüntü alanında bulunmadığı anlamına gelir.
static final String PROJECT_ID = "my-delivery-co-gcp-project";
DeliveryServiceBlockingStub deliveryService =
DeliveryServiceGrpc.newBlockingStub(channel);
// Tasks request
String parent = "providers/" + PROJECT_ID;
ListDeliveryVehiclesRequest listDeliveryVehiclesRequest =
ListDeliveryVehiclesRequest.newBuilder() // No need for the header
.setParent(parent)
.setViewport(
Viewport.newBuilder()
.setHigh(LatLng.newBuilder()
.setLatitude(37.45)
.setLongitude(-122.06)
.build())
.setLow(LatLng.newBuilder()
.setLatitude(37.41)
.setLongitude(-122.11)
.build())
.setFilter("attributes.my_key = my_value")
.build();
try {
ListDeliveryVehiclesResponse listDeliveryVehiclesResponse =
deliveryService.listDeliveryVehicles(listDeliveryVehiclesRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
REST
Bir tarayıcıdan görevleri listelemek için ListDeliveryVehicles
öğesine HTTP REST çağrısı yapın:
`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles`
Listelenen görevlere filtre uygulamak için değeri olarak URL çıkışlı filtre sorgusu içeren bir "filter" URL parametresi ekleyin.
İstek başlığında, Bearer <token> değerine sahip bir Yetkilendirme alanı bulunmalıdır. Burada <token>, Fleet Engine jeton fabrikası tarafından verilen bir jetondur.
Arama başarılı olursa yanıt gövdesi, aşağıdaki yapıya sahip verileri içerir:
// JSON representation
{
"deliveryVehicles": [
{
object (DeliveryVehicle)
}
],
"nextPageToken": string,
"totalSize": integer
}
Başarılı bir yanıt yine de boş olabilir. Bu durum, belirtilen filtre sorgusu ve görüntü alanıyla eşleşen bir teslimat aracı bulunamadığı anlamına gelir.
Örnek curl
komutu:
# Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
"https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?filter=attributes.my_key%20%3D%20my_value%20&viewport.high.latitude=37.45&viewport.high.longitude=-122.06&viewport.low.latitude=37.41&viewport.low.longitude=-122.11"
Gönderim takibi
Gönderim takibini etkinleştirmek için Fleet Engine Deliveries API'yi iki şekilde kullanabilirsiniz:
Tercih edilen: JavaScript Gönderim İzleme kitaplığını kullanın. Kitaplık, Fleet Engine'de izlenen araçların ve ilgilenilen konumların konumlarını görselleştirmenize olanak tanır. Bu paket, standart bir google.maps.Map nesnesinin yerini alacak bir JavaScript harita bileşeni ve Fleet Engine'e bağlanacak veri bileşenleri içerir. Bu bileşen, web veya mobil uygulamanızdan özelleştirilebilir, animasyonlu bir kargo takibi deneyimi sağlamanıza olanak tanır.
Fleet Engine Deliveries API'nin üzerine kendi gönderi izlemenizi uygulayın.
Önemli olan, izleme kimliğine göre kargo görevlerini aramaktır.
Teslimat Tüketicisi Rolü kullanırsanız Fleet Engine Deliveries API çağrıları yalnızca bir gönderen veya alıcıyla alakalı bilgileri döndürür. Yanıtlardaki diğer tüm bilgiler çıkarılır. Son kullanıcıların kimliğini doğrulamak sizin sorumluluğunuzdadır. Ayrıca, konum bilgileri yapılmakta olan göreve göre filtrelenir. Müsaitlik durumu görevi sırasında son kullanıcıyla konum bilgisi paylaşılmaz.
Günlük Kaydı
Fleet Engine'i, RPC günlüklerini Cloud Logging'e gönderecek şekilde ayarlayabilirsiniz. Daha fazla bilgi için Günlük Kaydı bölümünü inceleyin.
Yetkilendirme Rolleri ve Jetonları
Araç ve görev yaşam döngüsünü yönetme bölümünde ve bireysel kullanım alanları için yetkilendirme notlarında açıklandığı gibi, Fleet Engine'e çağrı yapmak için hizmet hesabı kimlik bilgileri kullanılarak imzalanmış JSON Web Jetonları ile kimlik doğrulama gerekir. Bu jetonları yayınlamak için kullanılan hizmet hesaplarının bir veya daha fazla rolü olabilir. Bu rollerdeki her rol, farklı bir izin grubu verir.
Daha fazla bilgi için Kimlik Doğrulama ve Yetkilendirme bölümüne bakın.
Sık karşılaşılan sorunları giderme
Sorunla karşılaşırsanız yardım almak için aşağıdaki bölümlere göz atın.
Esneklik
Fleet Engine, doğru kaynak olarak kabul edilmez. Fleet Engine'e güvenmeden, gerekirse sisteminizin durumunu geri yüklemekten siz sorumlu olursunuz.
Fleet Engine'de kayıp durum
Fleet Engine ile çalışırken, bir hata oluştuğunda sistemin kendi kendini iyileştirmesi için istemcileri uygulayın. Örneğin, Fleet Engine bir aracı güncellemeye çalıştığında, aracın mevcut olmadığını belirten bir hatayla yanıt verebilir. Ardından müşteri, aracı yeni durumda yeniden oluşturmalıdır. Bu sorun nadiren meydana gelse de, sisteminizin bu sorunla başa çıkacak kadar dayanıklı olduğundan emin olun.
Çok düşük bir ihtimal de olsa Fleet Engine'de ciddi bir arıza yaşandığı senaryosunda, araçların ve görevlerin çoğunu veya tamamını yeniden oluşturmanız gerekebilir. Oluşturma hızı çok yükselirse hizmet reddi (DOS) saldırılarını önlemek için kota kontrolleri yapıldığından bazı istekler kota sorunları nedeniyle tekrar başarısız olabilir. Bu durumda, tekrar denemeler için bir geri yükleme stratejisi kullanarak yeniden oluşturma oranını yavaşlatın.
Sürücü uygulamasında kayıp durum
Sürücü uygulaması kilitlenirse uygulama, Driver SDK'sında mevcut durumu yeniden oluşturmalıdır. Uygulama, görevlerin mevcut olduğundan emin olmak ve mevcut durumlarını geri yüklemek için görevleri yeniden oluşturmayı denemelidir. Uygulama ayrıca Driver SDK'sı için durak listesini yeniden oluşturmalı ve açıkça ayarlamalıdır.
SSS
Sürücü bir görevin sırasının bozulması nedeniyle durursa ne olur?
Bu durumda ilk olarak görevlerin sırasını güncelleyin, ardından durağa varışı, görev tamamlanmayı ve diğer ayrıntıları işaretleyerek normal bir şekilde devam edin. Aksi takdirde sistem tutarsız hale gelebilir, GMR'ler hatalı olabilir ve beklenmedik hatalar bildirilebilir.