퀵스타트

이 가이드는 filtered stream에 연결하여 필터 규칙과 매칭되는 게시물을 거의 실시간으로 수신하는 방법을 안내합니다.

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

developer account
App의 Bearer Token(Developer Console의 “Keys and tokens”에서 확인)

필터 규칙 생성

규칙은 어떤 게시물을 수신할지 정의합니다. keywords, hashtags, users 등을 매칭하는 데 연산자를 사용하세요.예시 규칙: 이미지가 포함된 “cat” 게시물 매칭:

cat has:images

규칙 작성

규칙 구문 및 연산자 익히기

스트림에 규칙 추가

rules 엔드포인트를 사용해 규칙을 추가합니다. 각 게시물이 어떤 규칙에 매칭됐는지 식별할 수 있도록 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")

# Add a rule to the filtered stream
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" });

// Add a rule to the filtered stream
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")

# Get all active rules
response = client.filtered_stream.get_rules()

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

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

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

// Get all active rules
const response = await client.filteredStream.getRules();

response.data?.forEach((rule) => {
  console.log(`Active rule: ${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")

# Connect to the filtered stream
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" });

// Connect to the filtered stream
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 배열은 정의한 tag를 사용해 어떤 규칙이 게시물에 매칭되었는지 보여줍니다.

규칙 삭제 (선택 사항)

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")

# Delete rules by 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" });

// Delete rules by 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 레퍼런스

전체 엔드포인트 문서

Getting Started

Products

Fundamentals

Partners & Customers

Resources

규칙 작성

연결 관리

다음 단계

규칙 작성

연산자 레퍼런스

연결 끊김 처리

API 레퍼런스

규칙 작성

​연결 관리

​다음 단계

규칙 작성

연산자 레퍼런스

연결 끊김 처리

API 레퍼런스

연결 관리

다음 단계