> ## Documentation Index > Fetch the complete documentation index at: https://generaltranslation.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # v1에서 v2로
### Standard v1.1와 X API v2 비교
v1.1 [statuses/filter](https://developer.x.com/en/docs/x-api/v1/tweets/filter-realtime/api-reference/post-statuses-filter) 엔드포인트를 사용해 왔다면, 이 가이드는 Standard v1.1과 X API v2 필터링 스트림 엔드포인트 간의 유사점과 차이점을 이해하는 데 도움이 됩니다. * **유사점** * 요청 매개변수와 연산자 * 게시물 편집 기록 및 메타데이터 지원 * **차이점** * 엔드포인트 URL * App 및 Project 요구 사항 * 인증 방식 * 규칙 수 제한 및 상시 스트림 * 응답 데이터 형식 * 요청 매개변수 * 복구 및 이중화 기능 제공 여부 * 쿼리 연산자
#### 유사점
**요청 매개변수와 연산자** 표준 v1.1 `statuses/filter` 엔드포인트에는 스트림을 필터링하기 위해 요청과 함께 전달할 수 있는 몇 가지 매개변수가 있습니다. v2 필터링된 스트림에서는 대신, 원하는 포스트를 필터링하기 위해 불리언 로직으로 서로 연결할 수 있는 [연산자](/ko/x-api/posts/filtered-stream#building-rules-for-filtered-stream) 집합을 사용합니다. 사용 가능한 연산자에는 기존 표준 v1.1 매개변수를 직접 대체하는 것들도 포함됩니다.  다음 표준 v1.1 요청 매개변수는 X API v2에서 이에 해당하는 연산자가 있습니다:   | **Standard** | **X API v2** | | :---------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------- | | follow - 쉼표로 구분된 사용자 ID 목록으로, 스트림에 포스트를 전달해야 하는 사용자를 나타냅니다. | 특정 사용자와 관련된 포스트를 찾는 데 도움이 되는 여러 연산자:

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

\* keyword
\* "exact phrase match"
\* #
\* 등 | **포스트 편집 기록 및 메타데이터 지원** 두 버전 모두 편집 이력을 설명하는 메타데이터를 제공합니다. 자세한 내용은 [필터링된 스트림 API 참조 문서](/ko/x-api/posts/filtered-stream#api-reference-index)와 [포스트 편집 기본 사항 페이지](/ko/x-api/fundamentals/edit-posts)를 참고하세요. 
#### Differences
**엔드포인트 URL** * Standard v1.1 엔드포인트: * [https://stream.x.com/1.1/statuses/filter.json](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) * [https://api.x.com/2/tweets/search/stream/rule](https://api.x.com/2/tweets/search/stream/rule) **App 및 Project 요구 사항** X API v2 엔드포인트를 사용하려면 요청을 인증할 때 [developer App](/ko/resources/fundamentals/developer-apps) 자격 증명 중 [Project](/ko/resources/fundamentals/developer-apps)와 연결된 자격 증명을 사용해야 합니다. 모든 X API v1.1 엔드포인트는 개별 App 또는 Project와 연결된 App의 자격 증명을 사용할 수 있습니다. **인증 방식** Standard 엔드포인트는 [OAuth 1.0a User Context](/ko/resources/fundamentals/authentication)를 지원하는 반면, X API v2 필터링 스트림 엔드포인트는 [OAuth 2.0 App-Only](/ko/resources/fundamentals/authentication#oauth-2-0) (Application-only authentication이라고도 함)을 지원합니다. X API v2 버전으로 요청을 보내려면 App Access Token을 사용하여 요청을 인증해야 합니다. 개발자 콘솔에서 App을 생성할 때 제공되었던 App Access Token이 더 이상 없다면, 개발자 콘솔에서 해당 앱의 “Keys and tokens” 페이지로 이동하여 새 토큰을 생성할 수 있습니다. App Access Token을 프로그래밍 방식으로 생성하려면 이 [OAuth 2.0 App-Only 가이드](/ko/resources/fundamentals/authentication#app-only-authentication-and-oauth-2-0-bearer-token)를 참조하세요.  **규칙 개수 및 지속 스트림** Standard v1.1 엔드포인트는 스트리밍 연결을 필터링하기 위한 단일 규칙만 지원합니다. 규칙을 변경하려면 스트림 연결을 끊고, 수정된 필터링 규칙을 파라미터로 포함하여 새 요청을 제출해야 합니다.  X API v2 필터링 스트림 엔드포인트는 단일 스트림에 여러 규칙을 적용할 수 있으며, 스트림 연결을 유지한 상태에서 스트림에 대한 규칙을 추가하거나 제거할 수 있습니다.  **응답 데이터 형식** Standard v1.1과 X API v2 엔드포인트 버전 간의 가장 큰 차이점 중 하나는 페이로드에 어떤 필드를 포함할지 선택하는 방식입니다. Standard 엔드포인트의 경우, 응답 필드 대부분을 기본적으로 받게 되며, 이후 파라미터를 사용해 어떤 필드 또는 필드 집합을 페이로드에 포함할지 선택할 수 있습니다. X API v2 버전은 기본적으로 게시물 id 및 text 필드만 제공합니다. 추가 필드나 객체를 요청하려면 [fields](/ko/x-api/fundamentals/fields) 및 [expansions](/ko/x-api/fundamentals/expansions) 파라미터를 사용해야 합니다. 이러한 엔드포인트에서 요청한 게시물 필드는 기본 게시물 객체에 포함되어 반환됩니다. 확장된 사용자, 미디어, 설문조사(poll), 장소(place) 객체 및 필드는 응답 내 includes 객체에 포함되어 반환됩니다. 이후 게시물과 확장된 객체 양쪽에 있는 ID를 매칭하여 확장된 객체를 게시물 객체와 다시 연결할 수 있습니다.  각 파라미터의 가이드나 [fields와 expansions 사용 방법](/ko/x-api/fundamentals/data-dictionary#how-to-use-fields-and-expansions)에 대한 가이드를 읽어 보시기를 권장합니다.  또한 standard v1.1 필드를 새로운 v2 필드에 매핑하는 데 도움이 되는 [데이터 형식 마이그레이션 가이드](/ko/x-api/migrate/data-format-migration#migrating-from-standard-v1-1s-data-format-to-v2)를 제공하고 있습니다. 이 가이드는 특정 필드를 반환하기 위해 v2 요청에 포함해야 하는 expansions 및 fields 파라미터도 구체적으로 안내합니다.    특정 필드를 요청하는 방식의 변경과 더불어, X API v2는 게시물 및 [user](/ko/x-api/fundamentals/data-dictionary#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이 아닌 값을 가진 경우에만 포함됩니다.    또한 다음을 포함해 [게시물 객체](/ko/x-api/fundamentals/data-dictionary#tweet)에 대한 새로운 필드 집합도 도입했습니다: * [conversation\_id](/ko/x-api/fundamentals/conversation-id) 필드 * context 및 entities를 포함하는 두 개의 새로운 [annotations](/ko/x-api/fundamentals/post-annotations) 필드 * 여러 개의 새로운 [metrics](/ko/x-api/fundamentals/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](/ko/x-api/getting-started/about-x-api)를 통해서만 사용할 수 있습니다. 이 기능에 대한 자세한 내용은 [recovery and redundancy features](/ko/x-api/posts/filtered-stream#filtered-stream-recovery-and-redundancy-features) 통합 가이드를 참고하세요. **새로운 쿼리 연산자** X API v2는 두 가지 새로운 기능을 지원하기 위해 새로운 연산자를 도입합니다. * **[Conversation IDs](/ko/x-api/fundamentals/conversation-id)** - X에서 대화가 진행됨에 따라, 대화의 일부인 포스트를 표시하기 위한 conversation ID가 제공됩니다. 대화에 속한 모든 포스트는 해당 대화를 시작한 포스트의 ID를 conversation\_id로 갖습니다. * conversation\_id: * **[X Annotations](/ko/x-api/fundamentals/post-annotations)** 는 포스트에 대한 컨텍스트 정보를 제공하며, entity 및 context annotation을 포함합니다. entity에는 사람, 장소, 제품, 조직이 포함됩니다. context는 해당 entity가 속한 도메인 또는 토픽입니다. 예를 들어, 포스트에 언급된 사람은 운동선수, 배우, 정치인인지 여부를 나타내는 context를 가질 수 있습니다. * context: - 관심 있는 context로 annotation된 포스트와 일치합니다. * entity: - 관심 있는 entity로 annotation된 포스트와 일치합니다. ***
## 코드 예제
### 필터링된 스트림에 규칙 추가 (v2)
```bash cURL theme={null} 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"}]}' ``` ```python Python theme={null} 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()) ``` ```python Python SDK theme={null} 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) ``` ```javascript JavaScript SDK theme={null} 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)
```bash cURL theme={null} curl "https://api.x.com/2/tweets/search/stream?tweet.fields=created_at,author_id" \ -H "Authorization: Bearer $BEARER_TOKEN" ``` ```python Python theme={null} 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")) ``` ```python Python SDK theme={null} 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]}...") ``` ```javascript JavaScript SDK theme={null} 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)}...`); } ```