빠른 시작

이 가이드는 필터 규칙과 일치하는 실시간 포스트를 받기 위해 필터링된 스트림에 연결하는 방법을 설명합니다.

사전 준비 사항시작하기 전에 다음이 필요합니다:

개발자 계정
개발자 콘솔의 “Keys and tokens”에서 확인할 수 있는 App의 Bearer 토큰

필터 규칙 만들기

규칙은 어떤 포스트를 받을지 정의합니다. 연산자를 사용해 키워드, 해시태그, 사용자 등을 기준으로 일치시킬 수 있습니다.예시 규칙: “cat”이 포함되어 있고 이미지가 있는 포스트와 일치:

cat has:images

규칙 만들기

규칙 구문과 연산자에 대해 알아보세요

스트림에 규칙을 추가하세요

규칙 엔드포인트를 사용해 규칙을 추가하세요. 어떤 규칙이 각 게시물과 일치했는지 식별할 수 있도록 tag를 포함하세요:

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"}
    ]
  }'

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

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

for rule in response.data:
    print(f"Rule added: {rule.id} - {rule.value}")

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

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

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

response.data?.forEach((rule) => {
  console.log(`Rule added: ${rule.id} - ${rule.value}`);
});

응답:

{
  "data": [
    {
      "id": "1273026480692322304",
      "value": "cat has:images",
      "tag": "cats with images"
    }
  ],
  "meta": {
    "sent": "2024-01-15T10:30:00.000Z",
    "summary": {
      "created": 1,
      "not_created": 0,
      "valid": 1,
      "invalid": 0
    }
  }
}

규칙을 확인하세요

모든 활성 규칙을 나열하여 규칙이 추가되었는지 확인하세요:

cURL

curl "https://api.x.com/2/tweets/search/stream/rules" \
  -H "Authorization: Bearer $BEARER_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# 모든 활성 규칙 가져오기
response = client.filtered_stream.get_rules()

for rule in response.data:
    print(f"활성 규칙: {rule.id} - {rule.value}")

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

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

// 모든 활성 규칙 가져오기
const response = await client.filteredStream.getRules();

response.data?.forEach((rule) => {
  console.log(`활성 규칙: ${rule.id} - ${rule.value}`);
});

스트림에 연결하기

일치하는 포스트를 받기 위해 지속 연결을 설정합니다:

cURL

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

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# 필터링된 스트림에 연결
for post in client.filtered_stream.stream(
    tweet_fields=["created_at", "author_id"],
    expansions=["author_id"],
    user_fields=["username"]
):
    print(f"New post: {post.data.text}")
    print(f"Matching rules: {post.matching_rules}")

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

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

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

for await (const post of stream) {
  console.log(`New post: ${post.data?.text}`);
  console.log(`Matching rules: ${post.matching_rules}`);
}

수신된 포스트 처리

일치하는 포스트 스트림(JSON 객체):

{
  "data": {
    "id": "1234567890",
    "text": "Look at this cute cat! 🐱",
    "author_id": "9876543210",
    "created_at": "2024-01-15T10:35:00.000Z",
    "edit_history_tweet_ids": ["1234567890"]
  },
  "includes": {
    "users": [
      {
        "id": "9876543210",
        "username": "catperson"
      }
    ]
  },
  "matching_rules": [
    {
      "id": "1273026480692322304",
      "tag": "cats with images"
    }
  ]
}

matching_rules 배열은 여러분이 정의한 태그를 기준으로 어떤 규칙이 이 게시물에 매칭되었는지 보여 줍니다.

규칙 삭제(선택 사항)

ID로 규칙 삭제:

cURL

curl -X POST "https://api.x.com/2/tweets/search/stream/rules" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "delete": {
      "ids": ["1273026480692322304"]
    }
  }'

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# ID로 규칙 삭제
response = client.filtered_stream.delete_rules(
    delete={"ids": ["1273026480692322304"]}
)
print(f"Deleted: {response.meta.summary.deleted}")

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

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

// ID로 규칙 삭제
const response = await client.filteredStream.deleteRules({
  delete: { ids: ["1273026480692322304"] },
});
console.log(`Deleted: ${response.meta?.summary?.deleted}`);

연결 관리하기

Keep-alive 신호

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

연결 해제

연결을 종료하려면 Ctrl+C를 누르거나 터미널 창을 닫으세요.

연결 제한

App당 하나의 연결만 허용됩니다. 새 연결을 열면 기존 연결은 자동으로 종료됩니다.

다음 단계

규칙 만들기

규칙 구문 알아보기

연산자 참조 문서

사용 가능한 모든 연산자

연결 끊김 처리

원활하게 재연결하기

API 참조 문서

전체 엔드포인트 문서

개요

포스트

사용자

다이렉트 메시지

좋아요

리스트

Spaces

커뮤니티

커뮤니티 노트

트렌드

뉴스

미디어

X 활동

사용량

스트림 연결

규정 준수

Enterprise v2

좋아요 스트림

GNIP 2.0

규칙 만들기

연결 관리하기

다음 단계

규칙 만들기

연산자 참조 문서

연결 끊김 처리

API 참조 문서