규칙 만들기

연산자를 사용하여 필터링된 스트림 규칙을 만드는 방법 알아보기

필터링된 스트림 엔드포인트는 스트림에 적용된 일련의 규칙과 일치하는 포스트를 전달합니다. 규칙은 다양한 포스트 속성과 일치하도록 동작하는 연산자로 구성됩니다.

여러 규칙은 POST /tweets/search/stream/rules 엔드포인트를 사용해 적용할 수 있습니다. 규칙을 추가하고 GET /tweets/search/stream으로 스트림에 연결한 후에는 규칙과 일치하는 포스트만 전달됩니다. 규칙을 추가하거나 제거하기 위해 연결을 끊을 필요는 없습니다.

---

규칙 제한 사항

규칙 수에 대한 제한은 사용 중인 액세스 레벨에 따라 달라집니다. 구체적인 한도는 필터링 스트림 소개를 참고하세요.

---

연산자 유형: 독립형과 결합 필요

독립형 연산자는 단독으로 사용하거나 (결합이 필요한 연산자를 포함해) 다른 어떤 연산자와도 함께 사용할 수 있습니다.

예를 들어, 이 규칙은 #hashtag가 독립형 연산자이기 때문에 동작합니다:

#xapiv2

연결 필수 연산자는 규칙에서 단독으로 사용할 수 없으며, 최소 한 개 이상의 단독 연산자와 함께 사용할 때만 사용할 수 있습니다. 이는 이러한 연산자를 단독으로 사용하면 매우 방대한 양의 포스트와 일치하게 되기 때문입니다.

예를 들어, 다음 규칙들은 연결 필수 연산자만 포함하고 있으므로 지원되지 않습니다:

has:media

has:links OR is:retweet

"X data"와 같은 단독 연산자를 추가하면 규칙이 제대로 동작합니다:

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

---

불리언 연산자와 그룹화

다음 도구를 사용해 여러 연산자를 함께 연결할 수 있습니다:

Operator	Description	Example
AND (space)	포스트가 두 조건을 모두 만족해야 합니다	snow day #NoSchool은 “snow” AND “day” AND #NoSchool이 모두 포함된 포스트와 일치합니다
OR	포스트가 두 조건 중 하나만 만족해도 됩니다	grumpy OR cat OR #meme은 “grumpy” OR “cat” OR #meme 중 하나라도 포함된 포스트와 일치합니다
NOT (dash)	이 조건과 일치하는 포스트를 제외합니다	cat #meme -grumpy는 “cat”과 #meme은 포함하지만 “grumpy”는 포함하지 않는 포스트와 일치합니다
Grouping (parentheses)	연산자를 그룹으로 묶습니다	(grumpy cat) OR (#meme has:images)는 두 그룹 중 하나와 일치합니다

부정(negation)에 대한 참고 사항

• sample:을 제외한 모든 연산자는 부정할 수 있습니다.
• 연산자 -is:nullcast는 항상 부정형이어야 합니다.
• 부정 연산자는 단독으로 사용할 수 없습니다.
• 그룹화된 연산자는 부정하지 마세요. skiing -(snow OR day OR noschool) 대신 skiing -snow -day -noschool을 사용하세요.

---

연산 순서

AND와 OR을 함께 사용할 때는:

1. AND 논리로 연결된 연산자가 먼저 결합됩니다.
2. 그다음 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)

---

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

발음 구별 부호(diacritics): 발음 구별 부호가 포함된 필터 스트림 규칙은 해당 부호가 포함된 포스트에만 일치합니다. 예를 들어, diacrítica는 _diacrítica_에는 일치하지만 _diacritica_에는 일치하지 않습니다.

대소문자 구분: 모든 연산자는 대소문자를 구분하지 않습니다. 규칙 cat은 cat, CAT, Cat 모두와 일치합니다.

검색 포스트는 다르게 동작합니다

검색 쿼리를 빌드할 때, 발음 구별 부호가 있는 키워드는 해당 부호가 있는 포스트와 없는 포스트 모두에 일치합니다. 예를 들어, Diacrítica는 _Diacrítica_와 Diacritica 둘 다에 일치합니다.

---

Quote Tweet 매칭

필터링된 스트림을 사용할 때, 연산자는 Quote Tweet의 콘텐츠 및 인용된 원본 게시물의 콘텐츠 둘 다와 일치하도록 동작합니다.

포스트 검색은 동작 방식이 다릅니다. Quote Tweet의 콘텐츠에만 매칭되며, 원본 게시물에는 매칭되지 않습니다.

---

구체성과 효율성

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

효과적인 규칙을 만들기 위한 팁:

1. 처음에는 구체적으로, 이후에 범위를 확장 — 관련성 높은 결과를 반환하는 정밀한 규칙을 먼저 만듭니다
2. 여러 연산자를 사용 — 연산자를 조합해 결과 범위를 좁힙니다
3. 문자 수를 확인 — 전체 규칙 문자열이 모두 제한 문자 수에 포함됩니다

예시 진행 단계:

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

# 개선됨 - 언어 필터 및 제외 조건 추가
(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"
}

게시물 annotation 사용하기

context: 연산자를 사용하여 이미지가 포함된 일본어 반려동물(고양이는 제외) 게시물을 찾습니다:

먼저 Post 조회에서 tweet.fields=context_annotations를 사용하여 domain.entity ID를 식별합니다:

• 고양이: domain 66, entity 852262932607926273
• 반려동물: domain 65, entity 852262932607926273

{
  "value": "context:65.852262932607926273 -context:66.852262932607926273 -is:retweet has:images lang:ja",
  "tag": "이미지가 있는 일본어 반려동물 게시물 - 고양이 제외"
}

---

다음 단계

연산자 레퍼런스

사용 가능한 모든 연산자 목록

필터링된 스트림 빠른 시작

스트림에 연결

샘플 코드

여러 언어의 코드 예제