サイトのトップへ戻る

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

サイト内検索

サイトストリームの制御ストリーム

制御ストリームでは、開発者が指定したサイトストリーム接続の状態を参照したり編集したりできる、RESTベースのインタフェースが使用できます。 Use the same three-legged OAuth patterns you use to connect to Site Streams, where the access token used belongs to the user that owns the application that bears access tokens for the users you’re streaming on behalf of.

現時点では、制御ストリームを使って以下のことができます:



stream_id とcontrol_uriを決定する

サイトストリームへの接続を開いた後、 you will be streamed a new event that will declare a specific URI path for you to base control requests from in the format of /:version/site/c/:stream_id. “control” イベント内の“control_uri”ノードからURLパスを取得できます。

{
  "control": {
    "control_uri":"/1.1/site/c/1_1_54e345d655ee3e8df359ac033648530bfbe26c5f"
  }
}

このパスの“/1.1/site/c/”以降の部分は、ストリームのユニークstream_idです。このストリームが切断されると、 stream_id は無効になります。上記の例では、 stream_id は “1_1_54e345d655ee3e8df359ac033648530bfbe26c5f” です。

サイトストリーム接続で最初に配信されるメッセージが、必ずcontrolメッセージになるとは限らないので注意してください。 他のタイプのメッセージが最初に配信されてきた場合でも処理できるように、コードを記述して下さい。



現在のストリームの状態に関する情報を取得する

URI 形式: GET /1.1/site/c/:stream_id/info.json

control メッセージから取得したstream_idを使い、 GET リクエストを作成して現在ストリーム上取り込んでユーザーの情報を取得することができます。 取得できる情報には、どれくらいの接続があるか、あなたは指定したユーザーへのRW+DM アクセス権を持っているかどうか、その他現段階では必要のない様々な情報があります。

This is the most reliable way to determine which users are being streamed over a particular connection.

GET /1.1/site/c/1_1_54e345d655ee3e8df359ac033648530bfbe26c5f/info.json

{
    "info":
    {
        "users":
        [
            {
                "id":119476949,
                "name":"oauth_dancer",
                "dm":false
            }
        ],
        "delimited":"none",
        "include_followings_activity":false,
        "include_user_changes":false,
        "replies":"none",
        "with":"user"
    }
}

サイトストリームのcontrolメッセージと違って、 “info request” 内にユーザーがフォローしているユーザーIDの配列が含まれていないことに気づいたでしょうか。 この情報を取得するには、制御ストリームのfriends/idsメソッド(REST APIのfriends/idsメソッドと同じ機能を持つ)を使用することができます。

A control stream may not be ready for manipulation and querying directly after receiving the control event — it may take as much as a minute for a stream info request to fully reflect the users currently connected to the specified stream.



認証ユーザーをサイトストリームコネクションに追加する

URI 形式: POST /1.1/site/c/:stream_id/add_user.json

ユーザーを現在のコネクションに追加するには、以下のような OAuth POST を送信するだけでとても簡単です:

POST /1.1/site/c/1_1_54e345d655ee3e8df359ac033648530bfbe26c5f/add_user.json
POST body: user_id=819797

あなたがユーザーのアクセストークンを持っていれば、これでユーザー 819797 が現在のストリームに追加されます。指定してユーザー(達)が追加できなかった場合は、次のようなメッセージが付いた 400 Bad Request HTTP code が取得されます: “No authorized followings found for your request”

追加リクエストが成功すると、空の 200 OK 応答が返ります。 The user(s) will be added to your specified stream and you’ll see the “preamble” for the added user(s) in your stream near immediately.また、“info”エンドポイントに別のGETリクエストを発行してストリームが変更されたか確認することもできます。

user_id パラメータは、コンマで区切って最大100ユーザー分のIDを設定できます。info メソッドであなたのストリーム上の接続数を監視し、接続制限を越えないようにして下さい。 新しいユーザーのためのスペースを確保するには、 remove_user を使ってユーザーをストリームから削除してください。

サイトストリームへの最初の接続では、100ユーザーを指定できます。1接続あたり最大1,000ユーザーまでストリーム内に取り込めますが、101人目から1000人目のユーザーを追加するには、サイトストリームごとに 1秒間に25リクエスト を超えないペースで、add_user メソッドを使って追加しなければなりません。 This allows you to add around 2,500 users per second to your current pool of site streams connections.



認証ユーザーをサイトストリームの接続から削除します。

URI 形式: POST /1.1/site/c/:stream_id/remove_user.json

ユーザーを現在のコネクションから削除するには、以下のような OAuth POST を送信するだけでとても簡単です:

POST /1.1/site/c/1_1_54e345d655ee3e8df359ac033648530bfbe26c5f/remove_user.json
POST body: user_id=819797

あなたがユーザーのアクセストークンを持っており、そのユーザーがストリームに取り込まれていれば、これでユーザー 819797 が現在のストリームから削除されます。 指定してユーザー(達)が追加できなかった場合は、次のようなメッセージが付いた 400 Bad Request HTTP code が取得されます: “No authorized followings found for your request”

削除リクエストが成功すると、空の 200 OK 応答が返ります。 The user will be removed from your specified stream and you’ll see the “preamble” for the added users in your stream near immediately. また、“info”エンドポイントに別のGETリクエストを発行してストリームが変更されたか確認することもできます。



Obtain information about the followings of specific users present on a Site Streams connection

URI 形式: POST /1.1/site/c/:stream_id/friends/ids.json

このメソッドは、対象範囲が指定したストリーム上のユーザーに限定されることを除けば、REST API の GET friends / ids と同じ働きをします。 The list of followings/friends is definitive in that it’s what the Site Streams connection is aware of for the specified user. REST API と同じ方法でカーソルが使用できます。

POST /1.1/site/c/1_1_54e345d655ee3e8df359ac033648530bfbe26c5f/friends/ids.json
POST body: user_id=119476949

{
    "follow":
    {
        "user":
        {
            "id":119476949,
            "name":"oauth_dancer",
            "dm":false
        },
        "friends":
        [
            795649,
            819797,
            1401881,
            3191321,
            6253282,
            8285392,
            9160152,
            13058772,
            15147442,
            15266205,
            15822993,
            27831060,
            101058399,
            289788076
        ],
        "previous_cursor":0,
        "next_cursor":0
    }
}

このドキュメントの最新の変更は以下の通りです:

  • 2011年 9月: バージョン 1.1へ更新。
  • 2011年10月: Base control URI now includes “:stream_id/info.json” as part of the path. All other resources now include “.json” in the path.
  • 2011年11月: もう“:stream_id/info.json”で友達の情報を取得できないので、代わりに “:stream_id/friends/ids.json” を使用してください。現在、“:stream_id/add_user.json”を使ったストリーム1つにつき最大1,000ユーザーまで追加できます
  • 2012年1月: 全てのサイトストリーム開発者にドキュメントを公開。ベータテスターの方々、どうもありがとうございました! 接続制限を明確化しました。