基礎

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 接続が含まれます。階層が許可する数を超えて接続を開こうとすると、2 つの選択肢があります：

既定の動作（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 によって閉じられます。

これがあなたにとって意味すること

接続はアクティブにデータを受信中であっても、または ping を送信中であっても、2 時間後に自動的に閉じられます。
この動作は想定どおりであり、エラーやネットワークの問題を示すものではありません。
シームレスな体験を維持するには、2 時間のウィンドウごとに再接続する必要があります。

当社が対応済みです

当社の Python と TypeScript のクライアントライブラリは、いずれもこれを透過的に処理します：

サーバーが 2 時間後に接続を閉じると、クライアントが切断を検知します。
その後、自動的に再接続を試み、最小限の中断でストリームを維持します。
これにより、手動の介入なしに継続的なデータフローが保証されます。

当社のライブラリを使わずに独自のクライアントを構築している場合は、2 時間の制限を適切に処理できるよう、あなた側で再接続ロジックを実装してください。

これらの基礎 —安全に接続し、リクエストを認証し、ping/pong ハートビートで接続を維持すること— を理解すれば、finlight.me の WebSocket API を効率的にアプリケーションへ統合する道は十分に開けています。ここから、購読メッセージ、source や language などのフィルター、受信記事の処理を探求して、リッチなリアルタイム金融ニュース体験を構築できます。