मूल बातें

finlight.me WebSocket API वित्तीय समाचार लेखों की एक निरंतर, रीयल-टाइम स्ट्रीम प्रदान करता है, जो उनके उपलब्ध होते ही डिलीवर की जाती है। पारंपरिक REST एंडपॉइंट के विपरीत, जिन्हें समय-समय पर पोलिंग की आवश्यकता होती है, WebSocket दृष्टिकोण आपको एक स्थायी कनेक्शन बनाए रखने और बार-बार अनुरोध किए बिना अपडेट प्राप्त करने देता है। इससे तेज़ डेटा डिलीवरी, कुशल संसाधन उपयोग और बेहतर उपयोगकर्ता अनुभव मिलता है।

इस गाइड में, आप finlight.me WebSocket API के साथ कनेक्ट करने, प्रमाणित करने और कनेक्शन को बनाए रखने के बुनियादी चरण सीखेंगे।

ध्यान दें: WebSocket सुविधाओं का उपयोग करने के लिए, आपके पास एक सशुल्क सब्सक्रिप्शन होना चाहिए। मुफ़्त टियर में WebSocket सुविधा शामिल नहीं है। आपको कम से कम WebSocket सुविधाओं वाला सब्सक्रिप्शन चाहिए।

WebSocket से कनेक्ट करना

रीयल-टाइम वित्तीय समाचार अपडेट प्राप्त करना शुरू करने के लिए, आपको finlight.me सर्वर से एक WebSocket कनेक्शन स्थापित करना होगा। यह कनेक्शन तब तक खुला रहता है जब तक आप या सर्वर इसे बंद न करें। जैसे ही कनेक्शन स्थापित होता है, आप लेख स्ट्रीम की सदस्यता लेना शुरू कर सकते हैं और नए लेख प्रकाशित होते ही संदेश प्राप्त कर सकते हैं।

ध्यान दें: WebSocket API तकनीकी रूप से 2 घंटे बाद डिस्कनेक्ट हो जाता है। हालाँकि, हमारी TypeScript या Python क्लाइंट लाइब्रेरी आपके लिए पुनः कनेक्ट करके इसे स्वतः संभालती है। आवश्यकता होने पर आप मैन्युअल रूप से भी पुनः कनेक्ट कर सकते हैं।

WebSocket एंडपॉइंट:
wss://wss.finlight.me

मुख्य बिंदु:

रीयल-टाइम डेटा: WebSocket प्रोटोकॉल एक फ़ुल-डुप्लेक्स कनेक्शन सक्षम करता है, जिसका अर्थ है कि डेटा सर्वर से और सर्वर तक रीयल-टाइम में प्रवाहित हो सकता है।
पब्लिश/सब्सक्राइब मॉडल: कनेक्ट होने पर, आप अपनी क्वेरी निर्दिष्ट कर सकते हैं (जैसे, 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 से कब बचें:

उत्पादन वातावरण: जहाँ आप कनेक्शन प्रबंधन पर स्पष्ट नियंत्रण चाहते हैं।
कई वैध कनेक्शन: जब आप जानबूझकर विभिन्न उद्देश्यों के लिए कई कनेक्शन इंस्टेंस चलाते हैं।
डिबगिंग: जब आपको यह समझने की आवश्यकता हो कि कनेक्शन सीमाएँ क्यों पहुँच रही हैं।

प्रमाणीकरण

सुरक्षित और अधिकृत पहुँच सुनिश्चित करने के लिए, finlight.me से सभी WebSocket कनेक्शनों को आपकी API कुंजी का उपयोग करके प्रमाणित किया जाना चाहिए। यह कुंजी सत्यापित करती है कि आपके पास रीयल-टाइम कंटेंट प्राप्त करने के लिए आवश्यक अनुमतियाँ और एक्सेस अधिकार हैं।

प्रारंभिक WebSocket हैंडशेक अनुरोध हेडर में अपनी API कुंजी शामिल करें। अधिकांश 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 नहीं मिलता, तो वह मान सकता है कि कनेक्शन खो गया है और पुनः कनेक्ट करने का प्रयास कर सकता है।

यह सरल हार्टबीट सुनिश्चित करता है कि क्लाइंट और सर्वर दोनों जानें कि कनेक्शन अभी भी सक्रिय है और बिना किसी रुकावट के डेटा का आदान-प्रदान कर सकते हैं।

उदाहरण (setInterval के साथ Node.js):

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 जाँच सुनिश्चित करती है कि अस्थायी नेटवर्क समस्याएँ क्लाइंट को टूटे हुए कनेक्शन से अनजान न छोड़ें।
संसाधन दक्षता: खोए हुए कनेक्शन का शीघ्र पता लगाना क्लाइंट को कभी न आने वाले नए डेटा की अनिश्चितकाल तक प्रतीक्षा न करके संसाधन बचाने में मदद करता है।

कनेक्शन अवधि सीमाएँ

finlight.me का WebSocket अवसंरचना AWS API Gateway द्वारा संचालित है, जो प्रति WebSocket सत्र 2 घंटे की एक कठोर अधिकतम कनेक्शन अवधि लागू करता है। यह एक प्लेटफ़ॉर्म-स्तरीय सीमा है — गतिविधि की परवाह किए बिना, सभी कनेक्शन 2 घंटे बाद AWS द्वारा बंद कर दिए जाते हैं।

इसका आपके लिए क्या अर्थ है

आपका कनेक्शन 2 घंटे बाद स्वतः बंद हो जाएगा, भले ही वह सक्रिय रूप से डेटा प्राप्त कर रहा हो या ping भेज रहा हो।
यह व्यवहार अपेक्षित है और किसी त्रुटि या नेटवर्क समस्या का संकेत नहीं देता।
एक निर्बाध अनुभव बनाए रखने के लिए, आपको प्रत्येक 2-घंटे की विंडो के बाद पुनः कनेक्ट करना होगा।

हमने इसका ध्यान रखा है

हमारी Python और TypeScript दोनों क्लाइंट लाइब्रेरी इसे पारदर्शी रूप से संभालती हैं:

जब सर्वर 2 घंटे बाद कनेक्शन बंद करता है, तो क्लाइंट डिस्कनेक्ट का पता लगाता है।
फिर यह स्वतः पुनः कनेक्ट करने का प्रयास करता है, न्यूनतम रुकावट के साथ आपकी स्ट्रीम को बनाए रखते हुए।
यह मैन्युअल हस्तक्षेप के बिना निरंतर डेटा प्रवाह सुनिश्चित करता है।

यदि आप हमारी लाइब्रेरी का उपयोग किए बिना अपना स्वयं का क्लाइंट बना रहे हैं, तो 2-घंटे की सीमा को सुचारू रूप से संभालने के लिए अपनी ओर से पुनः कनेक्ट लॉजिक अवश्य लागू करें।

इन मूल बातों को समझकर — सुरक्षित रूप से कनेक्ट करना, अपने अनुरोधों को प्रमाणित करना, और ping/pong हार्टबीट के साथ कनेक्शन बनाए रखना — आप finlight.me के WebSocket API को अपने एप्लिकेशन में कुशलता से एकीकृत करने की राह पर अच्छी तरह आगे हैं। यहाँ से, आप सब्सक्रिप्शन संदेशों, source या language जैसे फ़िल्टरों, और आने वाले लेखों को संभालने का अन्वेषण कर सकते हैं ताकि समृद्ध, रीयल-टाइम वित्तीय समाचार अनुभव बना सकें।