> ## 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.

# 필터링된 스트림

> 필터 규칙과 일치하는 실시간 게시물을 스트리밍합니다

export const Button = ({href, children}) => {
  return <div className="not-prose group">
    <a href={href}>
      <button className="flex items-center space-x-2.5 py-1 px-4 bg-primary-dark dark:bg-white text-white dark:text-gray-950 rounded-full group-hover:opacity-[0.9] font-medium">
        <span>
          {children}
        </span>
        <svg width="3" height="24" viewBox="0 -9 3 24" class="h-6 rotate-0 overflow-visible"><path d="M0 0L3 3L0 6" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"></path></svg>
      </button>
    </a>
  </div>;
};

Filtered Stream 엔드포인트를 사용하면 필터 규칙과 일치하는 실시간 포스트를 받아볼 수 있습니다. 강력한 연산자를 사용해 규칙을 만든 다음, 지속적인 스트림에 연결하여 게시될 때마다 일치하는 포스트를 받아 보세요.

<div id="overview">
  ## 개요
</div>

<CardGroup cols={2}>
  <Card title="실시간 전달" icon="bolt">
    게시된 후 몇 초 이내에 포스트를 수신합니다
  </Card>

  <Card title="지속 규칙" icon="filter">
    연결을 끊지 않고도 규칙을 추가하거나 제거할 수 있습니다
  </Card>

  <Card title="강력한 연산자" icon="magnifying-glass">
    키워드, 해시태그, 사용자 등으로 매칭합니다
  </Card>

  <Card title="웹훅 전달" icon="webhook">
    선택적으로 웹훅을 통해 포스트를 수신합니다
  </Card>
</CardGroup>

***

<div id="how-it-works">
  ## 동작 방식
</div>

1. **규칙 생성** — 연산자를 사용하여 필터 규칙을 정의합니다
2. **스트림 연결** — 지속적인 HTTP 연결을 설정합니다
3. **포스트 수신** — 일치하는 포스트를 실시간으로 수신합니다

```
┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│ Create/     │      │ Connect to  │      │ Receive     │
│ manage      │  →   │ streaming   │  →   │ matching    │
│ rules       │      │ endpoint    │      │ Posts       │
└─────────────┘      └─────────────┘      └─────────────┘
```

***

<div id="endpoints">
  ## 엔드포인트
</div>

| 메서드  | 엔드포인트                                                                   | 설명              |
| :--- | :---------------------------------------------------------------------- | :-------------- |
| GET  | [`/2/tweets/search/stream`](/ko/x-api/stream/stream-filtered-posts)     | 스트림에 연결합니다      |
| POST | [`/2/tweets/search/stream/rules`](/ko/x-api/stream/update-stream-rules) | 규칙을 추가하거나 삭제합니다 |
| GET  | [`/2/tweets/search/stream/rules`](/ko/x-api/stream/get-stream-rules)    | 현재 규칙을 조회합니다    |

***

<div id="access-levels">
  ## 액세스 수준
</div>

| 기능         | 사용량 기반 과금 | Enterprise |
| :--------- | :-------- | :--------- |
| 프로젝트당 규칙 수 | 1,000     | 25,000+    |
| 규칙 길이      | 1,024자    | 2,048자     |
| 연결 수       | 1         | 여러 개       |
| 모든 연산자     | ✓         | ✓          |

<Card title="Enterprise 문의" icon="building" href="https://developer.x.com/en/products/x-api/enterprise/enterprise-api-interest-form">
  더 높은 한도와 추가 기능을 이용해 보세요
</Card>

***

<div id="building-rules">
  ## 규칙 작성
</div>

규칙은 검색 쿼리와 동일한 연산자를 사용합니다.

```
(AI OR "machine learning") lang:en -is:retweet
```

<div id="example-rules">
  ### 규칙 예시
</div>

| 규칙                                 | 매칭 대상                  |
| :--------------------------------- | :--------------------- |
| `#python`                          | #python 해시태그가 있는 포스트   |
| `from:elonmusk`                    | @elonmusk가 작성한 포스트     |
| `"breaking news" has:images`       | 해당 문구와 이미지를 모두 포함한 포스트 |
| `(@XDevelopers OR @X) -is:retweet` | 리트윗을 제외한 멘션 포스트        |

<Card title="규칙 만들기" icon="filter" href="/ko/x-api/posts/filtered-stream/integrate/build-a-rule">
  규칙 문법과 연산자에 대해 알아보기
</Card>

***

<div id="connecting-to-the-stream">
  ## 스트림에 연결하기
</div>

포스트를 수신하기 위해 지속적인 HTTP 연결을 설정합니다.

```python theme={null}
import requests

def stream_posts(bearer_token):
    url = "https://api.x.com/2/tweets/search/stream"
    headers = {"Authorization": f"Bearer {bearer_token}"}
    
    response = requests.get(url, headers=headers, stream=True)
    
    for line in response.iter_lines():
        if line:
            print(line.decode("utf-8"))
```

<div id="keep-alive-signals">
  ### Keep-alive 신호
</div>

스트림은 연결을 유지하기 위해 20초마다 빈 줄(`\r\n`)을 전송합니다. 20초 동안 데이터나 keep-alive 신호를 받지 못하면 재연결하십시오.

<CardGroup cols={2}>
  <Card title="연결 끊김 처리" icon="plug" href="/ko/x-api/posts/filtered-stream/integrate/handling-disconnections">
    원활하게 재연결하기
  </Card>

  <Card title="스트리밍 데이터 처리" icon="stream" href="/ko/x-api/posts/filtered-stream/integrate/consuming-streaming-data">
    포스트를 효율적으로 처리하기
  </Card>
</CardGroup>

***

<div id="webhook-delivery">
  ## Webhook 전달
</div>

지속적인 연결을 유지하는 대신, webhook을 통해 포스트를 수신할 수 있습니다.

<Card title="Webhook 전달" icon="webhook" href="/ko/x-api/webhooks/stream/introduction">
  필터 스트림용 webhook 전달 설정
</Card>

***

<div id="post-edits">
  ## 게시물 편집
</div>

이 스트림은 편집된 포스트와 해당 편집 내역을 제공합니다. 각 편집마다 새로운 게시물 ID가 생성됩니다:

```json theme={null}
{
  "data": {
    "id": "1234567893",
    "text": "Hello world! (edited)",
    "edit_history_tweet_ids": ["1234567890", "1234567891", "1234567893"]
  }
}
```

<Card title="포스트 편집 기본사항" icon="clock-rotate-left" href="/ko/x-api/fundamentals/edit-posts">
  게시물 편집에 대해 자세히 알아보기
</Card>

***

<div id="getting-started">
  ## 시작하기
</div>

<Note>
  **사전 준비 사항**

  * 승인된 [개발자 계정](https://developer.x.com/en/portal/petition/essential/basic-info)
  * 개발자 콘솔의 [Project와 App](/ko/resources/fundamentals/developer-apps)
  * App의 [Bearer 토큰](/ko/resources/fundamentals/authentication)
</Note>

<CardGroup cols={2}>
  <Card title="빠른 시작" icon="rocket" href="/ko/x-api/posts/filtered-stream/quickstart">
    몇 분 안에 스트림에 연결하세요
  </Card>

  <Card title="규칙 생성" icon="filter" href="/ko/x-api/posts/filtered-stream/integrate/build-a-rule">
    규칙 구문 살펴보기
  </Card>

  <Card title="연산자 참조" icon="list-check" href="/ko/x-api/posts/filtered-stream/integrate/operators">
    사용 가능한 모든 연산자
  </Card>

  <Card title="샘플 코드" icon="github" href="https://github.com/xdevplatform/Twitter-API-v2-sample-code">
    실행 가능한 코드 예제
  </Card>
</CardGroup>

***

<div id="advanced-topics">
  ## 고급 주제
</div>

<CardGroup cols={2}>
  <Card title="연결 끊김 처리" icon="plug" href="/ko/x-api/posts/filtered-stream/integrate/handling-disconnections">
    안정적으로 재연결하기
  </Card>

  <Card title="대용량 처리 용량" icon="gauge-high" href="/ko/x-api/posts/filtered-stream/integrate/handling-high-volume-capacity">
    높은 처리량 처리하기
  </Card>

  <Card title="복구 및 이중화" icon="shield" href="/ko/x-api/posts/filtered-stream/integrate/recovery-and-redundancy-features">
    탄력적인 애플리케이션 구축
  </Card>

  <Card title="반환된 포스트 매칭" icon="crosshairs" href="/ko/x-api/posts/filtered-stream/integrate/matching-returned-tweets">
    어떤 규칙이 일치했는지 식별하기
  </Card>
</CardGroup>