ストリーミングAPIへの接続を確立すると、非常に長い生存期間のHTTPリクエストを作成して増加する応答を処理し続けることになります。 概念的には、HTTPを使って無限の長さのファイルをダウンロードするようなものと考えてください。
ストリーミングAPIでは以下の認証方法をサポートしています:
認証タイプ | サポートしているAPI | 説明 |
---|---|---|
OAuth |
公開ストリーム |
リクエストは OAuth の仕様に従って承認されなければなりません。 |
注意: 公開ストリーミングエンドポイントにおけるBasic 認証のサポートは 2013年6月11日に 終了しました。
ストリーミング APIに接続するには、HTTPリクエストを作成し、そのリクエストで得られたストリーム結果を使用します。Our servers will hold the connection open indefinitely, barring server-side error, excessive client-side lag, network hiccups, routine server maintenance or duplicate logins.
HTTPリクエストを作成したり応答を解析したりするメソッドは、言語やフレームワークごとに異なっているので、あなたが使っているHTTPライブラリのドキュメントを参照してください。
HTTPクライアントライブラリによっては、サーバから接続が切られた後に body応答のみを返すものがあります。 こうした動きをするクライアントでは、ストリーミングAPIへのアクセスができません。データ応答を返すことができるHTTPクライアントを使用しなければなりません。 最も堅牢なHTTPクライアントライブラリであればこの機能が付いています。例えば、 Apache HttpClient はこうしたケースを処理できます。
以下の理由により、Twitter はストリーミング接続を終了することがあります:
新しくデータを受信する際には、TCPレベルでの90秒のソケットタイムアウトか、アプリケーションレベルでの90秒のタイマーを設定します。 90秒間データを受信しなかった場合は、接続を切断して、次の項目で説明するバックオフ戦略に従って直ぐに再接続してください。 ストリーミングAPIは、あなたのアプリケーションとの接続がタイムアウトするのを防ぐために30秒ごとにキープアライブのための改行を送信します。 ネットワークの輻輳、PCのCPU不足、PCのGCによる一時停止、などが発生した場合に無駄な再接続を防ぐため、少なくとも3サイクルは待つ必要があります。
確立した接続が切断されたら、すぐに再接続を試みてください。再接続が失敗した場合は、発生したエラーに従い、頻度を下げて再接続を試みてください:
接続 (churn) を何度も開いたり閉じたりすると、サーバリソースを浪費してしまいます。 接続はできるだけ安定させ長時間維持するようにしてください。
携帯端末からのモバイル接続(セルラーネットワーク)は避けてください。一般的にWiFi は大丈夫です。
ユーザーがアプリケーションを直ぐに終了させる場合に備え、ストリーミングコネクションを開くのは少し遅らせるようにしてください。
時間がたつにつれて接続品質が変化する環境でクライアントが動作する場合は、接続が劣化したこと検知できるようにしてください。 劣化を検知した場合は、接続品質が改善されるまでの間RESTを使ったポーリングに切り替えるようにしてください。
バックオフを実装しないで延々と再接続を試行するようなクライアントは、僅かな時間の接続でも速度制限をされてしまいます。 速度制限に引っかかったクライアントでは、全ての接続要求に対してHTTP 420の応答が返されます。
接続を破棄して頻繁に再接続をする(例えば、クエリパラメータを変更するなど)クライアントは、速度制限を受ける危険があります。
Twitterでは速度制限を受ける接続回数を公開してはいませんが、テストや開発のためにある程度の余裕は持っています。 時々数十回の接続を試すくらいでは制限はかかりません。しかし、HTTP 420の応答を受け取った場合は数分の間接続を停止する必要があります。 あなたのクライアントが頻繁に速度制限を受ける場合は、あなたのIPはTwiterへのアクセスを無期限のでブロックされている可能性があります。
バックオフが実装できているかをテストする良い方法は、無効な承認資格を使って再接続のテストをすることです。 実装が正しければHTTP 420の応答を受信しません
クライアントが再接続間隔の上限に達した場合、そのことがあなたに通知され、接続に影響する問題を優先して対応することができます。
あなたのクライアントのプロセスがDNS生存時間(TTL)を遵守しているかテストしてください。スタック処理によっては、プロセスの生存期間中は解決したアドレスをキャッシュし、 TTLの期限が過ぎてもDNSの変更を検知しません。 Such aggressive caching will lead to service disruptions on your client as Twitter shifts load between IP addresses.
User-Agent
HTTP ヘッダにはクライアントのバージョンを含めるようにしてください。
This will be critical in diagnosing issues on Twitter’s end.
あなたの環境でUser-Agent
フィールドを設定できない場合は、X-User-Agent
ヘッダを設定してください。
大抵のエラーコードは説明の文字列が追加で付けられて取得されます。 200よりも大きいコードを取得した場合、クライアントは再接続するまで少し待機する必要があります。上記の接続の項目を参照してください。
ステータス | テキスト | 説明 |
---|---|---|
200 | Success | 見ての通り、成功です。 |
401 | Unauthorized |
HTTP 認証は以下いずれかの原因で失敗しました:
|
403 | Forbidden | 接続しているアカウントは、このエンドポイントへのアクセス権がありません。 |
404 | Unknown |
このURLには何もありません。つまり、指定したリソースは存在しません。 |
406 | Not Acceptable |
少なくとも一つの必須パラメータが無効です。例えば、filter エンドポイントでは以下の場合にこのステータスを返します:
|
413 | Too Long |
パラメータ一覧が長すぎます。例えば、filter エンドポイントでは以下の場合にこのステータスを返します:
|
416 | Range Unacceptable |
例えば、エンドポイントでは以下の場合にこのステータスを返します:
|
420 | Rate Limited |
クライアントの接続回数が多すぎます。例えば、エンドポイントでは以下の場合にこのステータスを返します:
|
503 | Service Unavailable |
ストリーミングサーバは一時的に負荷が高い状態でした。接続の速度制限、クライアントにDNS情報がキャッシュされている可能性を考慮に入れた上で、再接続を試みてください。 |