메인 콘텐츠로 건너뛰기

​
Timelines 엔드포인트와 통합하는 방법

이 페이지에는 Timelines 엔드포인트를 시스템에 통합할 때 알아두어야 할 여러 도구와 핵심 개념이 정리되어 있습니다. 이 페이지는 다음 섹션으로 구성됩니다:

​
유용한 도구

핵심 개념을 살펴보기 전에, 아래 도구나 코드 샘플 중 하나를 사용해 이 엔드포인트들의 기능을 먼저 테스트해 보시길 권장합니다. 코드 샘플 선호하는 프로그래밍 언어로 코드를 사용해 이 엔드포인트들을 설정하고 싶으신가요? 시작점으로 활용할 수 있는 다양한 코드 샘플을 GitHub 페이지에서 확인하실 수 있습니다. 라이브러리 시작에 도움이 되도록 다양한 커뮤니티 서드파티 라이브러리를 활용해 보세요. 올바른 버전 태그를 확인하면 v2 엔드포인트와 호환되는 라이브러리를 찾을 수 있습니다. Postman Postman은 이 엔드포인트들을 테스트하는 데 유용한 도구입니다. 각 Postman 요청에는 사용 가능한 항목을 빠르게 파악할 수 있도록 모든 경로 및 본문 매개변수가 포함되어 있습니다. Postman 컬렉션에 대해 자세히 알아보려면 Postman 사용 페이지를 방문하세요.

​
핵심 개념

인증 모든 X API v2 엔드포인트는 키와 토큰으로도 불리는 자격 증명 세트로 인증된 요청이 필요합니다. 이러한 엔드포인트에 대한 요청 인증에는 OAuth 1.0a 사용자 컨텍스트 또는 OAuth 2.0 Authorization Code with PKCE를 사용할 수 있습니다. 사용자 게시물 타임라인과 사용자 멘션 타임라인에는 OAuth 2.0 App-Only를 사용할 수 있습니다. OAuth 1.0a 사용자 컨텍스트에서는 요청에 함께 전달할 authorization 헤더 생성을 위해 API 키, 사용자 액세스 토큰, 기타 몇 가지 매개변수를 사용해야 합니다. 액세스 토큰은 귀하가 대신 요청을 수행하는 대상 사용자와 연동되어 있어야 합니다. 다른 사용자의 액세스 토큰을 생성하려면 해당 사용자가 3-legged OAuth 플로우를 통해 귀하의 App을 승인해야 합니다.  OAuth 1.0a는 사용이 까다로울 수 있습니다. 이 인증 방식에 익숙하지 않다면 라이브러리를 사용하거나 Postman 같은 도구를 사용하거나, OAuth 2.0으로 요청을 인증할 것을 권장합니다. 이러한 엔드포인트에서 게시물 또는 비공개 메트릭을 요청하려면 OAuth 1.0a 사용자 컨텍스트 또는 OAuth 2.0 Authorization Code with PKCE 중 하나를 사용해야 하며, 이를 통해 해당 콘텐츠 소유자로부터 적절한 권한을 확보할 수 있습니다. OAuth 2.0 App-Only는 요청에 OAuth 2.0 App 액세스 토큰을 전달하기만 하면 됩니다. Developer 앱 내에서 직접 App 액세스 토큰을 생성하거나 POST oauth2/token 엔드포인트를 사용하여 생성할 수 있습니다. 이는 사용자 게시물 타임라인 또는 사용자 멘션 타임라인에 사용할 수 있습니다. OAuth 2.0 Authorization Code with PKCE는 애플리케이션의 스코프에 대한 더 세밀한 제어와 여러 기기에 걸친 인증 플로우를 지원합니다. OAuth 2.0을 사용하면 사용자 대신 특정 권한을 부여하는 세분화된 스코프를 선택할 수 있습니다.  App에서 OAuth 2.0을 사용하려면 개발자 포털의 App 설정 섹션에 있는 인증 설정에서 이를 활성화해야 합니다.
유의 사항다음 필드를 요청하는 경우 OAuth 1.0a 사용자 컨텍스트 또는 OAuth 2.0 Authorization Code가 필요합니다: 
  • tweet.fields.non_public_metrics
  • tweet.fields.promoted_metrics
  • tweet.fields.organic_metrics
  • media.fields.non_public_metrics
  • media.fields.promoted_metrics
  • media.fields.organic_metrics
개발자 포털, 프로젝트, 및 Developer 앱 X API v2의 어떤 엔드포인트를 사용하려면 개발자 계정 등록 후 해당 계정 내에 프로젝트를 설정하고, 그 프로젝트 내에 Developer 앱을 생성해야 합니다. 해당 Developer 앱의 키와 토큰은 이 타임라인 엔드포인트에서 동작합니다. 요청 한도 매일 수천 명의 개발자가 X API에 요청을 보냅니다. 트래픽 관리를 위해 각 엔드포인트에는 앱 또는 인증된 사용자를 대신하여 각 개발자가 수행할 수 있는 요청 수를 제한하는 요청 한도가 설정되어 있습니다.  이러한 엔드포인트에는 사용 중인 인증 방식에 따라 서로 다른 요청 한도가 적용됩니다. 앱 수준 요청 한도는 OAuth 2.0 App-Only로 요청하는 App에 적용되며, 사용자 수준 요청 한도는 OAuth 1.0a 사용자 컨텍스트를 사용해 특정 승인 사용자를 대신하여 수행되는 요청에 적용됩니다. 두 요청 한도는 15분 윈도우 내 요청 빈도를 기준으로 합니다. 예를 들어, 이 두 타임라인 엔드포인트 모두에 대해 OAuth 2.0 App-Only 인증을 사용하는 앱은 15분 시간 범위 내에서 사용자 게시물 타임라인에 1,500건(페이지네이션 요청 포함), 사용자 멘션 타임라인에 450건(페이지네이션 요청 포함)의 요청을 보낼 수 있습니다. 동일한 앱이 동일한 15분 시간 범위 내에서 서로 다른 두 명의 승인된 사용자(OAuth 1.0a 사용자 컨텍스트 사용)와 함께할 경우, 각 인증된 사용자별로 사용자 게시물 타임라인에 900건(페이지네이션 요청 포함), 사용자 멘션 타임라인에 180건(페이지네이션 요청 포함)의 요청을 보낼 수 있습니다. 역순(최신순) 홈 타임라인은 사용자당 15분 창마다 180건의 요청 제한이 적용됩니다. 이 엔드포인트를 사용하면 지난 7일 동안 타임라인에 생성된 모든 게시물과, 생성 날짜와 관계없이 가장 최근의 게시물 800개를 반환할 수 있습니다. 필드와 expansions X API v2는 fields와 expansions를 사용해 API에서 반환받길 원하는 데이터를 정확히 선택할 수 있게 합니다. expansions 매개변수는 페이로드에서 참조되는 객체를 확장하여 포함합니다. 예를 들어, 이 엔드포인트에서는 expansions 매개변수를 사용해 poll, place, media 등의 객체를 요청할 수 있습니다. fields 매개변수는 서로 다른 데이터 객체 내에서 수신하려는 정확한 필드를 선택할 수 있게 합니다. 기본적으로 이 엔드포인트들이 반환하는 기본 게시물 객체에는 id 및 text 필드가 포함됩니다. author_id 또는 public_metrics와 같은 추가 필드를 받으려면 fields 매개변수를 사용하여 해당 필드를 명시적으로 요청해야 합니다. 통합 시 고려할 만한 중요한 필드로는 설문 데이터, metrics, Post annotations, conversation ID 등이 있습니다. how to use fields and expansions를 함께 사용하는 방법에 대한 가이드를 X API v2 data dictionary에 추가했습니다. 게시물 지표 X API v2 엔드포인트는 요청에 적절한 필드를 포함하는 경우, 반환되는 게시물 객체에서 직접 게시물 지표를 요청할 수 있습니다. 게시물 지표에는 사용자 프라이버시와 아래 응답 필드와 관련된 일부 제한이 있습니다:
  • tweet.fields.non_public_metrics
  • tweet.fields.promoted_metrics
  • tweet.fields.organic_metrics
  • media.fields.non_public_metrics
  • media.fields.promoted_metrics
  • media.fields.organic_metrics
위 필드에는 비공개 지표 데이터가 포함되므로, 사용자 게시물 타임라인 엔드포인트를 사용할 때 게시자의 대리로 이 데이터를 가져오려면 게시물 게시자의 승인이 필요하며, OAuth 1.0a User Context 또는 OAuth 2.0 Authorization Code Flow with PKCE를 사용해야 합니다. 예를 들어, 사용자 ID 1234의 사용자 게시물 타임라인에서 non_public_metrics를 받으려면 해당 사용자와 연결된 액세스 토큰을 요청에 포함해야 합니다. 3-legged OAuth flow를 사용해 사용자가 앱을 승인하도록 하고, 그 사용자와 연결된 액세스 토큰 세트를 발급받을 수 있습니다. 사용자 멘션 타임라인을 사용하는 경우, 위 필드는 멘션 작성자가 앱의 비공개 지표 데이터 접근을 승인했고, OAuth 1.0a 사용자 컨텍스트로 요청을 보내며 해당 사용자의 액세스 토큰을 사용하는 경우에만 제공됩니다. non_public_metrics, organic_metrics, promoted_metrics는 모두 최근 30일 내에 생성된 게시물에만 제공됩니다. 즉, 위 필드를 요청할 때 결과는 자동으로 최근 30일의 게시물만 포함하도록 제한됩니다. 이들 필드를 요청하는 경우, 인증된 사용자가 작성한 게시물만 반환되며 다른 모든 게시물에는 오류가 반환됩니다. 페이지네이션 이 엔드포인트들은 응답을 신속히 반환하기 위해 페이지네이션을 사용합니다. 단일 응답으로 보낼 수 있는 결과보다 더 많은 결과가 있는 경우(타임라인 엔드포인트는 최대 100개 게시물) 페이지네이션이 필요합니다. 페이지당 반환할 결과 수를 지정하려면 max_results 매개변수를, 다음 페이지 결과를 받으려면 pagination_token 매개변수를 사용하십시오. 자세한 내용은 pagination guide를 참고하십시오. 결과 필터링 이 엔드포인트에는 결과를 필터링하는 데 사용할 수 있는 여러 매개변수가 포함되어 있습니다. start_date 및 end_date를 사용하면 결과를 특정 기간으로 좁힐 수 있습니다. 특정 게시물 집합을 선택하기 위해 게시물 ID를 사용하려면 since_id 및 until_id를 사용할 수 있습니다. 사용자 게시물 타임라인에는 결과에서 리트윗과 답글을 제외할 수 있는 exclude 매개변수도 있습니다.  게시물 상한 및 반환 게시물 수 사용자 게시물 타임라인과 사용자 멘션 타임라인 엔드포인트는 특정 월에 반환할 수 있는 게시물 수에 제한이 있습니다. 역순 시간순 홈 타임라인 엔드포인트는 이 제한의 적용을 받지 않습니다. 어느 타임라인 엔드포인트를 사용하든 반환된 게시물은 프로젝트 수준 게시물 상한에 포함됩니다. 사용량은 개발자 포털에 표시되며, ‘월’은 개발자 포털 대시보드에 표시된 구독 갱신일에 시작됩니다.  사용자 게시물 타임라인 엔드포인트는 사용자의 타임라인에 게시된 가장 최근 3,200개의 게시물만 반환합니다. start_time 및 end_time을 가장 최근 3,200개를 넘어서는 기간으로 설정하면 성공적인 응답을 받더라도 게시물은 반환되지 않습니다. 또한 사용자 게시물 타임라인 요청에 excludes=replies를 전달하는 경우, 가장 최근 800개의 게시물만 반환된다는 점에 유의하세요. 사용자 멘션 타임라인 엔드포인트는 가장 최근 게시물 멘션 800개만 반환합니다. 역순 시간순 홈 타임라인 엔드포인트는 마지막 3,200개의 게시물을 반환합니다. 게시물 수정 수정 가능한 게시물은 원본 게시물이 게시된 후 30분 이내에 최대 다섯 번까지 수정할 수 있습니다. 검색 엔드포인트는 항상 게시물의 최신 버전을 제공합니다. 게시된 지 30분 이상 지난 게시물만 요청하는 경우 항상 게시물의 최종 버전을 받게 됩니다. 그러나 거의 실시간에 가까운 사용 사례로 지난 30분 내에 게시된 게시물을 조회하는 경우에는 해당 게시물이 수신 이후에 수정되었을 수 있습니다. 이러한 게시물은 검색 또는 게시물 조회 엔드포인트로 재수화하여 최종 상태를 확인할 수 있습니다. 게시물 수정 방식에 대한 자세한 내용은 게시물 수정 기본 사항 페이지를 참조하세요.   엣지 케이스
  • 사용자 게시물 타임라인 엔드포인트에서 30일이 지난 게시물에 대해 비공개 지표를 요청하는 경우, 결과 수가 0인 next_token이 응답에 포함될 수 있습니다. 이 문제를 피하려면 non_public_metrics 매개변수로 요청하는 기간을 최근 30일 이내로 설정하세요. 또한 max_results의 최소값은 10이어야 합니다. 이는 해당 상황을 피하는 데 도움이 될 수 있으나, 여전히 발생할 수 있습니다.
  • 프로모션되지 않은 게시물에 대해 프로모션 지표를 요청하면 게시물 데이터 대신 빈 응답이 반환됩니다. 이 문제는 현재 수정 중입니다.
  • 본문 텍스트가 140자를 초과하는 게시물을 리트윗한 경우, 전체 게시물 텍스트를 반환하는 대신 text 필드가 잘립니다. 단기적인 해결 방법으로는 참조된 게시물을 확장하여(expansion) 해당 확장에서 전체 텍스트를 가져오는 것입니다. 이는 향후 수정될 버그입니다.
다음 단계 [타임라인 엔드포인트에 첫 요청 보내기]/x-api/posts/timelines#getting-started-with-reverse-chronological-home-timeline “타임라인 엔드포인트에 첫 요청 보내기”) API Reference 페이지에서 매개변수, 필드 등 전체 목록 보기 지원 받기 또는 오류 문제 해결