サイトのトップへ戻る

Twitter 開発者 ドキュメント日本語訳

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

概要

ストリーミング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 はストリーミング接続を終了することがあります:

  • クライアントが同一の資格情報を使って非常に多くのコネクションを確立した。これが起こると、最も古い接続が切断されます。 つまり、同一資格情報を使った二つのクライアントで、平行して再接続しないよう注意する必要があります。さもないと各クライアントが相手を切断してしまいます。
  • クライアントが突然データの読み込みを停止した。ストリームからツイートを読み込む速度が突然低下した場合、その接続は終了されます。
  • クライアントが非常にゆっくりとデータを読み込む。全てのストリーミング接続は、クライアントに送信されるメッセージキューによって支えされています。 時間の経過とともにこのキューが大きくなりすぎると、接続は終了されます。
  • ストリーミングサーバが再起動された。これは通常コードの追加に関連して行われ、頻繁にはありません。
  • Twitterのネットワーク設定が変わった。こうしたイベントは非常に稀で、例えばロードバランサーの再起動やネットワークの再構成などがあります。


速度低下

新しくデータを受信する際には、TCPレベルでの90秒のソケットタイムアウトか、アプリケーションレベルでの90秒のタイマーを設定します。 90秒間データを受信しなかった場合は、接続を切断して、次の項目で説明するバックオフ戦略に従って直ぐに再接続してください。 ストリーミングAPIは、あなたのアプリケーションとの接続がタイムアウトするのを防ぐために30秒ごとにキープアライブのための改行を送信します。 ネットワークの輻輳、PCのCPU不足、PCのGCによる一時停止、などが発生した場合に無駄な再接続を防ぐため、少なくとも3サイクルは待つ必要があります。



再接続する

確立した接続が切断されたら、すぐに再接続を試みてください。再接続が失敗した場合は、発生したエラーに従い、頻度を下げて再接続を試みてください:

  • TCP/IP レベルのネットワークエラーの場合は、単純加算バックオフを使います。 こうした問題は通常一時的なもので、直ぐに改善する傾向にあります。成功するまで間隔を250ミリ秒ずつ増やしながら再接続し、最大16秒間隔になるまで繰り返します。
  • HTTP エラーの場合は、指数関数バックオフを使うのが適しています。5秒待って再接続をし、それでも失敗する場合は間隔を二倍にしながら再接続を続け、最大320秒間隔になるまで繰り返します。
  • HTTP 420 エラーの場合は、指数関数バックオフを使用します。1分待って再接続をし、それでも失敗する場合は間隔を二倍にしながら再接続を続けます。 Note that every HTTP 420 received increases the time you must wait until rate limiting will no longer will be in effect for your account.


Connection churn

接続 (churn) を何度も開いたり閉じたりすると、サーバリソースを浪費してしまいます。 接続はできるだけ安定させ長時間維持するようにしてください。

携帯端末からのモバイル接続(セルラーネットワーク)は避けてください。一般的にWiFi は大丈夫です。

ユーザーがアプリケーションを直ぐに終了させる場合に備え、ストリーミングコネクションを開くのは少し遅らせるようにしてください。

時間がたつにつれて接続品質が変化する環境でクライアントが動作する場合は、接続が劣化したこと検知できるようにしてください。 劣化を検知した場合は、接続品質が改善されるまでの間RESTを使ったポーリングに切り替えるようにしてください。



速度制限

バックオフを実装しないで延々と再接続を試行するようなクライアントは、僅かな時間の接続でも速度制限をされてしまいます。 速度制限に引っかかったクライアントでは、全ての接続要求に対してHTTP 420の応答が返されます。

接続を破棄して頻繁に再接続をする(例えば、クエリパラメータを変更するなど)クライアントは、速度制限を受ける危険があります。

Twitterでは速度制限を受ける接続回数を公開してはいませんが、テストや開発のためにある程度の余裕は持っています。 時々数十回の接続を試すくらいでは制限はかかりません。しかし、HTTP 420の応答を受け取った場合は数分の間接続を停止する必要があります。 あなたのクライアントが頻繁に速度制限を受ける場合は、あなたのIPはTwiterへのアクセスを無期限のでブロックされている可能性があります。



ベストプラクティス

バックオフ方式のテスト

バックオフが実装できているかをテストする良い方法は、無効な承認資格を使って再接続のテストをすることです。 実装が正しければHTTP 420の応答を受信しません

再接続を複数回実施して問題が発生した時の通知

クライアントが再接続間隔の上限に達した場合、そのことがあなたに通知され、接続に影響する問題を優先して対応することができます。

DNS の変更を制御する

あなたのクライアントのプロセスが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ヘッダを設定してください。



HTTP エラーコード

大抵のエラーコードは説明の文字列が追加で付けられて取得されます。 200よりも大きいコードを取得した場合、クライアントは再接続するまで少し待機する必要があります。上記の接続の項目を参照してください。

ステータス テキスト 説明
200 Success 見ての通り、成功です。
401 Unauthorized

HTTP 認証は以下いずれかの原因で失敗しました:

  • 無効なベーシック認証資格か、無効なOAuth リクエストです。
  • OAuth リクエストのタイムスタンプがズレています(the response body will indicate this).
  • 間違ったパスワードを非常にたくさん入力したか、その他ログインの速度制限に引っかかりました。
403 Forbidden 接続しているアカウントは、このエンドポイントへのアクセス権がありません。
404 Unknown

このURLには何もありません。つまり、指定したリソースは存在しません。

406 Not Acceptable

少なくとも一つの必須パラメータが無効です。例えば、filter エンドポイントでは以下の場合にこのステータスを返します:

  • 検索キーワード が長すぎるか短すぎる。
  • 無効な領域範囲 が設定された。
  • track パラメータと follow パラメータが設定されていない。
  • フォローユーザーのIDが有効ではない。
413 Too Long

パラメータ一覧が長すぎます。例えば、filter エンドポイントでは以下の場合にこのステータスを返します:

  • このユーザーが使用できる数を超えたtarck値が送信されました。
  • このユーザーが使用できる数を超えた領域範囲が送信されました。
  • このユーザーが使用できる数を超えたフォローユーザーIDが送信されました。
416 Range Unacceptable

例えば、エンドポイントでは以下の場合にこのステータスを返します:

  • count パラメータが設定されましたが、このユーザーはcountパラメータを使うためのアクセス権を持っていません。
  • count パラメータが設定されましたが、使用できる値の上限もしくは下限を超えています。
420 Rate Limited

クライアントの接続回数が多すぎます。例えば、エンドポイントでは以下の場合にこのステータスを返します:

  • クライアントが短時間で非常に多くのログインを試みた。
  • 非常に多くのアプリケーションが同じ資格情報で認証を試みた。.
503 Service Unavailable

ストリーミングサーバは一時的に負荷が高い状態でした。接続の速度制限、クライアントにDNS情報がキャッシュされている可能性を考慮に入れた上で、再接続を試みてください。