페이지네이션

X API는 여러 페이지의 결과를 반환하는 엔드포인트(예: 타임라인, 검색 등)에 페이지네이션을 사용합니다. 각 API 응답에는 result_count, previous_token, next_token이 포함된 meta 객체가 있습니다. XDK는 next_token을 사용해 필요한 만큼의 API 호출을 자동으로 처리하므로, 개발자는 여러 번 호출을 직접 만들 필요 없이 원하는 데이터 양만 지정하면 됩니다. SDK는 다음과 같이 이 작업을 단순화합니다:

• 내장 이터레이터: 제너레이터 함수를 사용해 여러 페이지를 자연스럽게 연속해서 가져옵니다.
• 명시적 토큰 처리: 필요할 때 pagination_token을 전달하여 유연하게 수동 제어할 수 있습니다.
• 최대 결과 수 준수: 호출당 max_results를 준수합니다(검색의 경우 최대 100 등, API 한도 내).

​

자동 페이지네이션(권장)

페이지네이션이 적용된 응답에서 iterate() 메서드를 사용해 모든 결과를 지연 로딩 방식으로 가져옵니다. 예시: 페이지네이션 검색

from xdk import Client
client = Client(bearer_token="your_bearer_token")
# 자동 페이지네이션으로 검색
all_posts = []
for page in client.posts.search_recent(
    query="python",
    max_results=100,  # 페이지당
    tweet_fields=["created_at", "author_id"]  # 선택적 확장
):
    all_posts.extend(page.data)
    print(f"Fetched {len(page.data)} Posts (total: {len(all_posts)})")
print(f"Total tweets: {len(all_posts)}")

• 이터레이터가 next_token을 자동으로 처리합니다.
• next_token이 더 이상 없으면 중지됩니다.
• 429 errors를 피하기 위한 rate limit 백오프를 지원합니다.

​

수동 페이지네이션

사용자 정의 로직(예: 페이지별 처리)에 따라 결과를 세밀하게 제어해야 하는 경우, 아래와 같이 next_token을 사용해 페이지네이션을 수동으로 처리할 수 있습니다.

# Get first page - search_recent returns an Iterator
first_page = next(client.posts.search_recent(
    query="xdk python sdk",
    max_results=100,
    pagination_token=None  # First page
))
print(f"First page: {len(first_page.data) if first_page.data else 0} Posts")
# Extract next_token from meta
next_token = None
if hasattr(first_page, 'meta') and first_page.meta:
    if hasattr(first_page.meta, 'next_token'):
        next_token = first_page.meta.next_token
    elif isinstance(first_page.meta, dict):
        next_token = first_page.meta.get('next_token')
if next_token:
    second_page = next(client.posts.search_recent(
        query="xdk python sdk",
        max_results=100,
        pagination_token=next_token
    ))
    print(f"Second page: {len(second_page.data) if second_page.data else 0} Posts")

팁:

• 엔드포인트마다 기본값이 다르므로, 항상 max_results를 지정해 최적화하세요.
• 디버깅을 위해 meta.result_count를 모니터링하세요.
• 매우 큰 쿼리의 경우, 블로킹을 피하기 위해 비동기 반복을 사용하는 것을 고려하세요. Python XDK를 사용한 자세한 코드 예시는 code samples GitHub repo를 참고하세요.