ストリーミングdataの取得

​

ストリーミングdataを取り込むクライアントの構築

ストリーミングエンドポイントを利用する際は、使用を最適化するために考慮すべき一般的なベストプラクティスがあります。    

​

クライアント設計

filter stream エンドポイントでソリューションを構築する際は、次の機能を備えたクライアントが必要です。

1. filter stream エンドポイントへの HTTPS ストリーミング接続を確立する。
2. ストリームのルールを追加・削除するために、filter stream rules エンドポイントへ POST リクエストを非同期で送信する。
3. 低ボリューム時の処理 — ストリーミング接続を維持し、Post オブジェクトおよびキープアライブ信号を検出する。
4. 高ボリューム時の処理 — 非同期処理でストリーム取り込みと後続処理を分離し、クライアント側バッファを定期的にフラッシュする。
5. クライアント側での使用量トラッキングを管理する。
6. ストリーム切断を検出し、評価のうえ自動再接続する。  

​

ストリーミングエンドポイントへの接続

X API v2 のストリーミングエンドポイントに接続するということは、非常に長寿命の HTTP リクエストを確立し、レスポンスを逐次的に解析することを指します。概念的には、HTTP 経由で終わりのないファイルをダウンロードしているようなものと考えられます。接続が確立されると、接続が開いているかぎり、X のサーバーはその接続を通じて Post イベントを配信します。  

​

data の消費

JSON オブジェクトの各フィールドには順序がなく、あらゆる状況で必ずしも全てのフィールドが存在するわけではありません。同様に、個々のアクティビティは並び替えられた順序で配信されず、重複メッセージが含まれる場合があります。時間の経過とともに新しいメッセージタイプが追加され、ストリーム経由で送信される可能性がある点に留意してください。

したがって、クライアントは次を許容する必要があります:

• 任意の順序で現れるフィールド
• 予期しないフィールドや欠落しているフィールド
• 並び順が保証されない Post
• 重複メッセージ
• いつでもストリームに流れてくる新たな任意のメッセージタイプ

関連する Post の data および要求した fields パラメータに加えて、ストリーム接続では次の種類のメッセージが配信される場合があります。このリストは網羅的ではない可能性がある点に注意してください。ストリームに追加のオブジェクトが導入される場合があります。パーサーが予期しないメッセージ形式にも耐性を持つようにしてください。  

​

バッファリング 

ストリーミングエンドポイントは、利用可能になり次第すぐにdataを送信するため、多くの場合で高トラフィックになります。X サーバーが直ちに新しいdataをストリームへ書き込めない場合（たとえばクライアントの読み取りが十分に速くないとき。詳しくは切断の処理を参照）、クライアントが追いつけるようにサーバー側でコンテンツをバッファします。ただし、このバッファが満杯になると、接続を切断するための強制切断が行われ、バッファされていたPostは破棄され、再送されません。詳細は以下を参照してください。

アプリが遅延しているタイミングを特定する一つの方法は、受信したPostのタイムスタンプを現在時刻と比較し、経時的に追跡することです。

パブリックインターネット上の潜在的なレイテンシーや断続的な不具合により、ストリームの滞留を完全に排除することはできませんが、アプリを適切に構成すれば大部分は防止できます。滞留の発生を最小限に抑えるには:

• クライアントがストリームを十分な速度で読み取っていることを確認してください。通常、読み取り中に実際の処理は行わないでください。ストリームを読み取り、処理は別スレッド/プロセス/データストアに引き渡して非同期で実行します。
• データセンターに、大容量の継続的なdataおよび大幅なスパイク（例: 通常の5～10倍）に対応できる十分な受信帯域幅があることを確認してください。filtered streamの場合、発生するボリュームとそれに伴って必要となる帯域幅は、あなたのルールがどのPostにマッチするかに完全に依存します。  

​

使用状況の追跡とルール管理

各開発者が自分のストリームにおける「通常」のデータ量をどう想定するかは異なるため、特定の増減率や期間についての一般的な推奨値は提示していません。

ストリームのデータ量に予期しない変動がないか監視することを検討してください。データ量の減少は、ストリームの切断とは異なる問題を示している可能性があります。このような場合でも、ストリームは引き続きキープアライブ信号を受信し、おそらく新しいアクティビティデータも一部受信しています。ただし、Posts の数が大幅に減っている場合は、アプリケーションやネットワークで受信データ量の低下を引き起こしている要因がないか調査し、関連するお知らせがないか status page を確認してください。

このような監視を実現するには、一定時間内に想定される新規 Posts の数を追跡します。ストリームのデータ量が設定したしきい値を大きく下回り、所定の期間内に回復しない場合は、アラートや通知を発報する必要があります。特にフィルタ済みストリームのルールを変更している最中や、Post アクティビティがスパイクするイベントが発生した場合には、データ量の急増についても監視するとよいでしょう。

フィルタ済みストリーム経由で配信される Posts は、月間の合計 Post 量に算入されます。最適化のために消費量を把握・調整してください。ボリュームが高い場合は、必要に応じて各ルールに sample: 演算子を追加し、100% の一致から sample:50 や sample:25 に減らすことを検討してください。

また、事前に設定したしきい値を超えた際にチームへアラートが届く仕組みをアプリ内に実装することを推奨します。さらに、過剰なデータを取り込んでいるルールの自動削除や、極端な状況ではストリームから完全に切断するなどの対策も検討してください。  

​

システムメッセージへの応答

キープアライブ信号 少なくとも20秒ごとに、ストリームは開いた接続を通じて、\r\n のキャリッジリターン（ハートビート）形式でキープアライブ信号を送信し、クライアントのタイムアウトを防ぎます。クライアントアプリケーションは、ストリーム内に含まれる \r\n 文字を許容する必要があります。

クライアントがHTTPライブラリで読み取りタイムアウトを適切に実装していれば、この期間内にデータが読み取られない場合、HTTPプロトコルおよびHTTPライブラリがイベントを発生させることに依拠でき、\r\n 文字を明示的に監視する必要はありません。

このイベントは、使用するHTTPライブラリにより、例外の送出やその他のイベントであるのが一般的です。これらのタイムアウトを検出するために、HTTPメソッドをエラー／イベントハンドラーでラップすることを強く推奨します。タイムアウト時には、アプリケーションは再接続を試みてください。

エラーメッセージ v2のストリーミングエンドポイントは、ストリーム内でエラーメッセージを配信する場合があります。以下に、これらのメッセージの基本形式といくつかの例を示します。配信されるメッセージは変更され、新しいメッセージが導入される可能性がある点にご留意ください。クライアントアプリケーションは、変化するシステムメッセージのペイロードに対して堅牢である必要があります。

エラーメッセージには、問題の解決方法を説明するドキュメントへのリンクが含まれます。

メッセージ形式:

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

バッファ満杯による強制切断を示すエラーメッセージは、その強制切断を招いた滞留のせいで配信自体が妨げられ、クライアントに届かない場合があります。したがって、アプリは再接続の開始をこれらのメッセージに依存しないようにしてください。