الأساسيات

توفّر واجهة finlight.me WebSocket API تدفّقًا مستمرًّا وفي الوقت الفعلي لمقالات الأخبار المالية، يُسلَّم لحظة توفّرها. وعلى عكس نقاط نهاية REST التقليدية التي تتطلّب استطلاعًا دوريًا، يتيح لك نهج WebSocket الحفاظ على اتصال دائم واستقبال التحديثات دون تكرار الطلبات. وهذا يؤدّي إلى تسليم بيانات أسرع، واستخدام فعّال للموارد، وتجربة مستخدم محسّنة.

في هذا الدليل، ستتعلّم الخطوات الأساسية للاتصال والمصادقة وإبقاء الاتصال حيًّا مع واجهة finlight.me WebSocket API.

ملاحظة: لاستخدام ميزات WebSocket، تحتاج إلى اشتراك مدفوع. لا تتضمّن الباقة المجانية ميزة WebSocket. تحتاج على الأقل إلى اشتراك يتضمّن ميزات WebSocket.

الاتصال بـ WebSocket

لبدء استقبال تحديثات الأخبار المالية في الوقت الفعلي، عليك إنشاء اتصال WebSocket بخادم finlight.me. يبقى هذا الاتصال مفتوحًا حتى تغلقه أنت أو الخادم. وبمجرّد إنشاء الاتصال، يمكنك البدء في الاشتراك في تدفّقات المقالات واستقبال الرسائل عند نشر مقالات جديدة.

ملاحظة: تقطع واجهة WebSocket API الاتصال تقنيًّا بعد ساعتين. ومع ذلك، تتولّى مكتبة العميل لدينا بلغة TypeScript أو Python التعامل مع ذلك تلقائيًا عبر إعادة الاتصال نيابةً عنك. ويمكنك أيضًا إعادة الاتصال يدويًا عند الحاجة.

نقطة نهاية WebSocket:
wss://wss.finlight.me

نقاط أساسية:

بيانات في الوقت الفعلي: يتيح بروتوكول WebSocket اتصالًا ثنائي الاتجاه (full-duplex)، ما يعني أن البيانات يمكن أن تتدفّق من الخادم وإليه في الوقت الفعلي.
نموذج النشر/الاشتراك: بمجرّد الاتصال، يمكنك تحديد استعلامك (مثل query: "nvidia")، وسيرسل الخادم فورًا أحدث مقال مطابق، يليه أي مقالات جديدة فور توفّرها.
لا استطلاع متكرّر: بدلًا من استطلاع الخادم باستمرار بحثًا عن بيانات جديدة، يدفع الخادم المقالات الجديدة إليك، مما يقلّل العبء والكمون.

إدارة حدود الاتصال باستخدام Takeover

تتضمّن كل فئة اشتراك عددًا ثابتًا من اتصالات WebSocket المتوازية. إذا حاولت فتح اتصالات أكثر مما تسمح به فئتك، فلديك خياران:

السلوك الافتراضي (takeover: false): سيُرفَض محاولة الاتصال الجديدة، وستتلقّى خطأً يشير إلى بلوغك حد الاتصالات.
وضع takeover (takeover: true): سيُغلَق أقدم اتصال قائم تلقائيًا، وسيحلّ الاتصال الجديد محلّه.

مثال مع تفعيل Takeover:

const { FinlightApi } = require('finlight-client')

const client = new FinlightApi(
  {
    apiKey: 'YOUR_API_KEY',
    logger: console,
    logLevel: 'info',
  },
  {
    // WebSocket-specific options
    takeover: true, // Automatically close oldest connection when limit is reached
  },
)

client.websocket.connect(
  { query: 'nvidia', language: 'en' },
  (article) => {
    console.log('New article received:', article)
  },
)

متى تستخدم Takeover:

التطوير/الاختبار: مفيد عندما تعيد تشغيل تطبيقك بشكل متكرّر ولا ترغب في إغلاق الاتصالات القائمة يدويًا.
نسخة نشطة واحدة: عندما ترغب في ضمان أن تكون نسخة الاتصال الأحدث وحدها نشطة.
الترحيل التلقائي: عند الترحيل بين الخوادم أو إعادة نشر تطبيقك.

متى تتجنّب Takeover:

بيئات الإنتاج: حيث ترغب في تحكّم صريح في إدارة الاتصالات.
اتصالات مشروعة متعدّدة: عندما تشغّل عمدًا عدّة نُسخ اتصال لأغراض مختلفة.
التصحيح: عندما تحتاج إلى فهم سبب بلوغ حدود الاتصال.

المصادقة

لضمان وصول آمن ومُصرَّح به، يجب مصادقة جميع اتصالات WebSocket بـ finlight.me باستخدام مفتاح API الخاص بك. يتحقّق هذا المفتاح من امتلاكك الأذونات وحقوق الوصول اللازمة لاستقبال المحتوى في الوقت الفعلي.

ضمِّن مفتاح API في ترويسات طلب مصافحة WebSocket الأولي. تتيح معظم مكتبات عميل WebSocket تحديد ترويسات إضافية عند إنشاء الاتصال.

الترويسة:
x-api-key: YOUR_API_KEY

كيفية الحصول على مفتاح API:

سجّل في لوحة تحكم finlight.
انتقل إلى قسم API Keys لإنشاء مفاتيحك وإدارتها.

مقتطف الكود (مثال Node.js):

const WebSocket = require('ws')

const socket = new WebSocket('wss://wss.finlight.me', {
  headers: {
    'x-api-key': 'YOUR_API_KEY',
  },
})

socket.on('open', () => {
  console.log('Connected to finlight.me WebSocket!')
  // You can now send a subscription request to start receiving articles
})

socket.on('error', (err) => {
  console.error('WebSocket error:', err)
})

إبقاء الاتصال حيًّا (آلية Ping/Pong)

يمكن أن تبقى اتصالات WebSocket مفتوحة لفترات طويلة، لكن ظروف الشبكة والوكلاء وجدران الحماية قد تُسقِط الاتصالات غير النشطة. وللتخفيف من ذلك، يدعم finlight.me آلية إبقاء حيّ ping/pong.

كيف تعمل:

يرسل العميل ping: على فترات منتظمة (مثل كل 8 دقائق)، يرسل العميل رسالة ping إلى الخادم.
يردّ الخادم بـ pong: يردّ الخادم برسالة pong، مشيرًا إلى أن الاتصال لا يزال حيًّا.
معالجة عدم الاستجابة: إذا لم يتلقَّ العميل pong خلال فترة معيّنة، يمكنه افتراض فقدان الاتصال ومحاولة إعادة الاتصال.

تضمن نبضة القلب البسيطة هذه أن يعرف كلٌّ من العميل والخادم أن الاتصال لا يزال نشطًا، وأن بإمكانهما تبادل البيانات دون انقطاع.

مثال (Node.js باستخدام setInterval):

socket.on('open', () => {
  console.log('Connected to finlight WebSocket')

  // Send a ping every 8 minutes
  const pingInterval = setInterval(
    () => {
      if (socket.readyState === WebSocket.OPEN) {
        console.log('Sending ping...')
        socket.send(JSON.stringify({ action: 'ping' }))
      }
    },
    8 * 60 * 1000,
  ) // 8 minutes in milliseconds

  socket.on('message', (data) => {
    const message = JSON.parse(data)
    if (message.action === 'pong') {
      console.log('Received pong, connection is alive.')
    } else {
      // Handle other messages, such as incoming articles
      console.log('Received message:', message)
    }
  })

  socket.on('close', () => {
    clearInterval(pingInterval)
    console.log('WebSocket connection closed.')
  })
})

لماذا يُعدّ Ping/Pong مهمًّا؟

الاتصالات طويلة الأمد: تعتمد تطبيقات كثيرة على اتصالات WebSocket عاملة باستمرار. ومن دون آلية إبقاء حيّ، قد تفشل هذه الاتصالات بصمت.
موثوقية الشبكة: تضمن فحوص ping/pong ألّا تترك مشكلات الشبكة العابرة العميلَ غير مدرك لاتصال منقطع.
كفاءة الموارد: يساعد الاكتشاف السريع للاتصال المفقود العميلَ على توفير الموارد بعدم الانتظار إلى ما لا نهاية لبيانات جديدة لن تصل أبدًا.

حدود مدة الاتصال

تعمل بنية WebSocket الخاصة بـ finlight.me على AWS API Gateway، الذي يفرض حدًّا أقصى صارمًا لمدة الاتصال يبلغ ساعتين لكل جلسة WebSocket. وهذا حدّ على مستوى المنصّة — وبغضّ النظر عن النشاط، تُغلِق AWS جميع الاتصالات بعد ساعتين.

ماذا يعني هذا لك

سيُغلَق اتصالك تلقائيًا بعد ساعتين، حتى لو كان يستقبل البيانات بنشاط أو يرسل ping.
هذا السلوك متوقّع ولا يشير إلى خطأ أو مشكلة في الشبكة.
للحفاظ على تجربة سلسة، عليك إعادة الاتصال بعد كل نافذة مدّتها ساعتان.

نحن نهتمّ بذلك نيابةً عنك

تتعامل كلتا مكتبتَي العميل لدينا بلغتي Python وTypeScript مع هذا بشفافية:

عندما يغلق الخادم الاتصال بعد ساعتين، يكتشف العميل قطع الاتصال.
ثم يحاول إعادة الاتصال تلقائيًا، محافظًا على تدفّقك بأدنى انقطاع.
وهذا يضمن تدفّق بيانات مستمرًّا دون تدخّل يدوي.

إذا كنت تبني عميلك الخاص دون استخدام مكتباتنا، فاحرص على تنفيذ منطق إعادة الاتصال من جانبك للتعامل مع حدّ الساعتين بسلاسة.

بفهمك لهذه الأساسيات —الاتصال الآمن، ومصادقة طلباتك، والحفاظ على الاتصال بنبضة ping/pong— تكون في طريقك الصحيح لدمج واجهة finlight.me WebSocket API بكفاءة في تطبيقك. ومن هنا، يمكنك استكشاف رسائل الاشتراك، ومرشّحات مثل source أو language، ومعالجة المقالات الواردة لبناء تجارب أخبار مالية غنية في الوقت الفعلي.