필터링된 스트림 엔드포인트는 스트림에 적용된 일련의 규칙과 일치하는 포스트를 전달합니다. 규칙은 다양한 포스트 속성과 일치하도록 동작하는 연산자로 구성됩니다.
여러 규칙은 POST /tweets/search/stream/rules 엔드포인트를 사용해 적용할 수 있습니다. 규칙을 추가하고 GET /tweets/search/stream으로 스트림에 연결한 후에는 규칙과 일치하는 포스트만 전달됩니다. 규칙을 추가하거나 제거하기 위해 연결을 끊을 필요는 없습니다.
규칙 수에 대한 제한은 사용 중인 액세스 레벨에 따라 달라집니다. 구체적인 한도는 필터링 스트림 소개를 참고하세요.
독립형 연산자는 단독으로 사용하거나 (결합이 필요한 연산자를 포함해) 다른 어떤 연산자와도 함께 사용할 수 있습니다.
예를 들어, 이 규칙은 #hashtag가 독립형 연산자이기 때문에 동작합니다:
연결 필수 연산자는 규칙에서 단독으로 사용할 수 없으며, 최소 한 개 이상의 단독 연산자와 함께 사용할 때만 사용할 수 있습니다. 이는 이러한 연산자를 단독으로 사용하면 매우 방대한 양의 포스트와 일치하게 되기 때문입니다.
예를 들어, 다음 규칙들은 연결 필수 연산자만 포함하고 있으므로 지원되지 않습니다:
"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을 함께 사용할 때는:
- AND 논리로 연결된 연산자가 먼저 결합됩니다.
- 그다음 OR 논리로 연결된 연산자가 적용됩니다.
예시:
| Query | Evaluated as |
|---|
apple OR iphone ipad | apple OR (iphone ipad) |
ipad iphone OR android | (iphone ipad) OR android |
발음 구별 부호(diacritics): 발음 구별 부호가 포함된 필터 스트림 규칙은 해당 부호가 포함된 포스트에만 일치합니다. 예를 들어, diacrítica는 _diacrítica_에는 일치하지만 _diacritica_에는 일치하지 않습니다.
대소문자 구분: 모든 연산자는 대소문자를 구분하지 않습니다. 규칙 cat은 cat, CAT, Cat 모두와 일치합니다.
검색 포스트는 다르게 동작합니다검색 쿼리를 빌드할 때, 발음 구별 부호가 있는 키워드는 해당 부호가 있는 포스트와 없는 포스트 모두에 일치합니다. 예를 들어, Diacrítica는 _Diacrítica_와 Diacritica 둘 다에 일치합니다.
필터링된 스트림을 사용할 때, 연산자는 Quote Tweet의 콘텐츠 및 인용된 원본 게시물의 콘텐츠 둘 다와 일치하도록 동작합니다.
포스트 검색은 동작 방식이 다릅니다. Quote Tweet의 콘텐츠에만 매칭되며, 원본 게시물에는 매칭되지 않습니다.
단일 키워드나 해시태그 같은 광범위한 연산자만 사용하는 것은 권장되지 않습니다. 엄청난 양의 포스트와 매칭되어 연결을 빠르게 소모하게 됩니다.
- 처음에는 구체적으로, 이후에 범위를 확장 — 관련성 높은 결과를 반환하는 정밀한 규칙을 먼저 만듭니다
- 여러 연산자를 사용 — 연산자를 조합해 결과 범위를 좁힙니다
- 문자 수를 확인 — 전체 규칙 문자열이 모두 제한 문자 수에 포함됩니다
예시 진행 단계:
# 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
2단계: 결과를 기반으로 테스트하고 범위를 좁히기
(happy OR happiness) lang:en
(happy OR happiness) lang:en -birthday -is:retweet
(happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet
(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"}
]
}'
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"
}
{
"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"
}
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": "이미지가 있는 일본어 반려동물 게시물 - 고양이 제외"
}
