Gerçek zamanlı bisiklet kullanılabilirliğini uygulamada göstermek için, dönen sayıyı güncelliği ve aracın alınabilirlik durumlarıyla ilişkilendirin. Bir gözlem, kaynağın belirli bir andaki bilgisini anlatır; varışta bisikletin hala mevcut olacağını garanti etmez.
ROOTE hareketlilik sözleşmesi istasyonları, bireysel araçları ve durumlarını ayırt eder. Arayüz, bilinmeyen bir değeri, boş bir istasyonu ve geçici olarak erişilemez bir kaynağı karıştırmadan bu farklılıkları yansıtmalıdır.
Bir istasyonu bireysel araçtan ayırmak
Bir istasyon bisiklet ve dönme yeri sayacı gösterebilir. Bireysel araç ise kullanılabilirlik durumu ve diğer bilgileri taşır. Bir istasyonu bisikletle saymaktan veya aynı stoğu temsil eden sayaçları toplamaktan kaçının.
ROOTE hareketlilik DTO'sunda availability.bikes ve availability.docks bilinmeyen olabilir. Tahrik veya batarya alanları yalnızca varsa gösterilmeli ve sözleşmeye göre yorumlanmalıdır.
Güncellik ve zaman damgalarını okumak
| Alan | Yorum |
|---|---|
| freshness.state | Bildirilen durum: fresh (taze), stale (bayat), unknown (bilinmeyen) veya static (statik) |
| freshness.source_updated_at | Kaynağın güncelleme tarihi, biliniyorsa |
| freshness.received_at | Sözleşmede belirtilen alınma tarihi |
| freshness.expires_at | Bildirilen geçerlilik süresi, biliniyorsa |
| availability.bikes | Bilineni veya bilinmeyen değeri |
| pickup.enabled ve pickup.state | İstasyondan bisiklet alma bilgileri |
Çağrınızın zamanı otomatik olarak gözlem zamanı değildir. 10:00'de alınan sonuç, kaynağın 09:45'te güncellendiğini içerebilir. Arayüz saatine göre “şimdi güncellendi” göstermeyin.
Farklı gösterim durumları planlayın
| Alınan veri | Planlanan gösterim |
|---|---|
| Bilinir miktar ve taze veri | Gözlemlenen miktar ve zamansal gösterim |
| Miktar sıfır ise | Bisiklet gözlemlenmedi, zamansal bağlam ile |
| Miktar null ise | Kullanılabilirlik bilinmiyor |
| Stale durum veya süre aşımı | Eski veri; yenileme önerisi |
| pickup.enabled=false | Sayaç pozitif olsa bile alma mümkün değil |
| Arama hatası | Kullanılabilirlik geçici olarak yok, sıfıra çevrilmez |
Bilinmeyen veya statik durumları taze olarak sınıflandırmayın. Bir istasyon bilgisi stabil olabilir ama sayaç hızlı değişebilir. Ayrıca yanıt gerektirdiği uyarılar ve atamaları da koruyun.
Görüntüleme öncesi normalizasyon örneği
Aşağıdaki fonksiyon, ROOTE şemasına uygun bir istasyondan sunum durumu oluşturur. Tam bir yanıt doğrulayıcı değildir. Görünen etiketler, arayüzünüzün çeviri anahtarlarından gelmelidir.
function availabilityView(station, now = Date.now()) {
const freshness = station.freshness;
const expiresAt = freshness.expires_at
? Date.parse(freshness.expires_at) : null;
const expired = expiresAt !== null &&
Number.isFinite(expiresAt) && expiresAt <= now;
if (station.pickup.enabled === false ||
station.pickup.state === 'unavailable_now') {
return { state: 'pickup_unavailable', count: null };
}
if (expired || freshness.state === 'stale') {
return { state: 'stale', count: null };
}
const count = station.availability.bikes;
if (freshness.state !== 'fresh' || count === null ||
!Number.isFinite(count) || count < 0) {
return { state: 'unknown', count: null };
}
return {
state: count === 0 ? 'empty' : 'observed', count,
sourceUpdatedAt: freshness.source_updated_at,
receivedAt: freshness.received_at,
pickupState: station.pickup.state
};
}Gözlemlenmiş durumda bile pickupState=unknown'u onaylı alma olarak değiştirmeyin. Sayaç bir gözlemdir. Ürününüz kullanıcıya istasyon seçmede yardımcı oluyorsa, alma bağlamını gösterin.
Gereksiz çağrıları çoğaltmadan yenileme
Yenilemeyi bildirilen son kullanma tarihine, hizmet koşullarına ve kullanıcı davranışına göre ayarlayın. Aynı isteği gruplayın, arka planda aktif olmayan sayfada çağrı yapmaktan kaçının, değişen aramaları iptal edin.
Yerel önbellek süresi kaynağın güncelliğini kanıtlamaz. Hata sonrası, arayüzde açıkça eski olarak sunulduğu sürece, son tarihlendirilmiş gözlemi saklayabilirsiniz. Kaynak stale kalırsa, ilk başarılı alımda bu ayrımı silmeyin.
GBFS ile ilişkiyi anlamak
GBFS, paylaşımlı hareketlilik servisleri ve yayınlanan durumlarını tanımlar. Doğrudan entegrasyon dosyaları, sürümü ve zaman damgalarını yorumlamalıdır. Standardize API varsa, API sözleşmesini kullanın; yanıtında olmayan GBFS alanını eklemeyin.
GTFS, GTFS Realtime ve GBFS arasından seçim
Kullanıcıyı yanıltan durumları test edin
Gerçek sıfır, bilinmeyen değer, süre aşımı, devre dışı alma ve geçerli sonuç sonrası hatayı test edin. Gösterim zaman dilimlerini kontrol edin. Pozitif sayaç “ayrılmış bisiklet” değil, ulaşılamazlık boş sıfır üretmemeli.
Boş yanıtları ve hataları yönetmek
Bu kuralları bir Yapay Zeka yardımcısında uygulamak
Bisiklet bulmak için kullanıcı rehberi
Sıkça Sorulan Sorular
Pozitif miktar varlığı gelişte bisiklet garantiler mi?
Hayır. Bu bir gözlemdir, arama ile varış arasında değişebilir.
Null değeri sıfırla değiştirebilir miyiz?
Hayır. Null bilinmeyen değeri gösterir; sıfır bilinen miktardır ve farklı anlam taşır.
Her birkaç saniyede bir yenilemek gerekli mi?
Geçerlilik göstergeleri, hizmet sınırları ve arayüz ihtiyaçlarına göre kullanın. Rastgele sıklık kaynak tazeliği sağlamaz.