페이지 매김

​

소개

페이지네이션은 단일 응답에 담을 수 있는 양을 초과하는 결과를 반환하는 X API v2 엔드포인트에서 제공되는 기능입니다. 이런 경우 데이터는 일련의 “페이지”로 나누어 반환됩니다. 페이지네이션은 전체 결과 데이터 세트를 가져오기 위해 모든 페이지를 프로그래밍 방식으로 요청하는 방법을 말합니다. 모든 API 엔드포인트가 페이지네이션을 지원하거나 요구하는 것은 아니지만, 결과 세트가 큰 경우 자주 사용됩니다.

​

페이지네이션의 사용 사례

요청의 모든 결과를 가져오려면: 페이지네이션은 특정 요청과 해당 매개변수와 관련된 모든 데이터를 수집할 때 사용해야 합니다. 한 요청에서 일치하는 결과가 max_results 값을 초과하는 경우 페이지네이션이 필요합니다. 페이지네이션 토큰을 사용해 요청을 반복하면 모든 결과를 가져올 수 있습니다. 응답에 next_token 값이 없으면 모든 결과를 끝까지 조회한 것으로 볼 수 있습니다. 페이지네이션은 폴링 목적에 사용하지 마세요. 이전 요청 이후의 최신 결과를 가져오려면 since_id를 사용한 폴링을 검토하세요.

요청 결과를 탐색하려면: 페이지네이션은 응답의 next_token 및 previous_token 값을 사용하여 결과를 앞뒤로 탐색할 수 있는 방향 옵션을 제공합니다. 이러한 토큰은 이후 요청에서 pagination_token으로 설정해 다음 또는 이전 결과 페이지로 이동할 수 있습니다.

​

페이지네이션 토큰 정의

• next_token - 페이지네이션을 지원하는 엔드포인트의 meta 객체 응답에 포함되어 반환되는 불투명 문자열입니다. 추가 결과가 있음을 나타내며, 다음 요청에서 결과의 다음 페이지를 가져오기 위해 pagination_token 매개변수로 사용할 수 있습니다. 마지막 페이지에는 next_token이 포함되지 않습니다.
  • previous_token - 페이지네이션을 지원하는 엔드포인트의 meta 객체 응답에 포함되어 반환되는 불투명 문자열입니다. 이전 결과 페이지가 있음을 나타내며, 다음 요청에서 이전 페이지를 가져오기 위해 pagination_token 매개변수로 설정할 수 있습니다.
  • pagination_token - 페이지네이션 요청에 사용되는 매개변수입니다. 다음 페이지를 요청할 때는 next_token 값을, 이전 페이지를 요청할 때는 previous_token 값을 설정합니다.

​

페이지네이션의 기본

• 페이지네이션을 사용하는 엔드포인트는 초기 요청에 대해 첫 페이지의 결과로 응답하며, 추가 결과 페이지가 있으면 JSON 응답의 meta 객체에 next_token을 제공합니다. 모든 결과를 받으려면 응답에 더 이상 next_token이 포함되지 않을 때까지 이 과정을 반복하세요.
  • 결과는 최신순(내림차순)으로 제공됩니다. 이는 개별 페이지 내에서도, 여러 페이지 전반에서도 동일합니다:
    • 첫 번째 응답의 첫 번째 게시물이 가장 최신입니다.
    • 마지막 응답의 마지막 게시물이 가장 오래되었습니다.
  • max_results 요청 매개변수를 사용하면 응답 페이지당 반환되는 게시물 수를 설정할 수 있습니다. max_results에는 기본값과 최대값이 있습니다.
  • 모든 페이지네이션 구현에는 응답 페이로드에서 토큰을 파싱하는 과정이 포함되며, 이 토큰은 이후 요청에서 사용할 수 있습니다.
  • 경우에 따라 페이지당 max_results보다 적은 결과를 받을 수 있습니다. 페이지당 결과 수가 항상 max_results 매개변수 값과 같다고 가정하지 마세요.
  • 전체 결과를 얻기 위한 가장 좋은 페이지네이션 방법은 통합 코드에서 루프 로직을 사용하거나 X API v2를 지원하는 라이브러리를 사용하는 것입니다.

​

페이지네이션 예시

여기서는 max_results가 100으로 설정되어 있고, 2019년 1월 1일 17:00:00 UTC부터 12월 12일 00:00:00 UTC 사이에 사용자 ID 2244994945(@XDevelopers)가 생성한 게시물이 약 295개이므로 결과가 세 페이지에 걸쳐 제공됩니다. 첫 번째 페이지의 첫 번째 게시물(1337498609819021312)이 가장 최신이며, 세 번째 페이지의 마지막 게시물(1082718487011885056)이 가장 오래되었습니다.

​

최초 요청

      https://api.x.com/2/users/2244994945/tweets?tweet.fields=created_at&max_results=100&start_time=2019-01-01T17:00:00Z&end_time=2020-12-12T01:00:00Z

​

시퀀스 테이블

	첫 번째 요청	두 번째 페이지	세 번째 페이지	네 번째 페이지
요청 파라미터	- max_results = 100 - tweet.fields = created_at - start_time = 2019-01-01T17:00:00Z - end_time = 2020-12-12T01:00:00Z	- max_results = 100 - tweet.fields = created_at - start_time = 2019-01-01T17:00:00Z - end_time = 2020-12-12T01:00:00Z - pagination_token = 7140w	- max_results = 100 - tweet.fields = created_at - start_time = 2019-01-01T17:00:00Z - end_time = 2020-12-12T01:00:00Z - pagination_token = 7140k9	- max_results = 100 - tweet.fields = created_at - start_time = 2019-01-01T17:00:00Z - end_time = 2020-12-12T01:00:00Z - pagination_token = 71408hi
응답	json { "data": [ { "created_at": "2020-12-11T20:44:52.000Z", "id": "1337498609819021312", "text": "오늘 시청해 주신 모든 분들께 감사드립니다..." }, ... , { "created_at": "2020-05-06T17:24:31.000Z", "id": "1258085245091368960", "text": "이제 트윗 영향력을 더 쉽게 이해할 수 있습니다..." } ], "meta": { "oldest_id": "1258085245091368960", "newest_id": "1337498609819021312", "result_count": 100, "next_token": "7140w" } }	json { "data": [ { "created_at": "2020-04-29T17:01:44.000Z", "id": "1255542797765013504", "text": "우리 개발자 커뮤니티는 영감을 주는 아이디어로 가득합니다..." }, ... , { "created_at": "2019-11-21T16:17:23.000Z", "id": "1197549579035496449", "text": "곧 다음 도구를 출시할 예정입니다..." } ], "meta": { "oldest_id": "1197549579035496449", "newest_id": "1255542797765013504", "result_count": 100, "next_token": "7140k9", "previous_token": "77qp8" } }	json { "data": [ { "created_at": "2019-11-21T16:17:23.000Z", "id": "1197549578418941952", "text": "많은 양의 답글을 받는 일부 사용자가..." }, ... , { "created_at": "2019-01-08T19:19:37.000Z", "id": "1082718487011885056", "text": "그리드 임베드 업데이트..." } ], "meta": { "oldest_id": "1082718487011885056", "newest_id": "1197549578418941952", "result_count": 95, "next_token": "71408hi", "previous_token": "77qplte" } }	json { "meta": { "result_count": 0, "previous_token": "77qpw8l" } }
다음 요청을 위한 작업	다음 페이지를 가져오려면 응답에서 next_token 값(7140w)을 가져와 다음 요청 호출의 pagination_token으로 설정합니다.	모든 결과를 계속 가져오려면: 응답에서 next_token 값(7140k9)을 가져와 다음 요청 호출의 pagination_token으로 설정합니다. 이전 페이지로 이동하려면: 응답에서 previous_token 값(77qp8)을 가져와 다음 요청 호출의 pagination_token으로 설정합니다.	모든 결과를 계속 가져오려면: 응답에서 next_token 값(71408hi)을 가져와 다음 요청 호출의 pagination_token으로 설정합니다. 이전 페이지로 이동하려면: 응답에서 previous_token 값(77qplte)을 가져와 다음 요청 호출의 pagination_token으로 설정합니다.	next_token이 없으므로 모든 결과를 수신했음을 나타냅니다. 이전 페이지로 이동하려면: 응답에서 previous_token 값(77qpw8l)을 가져와 다음 요청 호출의 pagination_token으로 설정합니다.