切断時の対応

​

切断とは何ですか？

ストリーミング API への接続を確立するとは、非常に長時間にわたる HTTPS リクエストを発行し、レスポンスを逐次的に解析することを指します。filtered stream エンドポイントに接続する場合は、HTTPS リクエストを送信し、実用上可能な限り長く結果のストリームを読み取り続けてください。サーバー側のエラー、クライアント側の過度な遅延、ネットワークの問題、定期的なサーバーメンテナンス、または重複ログインがない限り、当社のサーバーは接続を無期限に維持します。ストリーミングエンドポイントへの接続では切断が発生する可能性が高く、その発生を前提とし、再接続ロジックを実装しておく必要があります。  

​

ストリーミング接続が切断される理由

ストリームはさまざまな理由で切断される可能性があります。失敗の原因を把握するため、ストリームから返されるエラーメッセージを確認してください。切断の主な理由は次のとおりです。

• 認証エラー（誤ったトークンの使用や不適切な認証方式の使用など）。
• X 側でストリーミングサーバーが再起動された場合。これは通常、コードのデプロイに関連しており、想定の上で設計に織り込む必要があります。
• クライアントがストリームで配信される Post の量に追いついていない、または読み取りが遅すぎる場合。すべてのストリーミング接続にはクライアントに送信するメッセージのキューがあり、このキューが時間の経過とともに大きくなりすぎると、接続は閉じられます。
• アカウントが日次／月次の Post のクォータを超過した場合。
• 冗長なアクティブ接続が多すぎる場合。
• クライアントが突然読み取りを停止した場合。ストリームから読み取られる Post の速度が急激に低下すると、接続は閉じられます。
• サーバーとクライアント間のネットワーク上の問題の可能性。
• 一時的なサーバー側の問題、計画メンテナンスやアップデート。（ステータスページを確認してください）  

​

一般的な切断時のエラーには、次のようなものがあります:

	"errors": [{
		"title": "operational-disconnect",
		"disconnect_type": "UpstreamOperationalDisconnect",
		"detail": "このストリームは運用上の理由により上流側で切断されました。",
		"type": "https://api.x.com/2/problems/operational-disconnect"
	}]
}

{
	"title": "ConnectionException",
	"detail": "このストリームは現在、許可されている接続数の上限に達しています。",
	"connection_issue": "TooManyConnections",
	"type": "https://api.x.com/2/problems/streaming-connection"
}

​

切断を見越した対処と再接続

Post をストリーミングする際は、切断が起こり得ることを踏まえつつ、可能な限り長時間の接続維持を目指します。エンドポイントは20秒間隔のキープアライブのハートビート（改行文字として現れます）を送信します。この信号を用いて切断の兆候を検知してください。

1. 新規コンテンツとハートビートの受信が止まったことをコードで検出する必要があります。
2. その場合は、再接続ロジックを起動してください。一部のクライアントや言語では読み取りタイムアウトを指定でき、20秒に設定できます。
3. サービスはこれらの切断を検知し、できるだけ早く再接続する必要があります。

確立済みの接続が切れたら、直ちに再接続を試みてください。再接続に失敗した場合は、発生したエラーの種類に応じて再接続の試行間隔を延ばしてください。

• TCP/IP レベルのネットワークエラーは線形バックオフにします。これらの問題は一般的に一時的で、すぐに解消される傾向があります。試行のたびに待機時間を250msずつ増やし、最大16秒までとします。
• 再接続が適切な HTTP エラーは指数バックオフにします。最初は5秒待機し、試行のたびに倍にして最大320秒までとします。
• HTTP 429 エラー（Rate limit exceeded）は指数バックオフにします。最初は1分待機し、試行のたびに倍にします。HTTP 429 を受信するたびに、アカウントのレート制限が解除されるまでに待機すべき時間が増える点に注意してください。  

​

失われたデータの復旧

切断が発生した場合、取り逃した可能性のあるすべてのデータを確実に受信するために使えるいくつかの方法があります。見逃したデータを復旧するための主要な手順は、データの復旧に関する統合ガイドで説明しています。   

​

レート制限と使用状況

接続制限を確認するには、レスポンスに3つのヘッダーが含まれます。これは、ルールエンドポイントを何回使用できるか、ストリーミングエンドポイントで許可される再接続試行回数がどの程度かを把握するのに役立ちます。

• x-rate-limit-limit は、15分間のウィンドウ内にクライアントが実行できる割り当てリクエスト数を示します。

• x-rate-limit-remaining は、15分間のウィンドウ内でこれまでに行われたリクエスト数を示します。

• x-rate-limit-reset は、15分間のウィンドウが再開され、その時点で x-rate-limit-remaining が0にリセットされる時刻を示す UNIX タイムスタンプです。

filter stream エンドポイントは現在、使用状況の data を報告しません。配信された Post の件数を確認するには、必要に応じて消費量を計測し一時停止できるよう、コード側でメータリングのロジックを実装してください。

ストリームのクライアント側をホストするコードは、受信した Post を先入れ先出し（FIFO）キューまたは同様のメモリ構造に挿入し、別のプロセス／スレッドがそのキューから Post を取り出して解析し、保存用に準備するようにします。この設計により、受信する Post のボリュームが劇的に変化した場合でも、効率的にスケールできるサービスを実装できます。概念的には、HTTP 経由で無限に長いファイルをダウンロードしているイメージです。

​

再接続のベストプラクティス

バックオフ戦略をテストする

バックオフ実装を検証する良い方法は、無効な認証情報を使って再接続試行の挙動を確認することです。適切に実装されていれば、429 応答は発生しません。

複数回の再接続に対してアラートを出す

クライアントが再接続間隔の上限しきい値に達した場合は、接続に影響する問題を優先度付けして対処できるよう、通知を送る必要があります。

DNS 変更に対応する

クライアントのプロセスが DNS の Time To Live (TTL) を遵守することを確認してください。一部のスタックは、プロセスの存続期間中に解決済みアドレスをキャッシュし、規定の TTL 内に発生した DNS 変更を反映しない場合があります。こうした過度なキャッシュは、X が IP アドレス間で負荷分散を行う際に、クライアント側でサービス中断を引き起こす原因になります。

User Agent

user-agent HTTP ヘッダーにクライアントのバージョンを含めてください。これは X 側での問題診断に不可欠です。環境の制約で user-agent フィールドを設定できない場合は、x-user-agent ヘッダーを設定してください。