Skip to main content

​
Standard v1.1와 X API v2 비교

v1.1 statuses/filter 엔드포인트를 사용해 왔다면, 이 가이드는 Standard v1.1과 X API v2 필터링 스트림 엔드포인트 간의 유사점과 차이점을 이해하는 데 도움이 됩니다.
  • 유사점
    • 요청 매개변수와 연산자
    • 게시물 편집 기록 및 메타데이터 지원
  • 차이점
    • 엔드포인트 URL
    • App 및 Project 요구 사항
    • 인증 방식
    • 규칙 수 제한 및 상시 스트림
    • 응답 데이터 형식
    • 요청 매개변수
    • 복구 및 이중화 기능 제공 여부
    • 쿼리 연산자

​
유사점

요청 매개변수와 연산자 표준 v1.1 statuses/filter 엔드포인트에는 스트림을 필터링하기 위해 요청과 함께 전달할 수 있는 몇 가지 매개변수가 있습니다. v2 필터링된 스트림에서는 대신, 원하는 포스트를 필터링하기 위해 불리언 로직으로 서로 연결할 수 있는 연산자 집합을 사용합니다. 사용 가능한 연산자에는 기존 표준 v1.1 매개변수를 직접 대체하는 것들도 포함됩니다.  다음 표준 v1.1 요청 매개변수는 X API v2에서 이에 해당하는 연산자가 있습니다:  
StandardX API v2
follow - 쉼표로 구분된 사용자 ID 목록으로, 스트림에 포스트를 전달해야 하는 사용자를 나타냅니다.특정 사용자와 관련된 포스트를 찾는 데 도움이 되는 여러 연산자:

* @
* from:
* to:
* 등
track - 스트림에 전달할 포스트를 결정하는 데 사용되는, 쉼표로 구분된 문구 목록입니다.특정 키워드와 관련된 포스트를 찾는 데 도움이 되는 여러 연산자:

* keyword
* “exact phrase match”
* #
* 등
포스트 편집 기록 및 메타데이터 지원 두 버전 모두 편집 이력을 설명하는 메타데이터를 제공합니다. 자세한 내용은 필터링된 스트림 API 참조 문서와 포스트 편집 기본 사항 페이지를 참고하세요. 

​
Differences

엔드포인트 URL App 및 Project 요구 사항 X API v2 엔드포인트를 사용하려면 요청을 인증할 때 developer App 자격 증명 중 Project와 연결된 자격 증명을 사용해야 합니다. 모든 X API v1.1 엔드포인트는 개별 App 또는 Project와 연결된 App의 자격 증명을 사용할 수 있습니다. 인증 방식 Standard 엔드포인트는 OAuth 1.0a User Context를 지원하는 반면, X API v2 필터링 스트림 엔드포인트는 OAuth 2.0 App-Only (Application-only authentication이라고도 함)을 지원합니다. X API v2 버전으로 요청을 보내려면 App Access Token을 사용하여 요청을 인증해야 합니다. 개발자 콘솔에서 App을 생성할 때 제공되었던 App Access Token이 더 이상 없다면, 개발자 콘솔에서 해당 앱의 “Keys and tokens” 페이지로 이동하여 새 토큰을 생성할 수 있습니다. App Access Token을 프로그래밍 방식으로 생성하려면 이 OAuth 2.0 App-Only 가이드를 참조하세요.  규칙 개수 및 지속 스트림 Standard v1.1 엔드포인트는 스트리밍 연결을 필터링하기 위한 단일 규칙만 지원합니다. 규칙을 변경하려면 스트림 연결을 끊고, 수정된 필터링 규칙을 파라미터로 포함하여 새 요청을 제출해야 합니다.  X API v2 필터링 스트림 엔드포인트는 단일 스트림에 여러 규칙을 적용할 수 있으며, 스트림 연결을 유지한 상태에서 스트림에 대한 규칙을 추가하거나 제거할 수 있습니다.  응답 데이터 형식 Standard v1.1과 X API v2 엔드포인트 버전 간의 가장 큰 차이점 중 하나는 페이로드에 어떤 필드를 포함할지 선택하는 방식입니다. Standard 엔드포인트의 경우, 응답 필드 대부분을 기본적으로 받게 되며, 이후 파라미터를 사용해 어떤 필드 또는 필드 집합을 페이로드에 포함할지 선택할 수 있습니다. X API v2 버전은 기본적으로 게시물 id 및 text 필드만 제공합니다. 추가 필드나 객체를 요청하려면 fields 및 expansions 파라미터를 사용해야 합니다. 이러한 엔드포인트에서 요청한 게시물 필드는 기본 게시물 객체에 포함되어 반환됩니다. 확장된 사용자, 미디어, 설문조사(poll), 장소(place) 객체 및 필드는 응답 내 includes 객체에 포함되어 반환됩니다. 이후 게시물과 확장된 객체 양쪽에 있는 ID를 매칭하여 확장된 객체를 게시물 객체와 다시 연결할 수 있습니다.  각 파라미터의 가이드나 fields와 expansions 사용 방법에 대한 가이드를 읽어 보시기를 권장합니다.  또한 standard v1.1 필드를 새로운 v2 필드에 매핑하는 데 도움이 되는 데이터 형식 마이그레이션 가이드를 제공하고 있습니다. 이 가이드는 특정 필드를 반환하기 위해 v2 요청에 포함해야 하는 expansions 및 fields 파라미터도 구체적으로 안내합니다.    특정 필드를 요청하는 방식의 변경과 더불어, X API v2는 게시물 및 user 객체를 포함해 API가 반환하는 객체에 대해 새로운 JSON 구조를 도입하고 있습니다.
  • JSON 루트 레벨에서, standard 엔드포인트는 게시물 객체를 statuses 배열로 반환하는 반면, X API v2는 data 배열로 반환합니다. 
  • 리트윗 및 인용 “statuses”를 참조하는 대신, X API v2 JSON은 리트윗 및 인용 Tweet을 참조합니다. contributors 및 user.translator_type과 같은 많은 레거시 및 사용 중단 예정 필드는 제거되고 있습니다. 
  • 게시물 객체의 favorites와 사용자 객체의 favourites를 모두 사용하는 대신, X API v2는 like라는 용어만 사용합니다. 
  • X는 값이 없는 JSON 값(예: null)은 페이로드에 기록하지 않는 규칙을 채택하고 있습니다. 게시물 및 사용자 속성은 null이 아닌 값을 가진 경우에만 포함됩니다.   
또한 다음을 포함해 게시물 객체에 대한 새로운 필드 집합도 도입했습니다:
  • conversation_id 필드
  • context 및 entities를 포함하는 두 개의 새로운 annotations 필드
  • 여러 개의 새로운 metrics 필드
  • 특정 포스트에 누가 답글을 달 수 있는지를 보여주는 새로운 reply_setting 필드
요청 파라미터 또한 X API v2에서는 지원되지 않는 표준 필터링 스트림 요청 파라미터 집합이 있습니다.
표준 v1.1 파라미터세부 정보
locations - 쉼표로 구분된 longitude,latitude 쌍 목록으로, 포스트를 필터링할 경계 박스 집합을 지정합니다.X API v2에서는 아직 위치 기반 연산자를 제공하지 않습니다.
Delimitedv1.1 엔드포인트에서는 이를 문자열 길이로 설정하면, Client가 상태 메시지의 끝까지 읽어야 할 바이트 수를 알 수 있도록 스트림에서 status가 구분(delimit)되어야 함을 나타냅니다.

이 기능은 X API v2에서는 제공되지 않습니다.
Stall_warningsv1.1 엔드포인트에서는 이 파라미터를 true로 설정하면, Client가 연결이 끊길 위험이 있을 때 주기적으로 메시지가 전송됩니다.

X API v2에서는 새로운 줄이 일정 간격으로 전송되며, 기본적으로 지연 경고가 전송됩니다.
복구 및 중복 기능의 가용성 X API v2의 필터링 스트림 버전은 스트리밍 가동 시간을 최대화하고, 5분 이하의 연결 끊김으로 인해 놓쳤을 수 있는 포스트를 복구하는 데 도움이 되는 복구 및 중복 기능을 도입합니다. 중복(冗長) 연결을 사용하면 특정 스트림에 최대 두 번까지 연결할 수 있어, 두 연결 중 하나가 실패하더라도 항상 스트림에 대한 연결을 유지할 수 있습니다. backfill_minutes 파라미터는 최대 5분치 누락된 데이터를 복구하는 데 사용할 수 있습니다. 이 두 기능은 모두 Academic Research access를 통해서만 사용할 수 있습니다. 이 기능에 대한 자세한 내용은 recovery and redundancy features 통합 가이드를 참고하세요. 새로운 쿼리 연산자 X API v2는 두 가지 새로운 기능을 지원하기 위해 새로운 연산자를 도입합니다.
  • Conversation IDs - X에서 대화가 진행됨에 따라, 대화의 일부인 포스트를 표시하기 위한 conversation ID가 제공됩니다. 대화에 속한 모든 포스트는 해당 대화를 시작한 포스트의 ID를 conversation_id로 갖습니다.
    • conversation_id:
  • X Annotations 는 포스트에 대한 컨텍스트 정보를 제공하며, entity 및 context annotation을 포함합니다. entity에는 사람, 장소, 제품, 조직이 포함됩니다. context는 해당 entity가 속한 도메인 또는 토픽입니다. 예를 들어, 포스트에 언급된 사람은 운동선수, 배우, 정치인인지 여부를 나타내는 context를 가질 수 있습니다.
    • context: - 관심 있는 context로 annotation된 포스트와 일치합니다.
    • entity: - 관심 있는 entity로 annotation된 포스트와 일치합니다.

​
코드 예제

​
필터링된 스트림에 규칙 추가 (v2)

cURL
curl -X POST "https://api.x.com/2/tweets/search/stream/rules" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -H "Content-Type: "application/json" \
  -d '{"add": [{"value": "cat has:images", "tag": "cats with images"}]}'

​
필터된 스트림에 연결하기 (v2)

cURL
curl "https://api.x.com/2/tweets/search/stream?tweet.fields=created_at,author_id" \
  -H "Authorization: Bearer $BEARER_TOKEN"