Gateway / V1
واجهة Gateway V1
اتصالات Gateway V1 واشتراكات المركبات والتحديثات المدعومة.
نظرة عامة
تتيح Gateway V1 اتصالات موثّقة واشتراكات في تحديثات تتبع المركبات المدعومة. لا يُفهم من ذلك ضمان للتسليم أو زمن الوصول.
بخلاف طلبات REST المنفصلة، يقيم العميل اتصال WebSocket مستمرًا، ويصادق، ثم يشترك في المركبات المسموح برؤيتها. يتلقى التحديثات المدعومة أثناء استمرار الاتصال والاشتراك دون طلب قراءة جديد لكل تحديث.
تعتمد إتاحة التتبع على المصدر والجهاز المهيأين. يتولى العميل الحفاظ على الاتصال وإدارة الاشتراكات والتعافي بعد الانقطاع. كل المُعرّفات والقيَم في الأمثلة بيانات توضيحية، والرموز بدائل غير صالحة للاستخدام.
عنوان Gateway
العنوان العام المهيأ:
wss://ws.tlgps.athear.ly
استخدم العنوان المخصص لبيئتك. استخدم WSS للتكاملات المنشورة؛ قد تستخدم بيئة التطوير WS.
أصل اتصال المتصفح
إذا أرسل العميل ترويسة Origin فيجب أن تطابق أصلًا يسمح به إعداد TLGPS. نسّق متطلبات أصل المتصفح مع جهة الاتصال المخوّلة. قد لا ترسل الأنظمة التي لا تعمل في المتصفح هذه الترويسة؛ غيابها لا يتجاوز المصادقة أو صلاحيات العملية والموارد.
إصدار البروتوكول
يشير هذا المرجع إلى V1. تعلن رسالة authenticated عن إصدار Gateway ومهلة الخمول. استخدم القيم الفعلية الواردة في الاتصال بدل افتراض إعداد ثابت.
المصادقة
تحتاج تكاملات Gateway إلى رمز وصول شخصي مناسب، وشركة نشطة يتوفر لها Gateway، وصلاحيات المستخدم المناسبة. تستخدم البوابة نفسها اعتماد متصفح قصير العمر ومنفصلًا. لا تضع رمز وصول شخصيًا في شيفرة متصفح عامة.
الحصول على الرمز
يمكن للمستخدم المخوّل إصدار رمز من صفحة رموز API في البوابة. إذا لم تتوفر هذه الصلاحية فتواصل مع مسؤول مخوّل. لا يوفر التوثيق مسارًا عامًا لإصدار الرموز.
يملك الرمز اسمًا وقدرات وتاريخ انتهاء إذا حُدد. احفظ السر في خادم موثوق. تحتاج اشتراكات التكامل إلى قدرة الرمز telemetry.subscribe والصلاحية الفعلية المقابلة والوصول إلى المركبة. لا تستبدل قدرات REST مثل vehicles.view أو vehicles.history هذه المتطلبات.
رسالة المصادقة
افتح الاتصال ثم أرسل:
{ "type": "authenticate", "data": { "token": "<gateway-ticket-or-personal-access-token>" } }
تنبيه
لا تستخدم رمزًا حقيقيًا في أمثلة مشتركة.
يتطلب الاتصال مصادقة مستقلة؛ انتظر رسالة نجاح قبل الاشتراك.
تأكيد المصادقة
{ "type": "authenticated", "timestamp": "2026-07-01T10:19:12+02:00", "data": { "gateway": { "version": "v1", "heartbeat": { "idle_timeout": 120 } } } }
قيمة gateway.heartbeat.idle_timeout بالثواني. مثال 120 قيمة توضيحية لإعداد الاتصال؛ اعتمد القيمة التي يعيدها خادم بيئتك.
فشل المصادقة
{ "type": "error", "timestamp": "2026-06-30T19:38:34+02:00", "data": { "error": "authentication_failed", "message": "Authentication failed." } }
قد يغلق الخادم الاتصال بعد فشل المصادقة. لا تفترض بقاء المقبس متاحًا بعد رسالة خطأ.
انتهاء بيانات الاعتماد وتغيّر الوصول
لا تتيح الرموز المنتهية أو الملغاة إنشاء وصول جديد. تخضع الاتصالات القائمة لإعادة تحقق دورية من بيانات الاعتماد وإتاحة الشركة والصلاحيات ورؤية المركبات. قد تُزال اشتراكات أو يُغلق الاتصال عند تغير الوصول؛ لا يُضمن السحب الفوري.
اعتماد المتصفح الذي تستخدمه البوابة ليس واجهة عامة لإصدار رموز التكامل. نسّق أي تكامل متصفح مخصص مع TLGPS بدل تضمين رمز وصول شخصي فيه.
إغلاق الاتصال وإعادته
قد يرسل الخادم رسالة أخيرة مثل:
{ "type": "connection_closed", "timestamp": "2026-06-30T19:38:34+02:00", "data": { "reason": "unauthorized", "message": "Connection authorization is no longer valid." } }
عند الانقطاع تُزال اشتراكات الاتصال. أنشئ اتصالًا جديدًا وصادق مجددًا وأعد الاشتراكات المسموح بها. لا تفترض استعادتها تلقائيًا أو إعادة إرسال ما فات من رسائل.
صيغ الرسائل
تُرسل الرسائل بصيغة JSON. تستخدم رسائل الخادم الغلاف التالي:
{ "type": "<message-type>", "timestamp": "2026-10-18T12:00:00+00:00", "data": {} }
يحدد type نوع الرسالة، ويحمل timestamp وقت إرسالها بصيغة ISO-8601، وتحتوي data على بيانات النوع. لطلبات العميل صيغها الخاصة أدناه؛ لا يُطلب طابع زمني من العميل.
رسائل العميل
| النوع | الغرض |
|---|---|
authenticate |
مصادقة الاتصال |
subscribe |
طلب اشتراكات مركبات |
unsubscribe |
إزالة اشتراكات |
ping |
الحفاظ على نشاط الاتصال |
رسائل الخادم
| النوع | المعنى |
|---|---|
authenticated |
نجحت المصادقة |
subscribed |
أُقرّ الاشتراك |
unsubscribed |
أُقرّ إلغاء الاشتراك |
telemetry |
حالة أو تحديث تتبع مركبة |
pong |
رد فحص الاتصال |
error |
خطأ في الطلب أو البروتوكول |
connection_closed |
إغلاق الاتصال |
تجاهل أنواع رسائل الخادم والحقول التي لا تعرفها. لا تفترض ترتيبًا مشتركًا بين اتصالات مختلفة أو عبر إعادة الاتصال، ولا تعتمد على ترتيب خصائص JSON.
فحص الاتصال
أرسل ping دوريًا خلال عمر الاتصال، ويجيب الخادم بـ pong. اختر فترة أقصر من مهلة الخمول التي أعلنها الاتصال. قد يغلق الخادم اتصالًا خاملًا أو غير مستجيب.
طلب فحص الاتصال
{ "type": "ping", "data": {} }
رد فحص الاتصال
{ "type": "pong", "timestamp": "2026-06-30T19:38:34+02:00", "data": {} }
لا تتطلب رسائل الفحص اشتراكًا ولا تحمل تتبعًا. استمر في إرسالها أثناء الاشتراكات. بعد الانقطاع صادق على اتصال جديد وأعد الاشتراكات؛ إرسال الفحص لا يعيد اتصالًا مغلقًا.
أسباب الإغلاق
تشمل الأسباب المعرفة في البروتوكول heartbeat_timeout وduplicate_authentication وserver_shutdown وmaintenance وunauthorized وprotocol_violation. تعامل مع الإغلاق نفسه، ولا تعتمد على وصول رسالة أخيرة في كل ظرف.
الاشتراكات
موضوع الاشتراك المدعوم في هذا الإصدار هو vehicle فقط. تُرفض المواضيع الأخرى. يتكون الاشتراك من topic وidentifier، حيث المُعرّف هو UUID المركبة نفسه المستخدم في REST.
طلب الاشتراك
أرسل مصفوفة غير فارغة باسم subscriptions في المستوى الأعلى للرسالة، بعد نجاح المصادقة:
{ "type": "subscribe", "subscriptions": [ { "topic": "vehicle", "identifier": "01900000-0000-7000-8000-000000000001" } ] }
يمكن أن تحتوي الدفعة على عدة مركبات. تُدمج الأزواج المكررة من الموضوع والمُعرّف في اشتراك فعلي واحد. إذا كانت أي مركبة غير متاحة فلا يُسجّل أي اشتراك من تلك الدفعة، دون كشف ما إذا كانت المركبة غير موجودة أو غير مصرّح بها.
إقرار الاشتراك
يُعاد إقرار لكل اشتراك مقبول:
{ "type": "subscribed", "timestamp": "2026-07-05T15:37:10+02:00", "data": { "subscription": { "topic": "vehicle", "identifier": "01900000-0000-7000-8000-000000000001" } } }
ملاحظة
يمكن الاشتراك في مركبة غير متصلة.
وإذا لم تتوفر حالة محلولة للمركبة، يصل subscribed دون رسالة telemetry أولية. يظل الاشتراك فعالًا لاستقبال تحديثات لاحقة إذا توفرت.
إلغاء الاشتراك
{ "type": "unsubscribe", "subscriptions": [ { "topic": "vehicle", "identifier": "01900000-0000-7000-8000-000000000001" } ] }
إقرار الإلغاء:
{ "type": "unsubscribed", "timestamp": "2026-07-05T15:37:10+02:00", "data": { "subscription": { "topic": "vehicle", "identifier": "01900000-0000-7000-8000-000000000001" } } }
إلغاء اشتراك غير مسجل لا يغيّر الاشتراكات الأخرى. ترتبط الاشتراكات بالاتصال الحالي وتنتهي بإغلاقه. لا يُعد إقرار الاشتراك ضمانًا لوصول حالة أولية أو تدفق بلا انقطاع.
تحديثات المركبة
تخص رسائل 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 |
أوقات الرصد والاستقبال والمزامنة حسب الإتاحة |
تُرسل البيانات أثناء استمرار الاشتراك المصرّح به. تعامل مع تكرار التحديثات، والقيَم غير المتاحة، والانقطاع؛ لا يُعلن هذا المرجع ضمانًا للتسليم أو زمن الوصول أو إعادة إرسال الرسائل الفائتة.
الطوابع الزمنية
| الحقل | المعنى |
|---|---|
timestamp |
وقت إرسال رسالة Gateway |
vehicle.state.timestamps.gps |
وقت رصد الجهاز |
vehicle.state.timestamps.received |
وقت استقبال التتبع |
vehicle.state.timestamps.last_synced |
وقت المزامنة إن توفر |
رسائل الخطأ
تحتوي رسالة error على رمز قابل للمعالجة في data.error ورسالة مقروءة في data.message:
{ "type": "error", "timestamp": "2026-06-30T14:52:31+02:00", "data": { "error": "invalid_payload", "message": "Missing token." } }
رموز الخطأ
| الرمز | المعنى |
|---|---|
authentication_failed |
فشلت مصادقة بيانات الاعتماد |
already_authenticated |
جرت محاولة مصادقة اتصال موثّق |
unauthorized |
يجب إتمام المصادقة قبل العملية |
forbidden |
لا تسمح الصلاحيات بالعملية |
invalid_json |
الرسالة ليست JSON صحيحًا |
invalid_payload |
حقول الرسالة مفقودة أو غير سليمة |
unknown_message |
نوع طلب غير مدعوم |
invalid_subscription |
اشتراك غير سليم أو مركبة غير متاحة |
internal_error |
خطأ غير متوقع |
قد لا يغلق الخطأ الاتصال؛ قد يتمكن العميل من تصحيح الطلب والمتابعة. تعامل أيضًا مع إغلاق المقبس بصورة مستقلة. قد تُطبّق حدود لأحجام الرسائل ومعدلاتها وعدد الاشتراكات بحسب إعداد البيئة. لا تفترض حدودًا غير معلنة.
التوافق والتعافي
تجاهل الحقول وأنواع رسائل الخادم غير المعروفة، وتعامل مع رموز الخطأ غير المعروفة كفشل عام. حافظ على الفصل بين نجاح المصادقة ونجاح الاشتراك وإتاحة الحالة. بعد الاتصال من جديد أعد المصادقة والاشتراكات؛ لا يوجد استرجاع تلقائي للاشتراكات أو عقد معلن لإعادة بث الرسائل الفائتة.