切断時の対応

​

切断とは何ですか？

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

​

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

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

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

​

切断に関する一般的な errors には、次のようなものがあります:

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

{
	"title": "ConnectionException",
	"detail": "This stream is currently at the maximum allowed connection limit.",
	"connection_issue": "TooManyConnections",
	"type": "https://api.x.com/2/problems/streaming-connection"
}

​

切断を予期して再接続する

投稿をストリーミングする場合、切断が発生しうることを認識しつつ、できるだけ長く接続を維持することが目標です。エンドポイントは 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 エンドポイントは、現在、利用状況データを返しません。どれだけの投稿が配信されたかを確認するには、コード内でメータリングロジックを実装し、必要に応じて消費量を計測・一時停止できるようにします。 

ストリームのクライアント側を実装しているコードでは、受信した投稿を先入れ先出し (FIFO) キュー、もしくは類似のメモリ構造に単純に挿入します。別のプロセスやスレッドが、そのキューから投稿を取り出して解析し、保存用にコンテンツを準備します。この設計により、受信する投稿量が劇的に変化した場合でも、効率的にスケールできるサービスを実装できます。イメージとしては、HTTP 経由で無限に長いファイルをダウンロードしているようなものだと考えることができます。

​

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

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

バックオフ実装をテストする有効な方法は、不正な認証情報を使用し、再接続試行の様子を確認することです。適切に実装されていれば、429 レスポンスを一切受け取りません。

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

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

DNS の変更を処理する

クライアントプロセスが DNS の Time To Live (TTL) を順守しているかテストしてください。一部のスタックは、プロセスの存続期間中、解決済みアドレスをキャッシュし続け、指定された TTL 内での DNS 変更を反映しない場合があります。このような過度なキャッシュにより、X が IP アドレス間で負荷を移動する際に、クライアント側でサービスの中断が発生します。

User Agent

user-agent HTTP ヘッダーにクライアントのバージョンが含まれていることを確認してください。これは X 側で問題を診断する際に非常に重要です。環境上の制約で user-agent フィールドを設定できない場合は、代わりに x-user-agent ヘッダーを設定してください。