규칙 작성

Filtered stream 엔드포인트는 스트림에 적용된 일련의 규칙에 매칭되는 게시물을 전달합니다. 규칙은 다양한 게시물 속성에 매칭되는 연산자로 구성됩니다. 여러 규칙은 POST /tweets/search/stream/rules 엔드포인트를 통해 적용할 수 있습니다. 규칙을 추가하고 GET /tweets/search/stream을 사용해 연결한 뒤에는, 규칙에 매칭되는 게시물만 전달됩니다. 규칙을 추가하거나 제거하기 위해 연결을 끊을 필요는 없습니다.

규칙 제한 사항

규칙 수 제한은 access level에 따라 달라집니다. 구체적인 제한은 filtered stream 소개를 참고하세요.

연산자 유형: standalone 및 conjunction-required

Standalone 연산자는 단독으로 사용하거나, conjunction이 필요한 연산자를 포함한 다른 연산자들과 함께 사용할 수 있습니다. 예를 들어, #hashtag는 standalone 연산자이므로 다음 규칙이 정상 동작합니다:

#xapiv2

Conjunction-required 연산자는 규칙에서 단독으로 사용할 수 없으며, 최소 하나 이상의 standalone 연산자가 포함되어야만 사용할 수 있습니다. 이는 이러한 연산자를 단독으로 사용할 경우 매우 많은 양의 게시물이 매칭되기 때문입니다. 예를 들어, 다음 규칙들은 conjunction-required 연산자만 포함하고 있으므로 지원되지 않습니다:

has:media

has:links OR is:retweet

embedding_threshold:0.45

여기에 "X data"와 같은 standalone 연산자를 추가하면 규칙이 정상 동작합니다:

"X data" has:mentions (has:media OR has:links)

embedding_threshold: 연산자(시맨틱 embedding: 규칙과 함께 사용)도 conjunction-required입니다.

Boolean 연산자와 그룹화

다음 도구를 사용해 여러 연산자를 조합할 수 있습니다:

Operator	Description	Example
AND (공백)	두 조건을 모두 매칭해야 함	`snow day #NoSchool`은 “snow” AND “day” AND #NoSchool을 포함한 게시물에 매칭
OR	두 조건 중 하나라도 매칭	`grumpy OR cat OR #meme`은 “grumpy” OR “cat” OR #meme을 포함한 게시물에 매칭
NOT (대시)	이 조건에 매칭되는 게시물 제외	`cat #meme -grumpy`는 “cat”과 #meme을 포함하지만 “grumpy”는 포함하지 않는 게시물에 매칭
그룹화 (괄호)	연산자를 하나로 묶음	`(grumpy cat) OR (#meme has:images)`는 두 그룹 중 하나에 매칭

부정 관련 참고 사항

sample: 및 embedding:을 제외한 모든 연산자를 부정할 수 있습니다
-is:nullcast 연산자는 반드시 부정된 형태로만 사용해야 합니다
부정된 연산자는 단독으로 사용할 수 없습니다
그룹화된 연산자를 부정하지 마세요. skiing -(snow OR day OR noschool) 대신 skiing -snow -day -noschool을 사용하세요
-embedding:"query"는 지원되지 않습니다

연산 우선순위

AND와 OR를 함께 사용할 때:

AND 로직으로 연결된 연산자가 먼저 결합됩니다
그 다음 OR 로직으로 연결된 연산자가 적용됩니다

예시:

Query	Evaluated as
`apple OR iphone ipad`	`apple OR (iphone ipad)`
`ipad iphone OR android`	`(iphone ipad) OR android`

모호함을 없애려면 괄호를 사용하세요:

(apple OR iphone) ipad

iphone (ipad OR android)

구두점, 발음 구별 부호, 대소문자 구분

발음 구별 부호: 악센트가 포함된 filtered stream 규칙은 악센트가 포함된 게시물에만 매칭됩니다. 예를 들어 diacrítica는 _diacrítica_에 매칭되지만 _diacritica_에는 매칭되지 않습니다. 대소문자 구분: 모든 연산자는 대소문자를 구분하지 않습니다. cat 규칙은 cat, CAT, _Cat_에 모두 매칭됩니다.

Search Posts는 다르게 동작합니다search 쿼리 작성 시, 악센트가 포함된 키워드는 악센트가 있는 게시물과 없는 게시물 모두에 매칭됩니다. 예를 들어 Diacrítica는 _Diacrítica_와 _Diacritica_에 모두 매칭됩니다.

Quote Tweet 매칭

filtered stream을 사용할 때, 연산자는 Quote Tweet의 콘텐츠 및 인용된 원본 게시물의 콘텐츠 모두에 매칭됩니다.

Search Posts는 다르게 동작합니다—Quote Tweet의 콘텐츠에만 매칭되고 원본 게시물에는 매칭되지 않습니다.

구체성 및 효율성

단일 키워드나 해시태그와 같은 광범위한 연산자를 사용하는 것은 권장되지 않습니다—엄청난 양의 게시물이 매칭되어 연결을 빠르게 소진하게 됩니다.

효과적인 규칙 작성을 위한 팁:

구체적으로 시작한 뒤 확장하기 — 관련성 있는 결과를 반환하는 타깃형 규칙을 만드세요
여러 연산자 사용하기 — 연산자를 조합해 결과 범위를 좁히세요
문자 수 확인하기 — 규칙 문자열 전체가 제한에 포함됩니다

예시 진행:

# Too broad - 200,000+ Posts per day
happy

# Better - adds language filter and exclusions
(happy OR happiness) lang:en -birthday -is:retweet

# Even better - 59 characters, more specific
(happy OR happiness) place_country:GB -birthday -is:retweet

반복적으로 규칙 다듬기

1단계: 기본 규칙으로 시작

happy OR happiness

2단계: 결과를 기반으로 테스트 및 범위 좁히기

여러 언어의 게시물이 있었습니다. 언어 필터를 추가합니다:

(happy OR happiness) lang:en

생일 인사가 반환됩니다. 이를 제외하고 리트윗도 제외합니다:

(happy OR happiness) lang:en -birthday -is:retweet

3단계: 커버리지 확장

더 많은 감정을 포착하고 싶습니다. 관련 키워드를 추가합니다:

(happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet

4단계: 트렌드에 맞춰 조정

Holiday 게시물이 등장합니다. 이를 제외합니다:

(happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet -holidays

규칙 추가 및 제거

규칙을 추가하거나 제거하려면 POST /2/tweets/search/stream/rules를 사용하세요.

규칙 추가

value(규칙)와 선택적 tag(매칭 게시물을 식별하기 위한 값)를 포함한 add JSON 본문을 전송합니다:

curl -X POST "https://api.x.com/2/tweets/search/stream/rules" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "add": [
      {"value": "cat has:media", "tag": "cats with media"},
      {"value": "cat has:media -grumpy", "tag": "happy cats with media"},
      {"value": "meme", "tag": "funny things"},
      {"value": "meme has:images"}
    ]
  }'

규칙 제거

제거할 규칙 ID를 포함한 delete JSON 본문을 전송합니다:

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

규칙 예시

자연재해 추적

허리케인 Harvey에 대한 기상 기관의 게시물에 매칭:

{
  "value": "-is:retweet has:geo (from:NWSNHC OR from:NHC_Atlantic OR from:NWSHouston OR from:NWSSanAntonio OR from:USGS_TexasRain OR from:USGS_TexasFlood OR from:JeffLindner1)",
  "tag": "Hurricane Harvey - weather agencies with geo"
}

#nowplaying에 대한 감성 분석

긍정 감성:

{
  "value": "#nowplaying (happy OR exciting OR excited OR favorite OR fav OR amazing OR lovely OR incredible) (place_country:US OR place_country:MX OR place_country:CA) -horrible -worst -sucks -bad -disappointing",
  "tag": "#nowplaying positive"
}

부정 감성:

{
  "value": "#nowplaying (horrible OR worst OR sucks OR bad OR disappointing) (place_country:US OR place_country:MX OR place_country:CA) -happy -exciting -excited -favorite -fav -amazing -lovely -incredible",
  "tag": "#nowplaying negative"
}

Post annotations 사용

context: 연산자를 사용해 이미지가 있는 일본어 게시물 중 반려동물 관련(고양이 제외)을 찾기: 먼저 tweet.fields=context_annotations와 함께 Post lookup을 사용해 domain.entity ID를 확인합니다:

Cats: domain 66, entity 852262932607926273
Pets: domain 65, entity 852262932607926273

{
  "value": "context:65.852262932607926273 -context:66.852262932607926273 -is:retweet has:images lang:ja",
  "tag": "Japanese pets with images - no cats"
}

임베딩을 이용한 시맨틱 매칭 (Enterprise)

embedding: 연산자를 사용해 키워드가 아닌 개념적 의미로 게시물을 매칭합니다. Enterprise + Embedding 티어가 필요합니다.

{
  "value": "embedding:\"climate change policy\" embedding_threshold:0.4",
  "tag": "climate-semantic"
}

정밀도를 위해 구조적 연산자와 결합할 수 있습니다:

{
  "value": "embedding:\"quarterly earnings surprises\" lang:en has:links -is:retweet",
  "tag": "earnings-en"
}

전체 세부사항과 모범 사례는 연산자 레퍼런스를 참고하세요.

다음 단계

연산자 레퍼런스

사용 가능한 연산자 전체 목록

Filtered stream 퀵스타트

스트림에 연결하기

샘플 코드

여러 언어로 된 코드 예제

Getting Started

Products

Fundamentals

Partners & Customers

Resources

규칙 제한 사항

연산자 유형: standalone 및 conjunction-required

Boolean 연산자와 그룹화

연산 우선순위

구두점, 발음 구별 부호, 대소문자 구분

Quote Tweet 매칭

구체성 및 효율성

반복적으로 규칙 다듬기

1단계: 기본 규칙으로 시작

2단계: 결과를 기반으로 테스트 및 범위 좁히기

3단계: 커버리지 확장

4단계: 트렌드에 맞춰 조정

규칙 추가 및 제거

규칙 추가

규칙 제거

규칙 예시

자연재해 추적

#nowplaying에 대한 감성 분석

Post annotations 사용

임베딩을 이용한 시맨틱 매칭 (Enterprise)

다음 단계

연산자 레퍼런스

Filtered stream 퀵스타트

샘플 코드

​규칙 제한 사항

​연산자 유형: standalone 및 conjunction-required

​Boolean 연산자와 그룹화

​연산 우선순위

​구두점, 발음 구별 부호, 대소문자 구분

​Quote Tweet 매칭

​구체성 및 효율성

​반복적으로 규칙 다듬기

​1단계: 기본 규칙으로 시작

​2단계: 결과를 기반으로 테스트 및 범위 좁히기

​3단계: 커버리지 확장

​4단계: 트렌드에 맞춰 조정

​규칙 추가 및 제거

​규칙 추가

​규칙 제거

​규칙 예시

​자연재해 추적

​#nowplaying에 대한 감성 분석

​Post annotations 사용

​임베딩을 이용한 시맨틱 매칭 (Enterprise)

​다음 단계

연산자 레퍼런스

Filtered stream 퀵스타트

샘플 코드

규칙 제한 사항

연산자 유형: standalone 및 conjunction-required

Boolean 연산자와 그룹화

연산 우선순위

구두점, 발음 구별 부호, 대소문자 구분

Quote Tweet 매칭

구체성 및 효율성

반복적으로 규칙 다듬기

1단계: 기본 규칙으로 시작

2단계: 결과를 기반으로 테스트 및 범위 좁히기

3단계: 커버리지 확장

4단계: 트렌드에 맞춰 조정

규칙 추가 및 제거

규칙 추가

규칙 제거

규칙 예시

자연재해 추적

#nowplaying에 대한 감성 분석

Post annotations 사용

임베딩을 이용한 시맨틱 매칭 (Enterprise)

다음 단계