v1에서 v2로

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에서 이에 해당하는 연산자가 있습니다:

Standard	X API v2
follow - 쉼표로 구분된 사용자 ID 목록으로, 스트림에 포스트를 전달해야 하는 사용자를 나타냅니다.	특정 사용자와 관련된 포스트를 찾는 데 도움이 되는 여러 연산자: * @ * from: * to: * 등
track - 스트림에 전달할 포스트를 결정하는 데 사용되는, 쉼표로 구분된 문구 목록입니다.	특정 키워드와 관련된 포스트를 찾는 데 도움이 되는 여러 연산자: * keyword * “exact phrase match” * # * 등

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

Differences

엔드포인트 URL

Standard v1.1 엔드포인트:
- https://stream.x.com/1.1/statuses/filter.json
X API v2 엔드포인트:
- https://api.x.com/2/tweets/search/stream
- https://api.x.com/2/tweets/search/stream/rule

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에서는 아직 위치 기반 연산자를 제공하지 않습니다.
Delimited	v1.1 엔드포인트에서는 이를 문자열 길이로 설정하면, Client가 상태 메시지의 끝까지 읽어야 할 바이트 수를 알 수 있도록 스트림에서 status가 구분(delimit)되어야 함을 나타냅니다. 이 기능은 X API v2에서는 제공되지 않습니다.
Stall_warnings	v1.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"}]}'

import requests

bearer_token = "YOUR_BEARER_TOKEN"
url = "https://api.x.com/2/tweets/search/stream/rules"

headers = {
    "Authorization": f"Bearer {bearer_token}",
    "Content-Type": "application/json"
}

data = {
    "add": [{"value": "cat has:images", "tag": "cats with images"}]
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# 필터링된 스트림에 규칙 추가
response = client.posts.add_stream_rules(
    add=[{"value": "cat has:images", "tag": "cats with images"}]
)
print(response.data)

import { Client } from "@xdevplatform/xdk";

const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

// 필터링된 스트림에 규칙 추가
const response = await client.posts.addStreamRules({
  add: [{ value: "cat has:images", tag: "cats with images" }],
});
console.log(response.data);

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

cURL

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

import requests

bearer_token = "YOUR_BEARER_TOKEN"
url = "https://api.x.com/2/tweets/search/stream"

params = {"tweet.fields": "created_at,author_id"}
headers = {"Authorization": f"Bearer {bearer_token}"}

# 실시간으로 포스트 스트리밍
response = requests.get(url, headers=headers, params=params, stream=True)
for line in response.iter_lines():
    if line:
        print(line.decode("utf-8"))

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# 필터된 스트림에 연결
for post in client.posts.stream(
    tweet_fields=["created_at", "author_id"]
):
    print(f"{post.data.created_at}: {post.data.text[:50]}...")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

// 필터된 스트림에 연결
const stream = client.posts.stream({
  tweetFields: ["created_at", "author_id"],
});

for await (const post of stream) {
  console.log(`${post.data?.created_at}: ${post.data?.text?.slice(0, 50)}...`);
}

Getting Started

Fundamentals

Partners & Customers

Resources

v1에서 v2로

Standard v1.1와 X API v2 비교

유사점

Differences

코드 예제

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

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

​Standard v1.1와 X API v2 비교

​유사점

​Differences

​코드 예제

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

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

Standard v1.1와 X API v2 비교

유사점

Differences

코드 예제

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

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