Using cursors to navigate collections |
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
の応答が返ってきます。
CursoringThe Twitter REST API utilizes a technique called ‘cursoring’ to paginate large result sets. Cursoring separates results into pages (the size of which are defined by the To retrieve cursored results, you initially pass a The |
エンドポイントへカーソル指定し、全ての応答を得るまで処理を繰り返す擬似コードは以下のようになります:
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 )
PseudocodeThe pseudocode to iterate over all responses from a cursored endpoint is: 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になりました。アカウントのフォロワーを取得するための繰り返し処理はこれで完了です。
ExampleLet’s see a real-life example of cursors in action. Consider the common scenario where we want to obtain the list of IDs who follow a user who has a large amount of followers. Instead of returning all IDs in one response set, the endpoint will instead return pages of results. RequestGET https://api.twitter.com/1.1/followers/ids.json?screen_name=theSeanCookResponse (truncated) { "ids": [ 385752029, 602890434, ... 333181469, 333165023 ], "next_cursor": 1374004777531007833, "next_cursor_str": "1374004777531007833", "previous_cursor": 0, "previous_cursor_str": "0" } We now have a means to move forwards through our dataset, via the GET https://api.twitter.com/1.1/followers/ids.json?screen_name=theSeanCook&cursor=1374004777531007833Response (truncated) { "ids": [ 333156387, 333155835, ... 101141469, 92896225 ], "next_cursor": 1323935095007282836, "next_cursor_str": "1323935095007282836", "previous_cursor": -1374003371900410561, "previous_cursor_str": "-1374003371900410561" } Notice that we now have a GET https://api.twitter.com/1.1/followers/ids.json?screen_name=theSeanCook&cursor=1323935095007282836Response (truncated) { "ids": [ 73635015, 61175149, ... 18300955, 32684766 ], "next_cursor": 0, "next_cursor_str": "0", "previous_cursor": -1323886329961827926, "previous_cursor_str": "-1323886329961827926" } Huzzah. The |