انتقل إلى المحتوى
TLGPSالتوثيق

توثيق المطورين

Gateway / V1

تحديثات المركبة

اتصالات Gateway V1 واشتراكات المركبات والتحديثات المدعومة.

تخص رسائل telemetry المركبة التي أُنشئ الاشتراك لها. يحمل كل تحديث معلومات الاشتراك وUUID المركبة وحالتها. يمكن أن تتعايش عدة اشتراكات على الاتصال نفسه.

الصلاحيات المطلوبة

يتطلب مسار التكامل برمز شخصي قدرة telemetry.subscribe والصلاحية الفعلية المقابلة، بالإضافة إلى صلاحية المركبة ورؤيتها ضمن الشركة. تستخدم البوابة مسار اعتماد متصفح مخصصًا يخضع لقدرات التتبع وصلاحياته؛ وليس تجاوزًا عامًا للتصريح.

الحالة الأولية والتحديثات اللاحقة

عند توفر حالة حالية، يمكن أن يلي إقرار الاشتراك تحديث أولي. وعند ورود تتبع مدعوم لاحقًا، تصل رسالة مثل:

{
    "type": "telemetry",
    "timestamp": "2026-06-30T19:53:37+02:00",
    "data": {
        "subscription": {
            "topic": "vehicle",
            "identifier": "01900000-0000-7000-8000-000000000001"
        },
        "vehicle": {
            "uuid": "01900000-0000-7000-8000-000000000001",
            "state": {
                "source": "realtime",
                "status": {
                    "connection": "online",
                    "movement": "parked"
                },
                "coordinates": {
                    "latitude": 0.0,
                    "longitude": 0.0
                },
                "geo_address": null,
                "speed": {
                    "kmh": 0,
                    "mps": 0
                },
                "gps_status": true,
                "angle": 61,
                "altitude": -1,
                "ignition": {
                    "status": "off"
                },
                "oil": 0,
                "voltage": 26.16,
                "mileage": {
                    "km": 27246189,
                    "meters": 27246189000
                },
                "temperature": "-255",
                "timestamps": {
                    "gps": "2026-06-30T17:52:51.000000Z",
                    "received": "2026-06-30T17:52:52.506493Z",
                    "last_synced": null
                }
            }
        }
    }
}

تستخدم vehicle.state تمثيل القيَم المشتركة نفسه المستخدم في location لدى REST عند تمثيل اللقطة المحلولة نفسها: أرقام الإحداثيات، ووحدات السرعة والمسافة وتقريبها، وقيَم الحالة والقيَم المنطقية وnull. لا يتضمن هذا التمثيل UUID الجهاز أو بيانات المصدر الخام أو بيانات الاعتماد.

تحتفظ طوابع الحالة timestamps.gps وreceived وlast_synced في Gateway V1 بصيغة UTC ISO-8601 وست خانات كسرية مع Z، أو null. يحتفظ REST V1 بصيغته الحالية وفق المنطقة الزمنية للتطبيق وإزاحتها وبدقة الثواني. يحافظ هذا الاختلاف على توافق V1؛ حلّل الوقت وقارن وفق الدقة المتاحة بدل مقارنة النصوص. أما timestamp في غلاف رسالة Gateway فيمثل وقت إرسال الرسالة بصيغة ISO-8601 وفق منطقة التطبيق وبدقة الثواني، لا وقت رصد GPS.

تستخدم geo_address العنوان المتاح في اللقطة أو null؛ لا ينفذ التسلسل طلب ترميز جغرافي عكسي. يتشارك النقلان display_name وcity وstate وcountry وcountry_code. ويحتفظ Gateway V1 أيضًا بمراجع الترميز الجغرافي الاختيارية place_id وosm_type وosm_id للتوافق مع العملاء الحاليين، بينما لا يعرضها REST. تستخدم الحالة الأولية والتحديثات اللاحقة تمثيل Gateway نفسه، وتبقى الحالة الأولية مشروطة بتوفر لقطة.

يظل الغلاف خاصًا بكل نقل، وقد تلاحظ القراءات والاشتراكات المنفصلة لقطات مختلفة. لا يعني ذلك تطابق الحمولات نصيًا أو ضمان التسليم أو زمن الوصول.

مفاهيم حقول الحالة

الحقل المعنى
source مصدر الحالة المحلولة
status حالة الاتصال والحركة
coordinates الإحداثيات إن توفرت
geo_address عنوان الموقع إن توفر
speed السرعة بوحداتها
gps_status صلاحية تحديد الموقع
angle وaltitude الاتجاه والارتفاع
ignition حالة التشغيل
oil وvoltage وtemperature قراءات مستشعرات اختيارية
mileage المسافة بوحداتها
timestamps أوقات الرصد والاستقبال والمزامنة حسب الإتاحة

تُرسل البيانات أثناء استمرار الاشتراك المصرّح به. تعامل مع تكرار التحديثات، والقيَم غير المتاحة، والانقطاع؛ لا يُعلن هذا المرجع ضمانًا للتسليم أو زمن الوصول أو إعادة إرسال الرسائل الفائتة.

توثيق عام · يتطلب التكامل وصولًا مصرّحًا به

توثيق تديره فرق الهندسة. تستخدم الأمثلة بيانات توضيحية وقيَمًا بديلة لبيانات الاعتماد.

العودة إلى الأعلى