Skip to main content

​
Standard v1.1과 X API v2 비교

v1.1 search/posts를 사용해 왔다면, 이 가이드의 목적은 Standard v1.1 검색 엔드포인트와 X API v2 search Posts 엔드포인트 간의 유사점과 차이점을 이해하는 데 도움을 주는 것입니다.
  • 유사점
    • OAuth 1.0a 사용자 컨텍스트 및 OAuth 2.0 App-only
    • 게시물 수정 내역과 메타데이터 지원 
  • 차이점
    • 엔드포인트 URL
    • App 및 Project 요구 사항
    • 응답 데이터 형식
    • 요청 파라미터
    • 새로운 쿼리 연산자
    • AND / OR 연산자 우선순위 

​
유사점

OAuth 1.0a User Context와 OAuth 2.0 App-Only 인증 v1.1 search/posts와 X API v2 recent search 엔드포인트는 OAuth 1.0a User Context와 OAuth 2.0 App-Only를 모두 지원합니다.  따라서 이전에 표준 v1.1 search 엔드포인트를 사용하고 있었다면 X API v2 버전으로 마이그레이션하더라도 동일한 인증 방식을 계속 사용할 수 있습니다.  사용 중인 인증 라이브러리/패키지에 따라 다르지만, App-Only 인증이 가장 쉽게 시작할 수 있는 방법인 경우가 많으며, 간단한 요청 헤더 설정만으로 사용할 수 있습니다. App 액세스 토큰을 생성하는 방법은 이 OAuth 2.0 App-Only 가이드를 참고하세요.  X API v2 엔드포인트를 사용해 비공개 또는 광고 지표를 조회하려면 OAuth 1.0a User Context를 사용해야 하며, 지표를 조회하려는 게시물을 작성한 사용자에 해당하는 사용자 액세스 토큰을 전달해야 합니다.  게시물 편집 기록 및 메타데이터 지원 두 버전 모두 편집 이력을 설명하는 메타데이터를 제공합니다. 자세한 내용은 search API 참조 문서와 게시물 편집 기본 사항 페이지를 참고하세요. 

​
차이점

엔드포인트 URL App 및 Project 요구 사항 X API v2 엔드포인트는 요청을 인증할 때 developer App과 연결된 Project의 자격 증명을 사용해야 합니다. 모든 X API v1.1 엔드포인트는 Project와 연결되지 않은 App 또는 Project와 연결된 App의 자격 증명을 모두 사용할 수 있습니다.  응답 데이터 형식 Standard v1.1과 X API v2 엔드포인트 버전 간의 가장 큰 차이점 중 하나는 페이로드에서 어떤 필드를 반환할지 선택하는 방식입니다. Standard 엔드포인트의 경우, 기본적으로 많은 응답 필드를 받게 되며, 이후 파라미터를 사용해 페이로드에 어떤 필드 또는 필드 집합을 반환할지 지정할 수 있습니다. X API v2 버전은 기본적으로 Post id와 text 필드만 제공합니다. 추가 필드나 객체를 요청하려면 fields 및 expansions 파라미터를 사용해야 합니다. 이러한 엔드포인트에서 요청한 모든 게시물 필드는 기본 Post 객체에 포함되어 반환됩니다. 확장된 user, media, poll, place 객체 및 필드는 응답 내 includes 객체에 포함되어 반환됩니다. 그런 다음 Post와 확장 객체 양쪽에 있는 ID를 매칭하여, 확장된 객체를 Post 객체와 다시 연결할 수 있습니다.  이러한 새 파라미터에 대해서는 각 가이드에서 더 자세히 읽어 보시거나, fields 및 expansions 사용 방법에 대한 가이드를 참고하시기를 권장합니다.  또한 Standard v1.1 필드를 v2의 새로운 필드로 매핑하는 데 도움이 되는 데이터 형식 마이그레이션 가이드도 제공합니다. 이 가이드는 특정 필드를 반환하기 위해 v2 요청에 함께 전달해야 하는 expansions 및 fields 파라미터를 구체적으로 안내합니다.    특정 필드를 요청하는 방식의 변경 외에도, X API v2는 API가 반환하는 객체(예: Post 및 user 객체)에 대해 새로운 JSON 디자인을 도입합니다.
  • JSON 루트 레벨에서, Standard 엔드포인트는 Post 객체를 statuses 배열로 반환하는 반면, X API v2는 data 배열로 반환합니다. 
  • Retweeted 및 Quoted “statuses”를 참조하는 대신, X API v2 JSON은 Retweeted 및 Quoted Tweets를 참조합니다. contributors 및 user.translator_type 같은 많은 레거시 및 사용 중단 필드는 제거되고 있습니다. 
  • Post 객체의 favorites와 user 객체의 favourites를 모두 사용하는 대신, X API v2는 like라는 용어만 사용합니다. 
  • X는 값이 없는 JSON 값(예: null)은 페이로드에 기록하지 않는 규칙을 채택하고 있습니다. Post 및 user 속성은 null이 아닌 값을 가진 경우에만 포함됩니다.   
또한 Post 객체에 다음을 포함한 새로운 필드 집합을 도입했습니다:
  • conversation_id 필드
  • context와 entities를 포함하는 두 개의 새로운 annotations 필드
  • 여러 개의 새로운 metrics 필드 
  • 특정 게시물에 누가 답글을 달 수 있는지를 보여주는 새로운 reply_setting 필드

​
요청 파라미터

다음 Standard v1.1 요청 파라미터에는 X API v2에서의 대응 항목이 있습니다:
Standard search v1.1Search Posts v2
qquery
start_time (YYYY-MM-DDTHH:mm:ssZ)
until (YYYY-MM-DD)end_time (YYYY-MM-DDTHH:mm:ssZ)
since_idsince_id
max_iduntil_id
countmax_results
Response provides search_metadata.next_resultsnext_token
또한 X API v2에서는 지원되지 않는 표준 Search Posts 요청 파라미터들도 있습니다:
Standard v1.1 parameterDetails
geocodeSearch Posts는 위치 기반 쿼리를 위한 geo 연산자를 지원합니다.
localeStandard search에서는 쿼리의 언어를 지정하기 위해 사용되었으나, 완전히 구현되지는 않았습니다.
langSearch Posts 엔드포인트는 관심 있는 언어와 일치시키기 위한 lang 쿼리 연산자를 제공합니다.
include_entities게시물 엔티티는 항상 포함됩니다.
result_typeSearch Posts 엔드포인트는 참여 수준과 관계없이 일치하는 모든 포스트를 반환합니다.
extendedX API v2는 최대 280자까지의 게시물을 기본으로 지원하도록 처음부터 설계되었습니다. v2에는 ‘extended’ 게시물이라는 개념이 없습니다.
다음은 Standard 요청과 Search Posts 요청 간 차이를 보여주는 예시 요청입니다:
Standard v1.1X API v2
https://api.x.com/1.1/search/tweets.json?q=snow&count=50https://api.x.com/2/tweets/search/recent?query=snow&max_results=50
이 두 요청은 모두 snow 키워드를 포함하는 가장 최근 포스트 50개를 반환합니다. v2 요청은 일치하는 포스트의 기본 id 및 text 필드를 반환합니다. 다음은 JSON 페이로드에 포함할 추가 게시물 및 사용자 필드를 지정하는 예시입니다:
X API v2
https://api.x.com/2/tweets/search/recent?query=snow&max_results=50&tweet.fields=id,created_at,author_id,text,source,entities,attachments&user.fields=id,name,username,description
새로운 쿼리 연산자 Search Posts는 두 가지 새로운 X API v2 기능을 지원하기 위해 새로운 연산자를 도입합니다:
  • Conversation IDs - X에서 대화가 전개됨에 따라, 대화에 포함된 게시물을 표시하기 위한 conversation ID가 제공됩니다. 대화에 속한 모든 게시물의 conversation_id 값은 대화를 시작한 게시물의 Post ID로 설정됩니다. 
    • conversation_id:
  • X Annotations 는 게시물에 대한 문맥 정보를 제공하며, 엔티티 및 컨텍스트 주석을 포함합니다. 엔티티는 사람, 장소, 상품, 조직으로 구성됩니다. 컨텍스트는 노출된 엔티티가 속한 도메인 또는 주제입니다. 예를 들어, 게시물에 언급된 사람은 운동선수, 배우, 정치인인지 여부를 나타내는 컨텍스트를 가질 수 있습니다.  
    • context: 관심 있는 컨텍스트로 주석이 달린 포스트와 일치합니다. 
    • entity: 관심 있는 엔티티로 주석이 달린 포스트와 일치합니다.   

​
AND / OR 연산자 우선순위

검색 쿼리를 구성할 때 기본적인 구성 요소는 OR 및 AND 논리 그룹을 사용하는 것입니다. 표준 검색 API는 AND보다 OR을 먼저 적용하는 반면, Search Posts 엔드포인트(프리미엄 및 엔터프라이즈 버전 포함)는 OR보다 AND를 먼저 적용합니다. 이러한 차이는 두 API 간에 쿼리를 변환할 때 매우 중요합니다.  예를 들어 표준 검색에서 ‘storm’ 키워드를 포함하면서 ‘colorado’라는 단어 또는 #COwx 해시태그가 언급된 포스트를 찾고 싶다면, 다음과 같은 검색 쿼리를 사용할 수 있습니다: storm #COwx OR colorado Search Posts의 연산자 우선순위에서는 AND가 OR보다 먼저 적용됩니다. 따라서 위의 쿼리는 다음과 같습니다:  (storm #COwx) OR colorado 그러나 위 규칙은 포스트에 ‘storm’이나 #COwx 해시태그가 언급되었는지와 관계없이 ‘Colorado’가 언급된 모든 포스트와 일치하게 됩니다. 또한 ‘storm’ 키워드와 #COwx 해시태그가 모두 언급된 포스트도 일치합니다.  쿼리가 원래 의도한 대로 동작하도록 하려면 OR 절을 함께 묶어야 합니다. 원래 표준 쿼리를 Search Posts에 맞게 변환하면 다음과 같습니다: storm (#COwx OR colorado) 이 두 규칙은 매우 다른 매칭 동작을 보입니다. 2019년 10월 한 달 동안, 원래 규칙은 1,175,000개 이상의 포스트와 일치하는 반면, 올바르게 변환된 규칙은 약 5,600개의 포스트와만 일치합니다. AND와 OR의 차이를 반드시 유의하고, 필요한 곳에는 괄호를 사용하십시오. 

​
cURL requests

다음 섹션에서는 표준 v1.1 엔드포인트와 이에 상응하는 v2 엔드포인트에 대한 cURL 요청을 보여줍니다. 요청은 OAuth 2.0 App-Only를 사용해 수행됩니다. 다음 cURL 요청을 실행하려면 Authorization 헤더의 ACCESS_TOKEN을 앱 액세스 토큰으로 교체해야 합니다. v2 엔드포인트의 경우, 앱 액세스 토큰은 Project 내의 developer App에 속해야 합니다.  v1.1 엔드포인트에서 반환되는 응답 페이로드는 v2 엔드포인트에서 반환되는 응답 페이로드와 다릅니다. v2에서는 기본 필드뿐만 아니라 fields 및 expansions 매개변수로 요청한 기타 필드도 응답에 포함됩니다. 이러한 매개변수를 사용해 반환받을 필드 집합을 다르게 지정할 수 있습니다. 표준 v1.1 GET search/tweets → v2 GET tweets/search/recent
cURL (v1.1)
curl --request GET \
  --url 'https://api.x.com/1.1/search/tweets.json?q=from%3AXDevelopers%20-is%3Aretweet&count=100' \
  --header 'Authorization: Bearer $ACCESS_TOKEN'
다음 단계 X API v2 최근 검색 빠른 시작 가이드 살펴보기 최근 검색에 대한 API 참조 문서 검토하기 이 엔드포인트에 대한 샘플 코드 살펴보기 최근 검색에 대한 첫 요청을 보내는 단계별 가이드