ストリーミングデータの取得

​

ストリーミングデータを受信するクライアントの構築

ストリーミングのendpointを使用する場合、利用を最適化するために考慮すべき一般的なベストプラクティスがあります。    

​

クライアント設計

filter stream endpoint を用いてソリューションを構築する際は、次のことが可能なクライアントが必要です。

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

​

streaming endpoint への接続

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

​

data の消費

JSON オブジェクトの各 fields には順序がなく、あらゆる状況で全ての fields が存在するとは限りません。同様に、個別のアクティビティはソートされた順序で配信されず、重複メッセージに遭遇する場合があります。時間の経過とともに、新しいメッセージ type が追加され、stream を通じて送信される可能性があることに留意してください。

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

• 任意の順序で現れる fields
• 予期しない fields や欠落している fields
• ソートされていない Posts
• 重複メッセージ
• 任意のタイミングで stream に流れてくる新たな任意のメッセージ type

関連する Post の data および要求した fields パラメータに加えて、stream 接続では以下の種類のメッセージが配信される場合があります。この一覧は網羅的ではない可能性があり、stream に追加のオブジェクトが導入されることがあります。予期しないメッセージ形式に対しても堅牢なパーサーにしてください。  

​

バッファリング 

streaming endpoint は、利用可能になり次第ただちに data を送信するため、状況によっては非常に大量のデータになることがあります。クライアントの読み取りが十分に速くないなどの理由で（詳細は切断の処理を参照）、X サーバーが即座に stream に新しい data を書き込めない場合、クライアントが追いつけるようサーバー側でコンテンツをバッファリングします。ただし、このバッファが満杯になると、接続を切断するための強制切断が行われ、バッファされていた Posts は破棄され再送されません。詳細は以下を参照してください。

App が処理に追いついていないタイミングを把握する一つの方法は、受信している Posts のタイムスタンプを現在時刻と比較し、その差分を継続的に追跡することです。

パブリックインターネット上の遅延や一時的な障害により、stream の滞留を完全に排除することはできませんが、App を適切に構成すれば大部分は回避できます。滞留の発生を最小限に抑えるには:

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

​

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

開発者ごとに自身のstreamで「通常」とみなすデータ量の水準は異なるため、特定の増減率や期間についての一般的な推奨値は提示していません。

streamのデータ量に予期しない変動がないか監視することを検討してください。データ量の減少は、streamの切断とは異なる問題の兆候である場合があります。このような状況でも、streamは引き続きキープアライブ信号を受信し、おそらく新たなアクティビティデータも受け取っています。しかし、Postの数が著しく減少している場合は、アプリケーションまたはネットワークへの受信データ量の減少を招く要因がないかを調査し、関連する通知がないかステータスページも確認してください。

このような監視を行うには、一定時間内に想定される新規Postの数を追跡するとよいでしょう。streamのデータ量が設定したしきい値を大きく下回り、かつ所定の期間内に回復しない場合は、アラートや通知を発報するようにします。また、特にFiltered streamでルールを変更している最中や、Postアクティビティが急増するイベントが発生した場合には、データ量の大幅な増加についても監視することを検討してください。

Filtered streamで配信されるPostは月間の総Postボリュームに算入されるため、最適化のために消費量を追跡し、適宜調整してください。ボリュームが高い場合は、必要に応じて各ルールにsample:演算子を追加し、100%マッチからsample:50やsample:25に減らすことを検討してください。

さらに、事前に設定したしきい値を超えた場合にチームへ通知する仕組みをApp内に実装することを推奨します。場合によっては、過剰なデータを取り込むルールの自動削除や、極端な状況ではstreamから完全に切断するなどの対策も検討してください。  

​

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

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

クライアントが使用する HTTP ライブラリで読み取りタイムアウトを適切に実装している場合、App は HTTP プロトコルおよび HTTP ライブラリに任せて、指定期間内に data が読み取られない場合にイベントが発生するようにでき、\r\n 文字を明示的に監視する必要はありません。

このイベントは通常、例外の送出、または使用する HTTP ライブラリに応じた他のイベントになります。これらのタイムアウトを検出するため、HTTP メソッドをエラー／イベントハンドラーでラップすることを強く推奨します。タイムアウトが発生した場合、アプリケーションは再接続を試みる必要があります。

エラーメッセージ v2 のストリーミング endpoint では、stream 内でエラーメッセージが配信されることがあります。以下に、これらのメッセージの基本形式といくつかの例を示します。配信されるメッセージは変更され、新しいメッセージが追加される可能性がある点に注意してください。クライアントアプリケーションは、変更されうるシステムメッセージのペイロードに対して許容的である必要があります。

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

メッセージ形式:

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

バッファが満杯になったことによる強制切断を示すエラーメッセージは、強制切断の原因となったバックアップによって送達が妨げられ、クライアントに届かない場合があります。したがって、再接続の開始をこれらのメッセージに依存しないように、Appを設計してください。