サイトのトップへ戻る

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

カーソル機能を使って取得結果を遷移する



カーソリング

Twitter REST API では‘カーソリング(cursoring)’と呼ばれる技術を使って大量の取得結果をページ制御しています。 カーソリングでは取得結果を複数のページに分割し(ページのサイズはリクエスト時に設定したcountパラメータによって決められます)、それらのページ間を前後に移動するための方法が用意されています。

カーソルされた結果を取得するには、まず最初にエンドポイントに対して-1を設定したcursorパラメータを送信します。既定では、cursorパラメータが設定されなかった場合、カーソリングをサポートしているAPI エンドポイントでは -1 が設定されたと見なします。 カーソル指定したリクエストの応答結果には、previous_cursor, next_cursor, previous_cursor_str , next_cursor_strといった値が含まれています。 Twitter APIで使われている多くのID値と同様に、桁の大きい数値に対応できないプログラム言語(例えばJavaScript)のために _str 値が用意されています。

next_cursorとは次のページの応答結果を取得する際にエンドポイントへ送信するカーソルのことで、previous_cursor とは前のページの応答結果を取得する際に送信するカーソルのことです。使用可能な最後の応答ページをリクエストすると、APIからはnext_cursor = 0の応答が返ってきます。



擬似コード

エンドポイントへカーソル指定し、全ての応答を得るまで処理を繰り返す擬似コードは以下のようになります:

cursor = -1
api_path = "https://api.twitter.com/1.1/endpoint.json?screen_name=targetUser"

do {
    url_with_cursor = api_path + "&cursor=" + cursor      
    response_dictionary = perform_http_get_request_for_url( url_with_cursor )
    cursor = response_dictionary[ 'next_cursor' ]
}
while ( cursor != 0 )



実際にカーソル処理を行う例を見てみましょう。たくさんのフォロワーがいるユーザーをフォローしているIDの一覧を取得する場合を考えてください。 エンドポイントは一回の応答で全てのIDを返すのではなく、応答結果を複数のページに分けて返します。

リクエスト
GET https://api.twitter.com/1.1/followers/ids.json?screen_name=theSeanCook
応答(一部省略)
{
    "ids": [
        385752029, 
        602890434, 
        ...
        333181469, 
        333165023
    ], 
    "next_cursor": 1374004777531007833, 
    "next_cursor_str": "1374004777531007833", 
    "previous_cursor": 0, 
    "previous_cursor_str": "0"
}

現在next_cursorを使用することで、Twitterのデータ群内のページ移動をすることができます。 次のページのデータを取得するには同じリクエストを実行しますが、cursorパラメータにnext_cursorの値を設定してください。

リクエスト
GET https://api.twitter.com/1.1/followers/ids.json?screen_name=theSeanCook&cursor=1374004777531007833
応答(一部省略)
{
    "ids": [
        333156387, 
        333155835, 
        ...
        101141469, 
        92896225
    ], 
    "next_cursor": 1323935095007282836, 
    "next_cursor_str": "1323935095007282836", 
    "previous_cursor": -1374003371900410561, 
    "previous_cursor_str": "-1374003371900410561"
}

現在、next_cursorだけでなくprevious_cursorも使用できるので覚えておいてください。つまり、応答結果のページでは前のページと次のページ両方を移動できるということです。next cursorを使ってデータ取得を続けましょう.

リクエスト
GET https://api.twitter.com/1.1/followers/ids.json?screen_name=theSeanCook&cursor=1323935095007282836
応答(一部省略)
{
    "ids": [
        73635015, 
        61175149, 
        ...
        18300955, 
        32684766
    ], 
    "next_cursor": 0, 
    "next_cursor_str": "0", 
    "previous_cursor": -1323886329961827926, 
    "previous_cursor_str": "-1323886329961827926"
}

おめでとう。next_cursorの値がもうページは残っていないことを示す0になりました。アカウントのフォロワーを取得するための繰り返し処理はこれで完了です。