X API v2의 Powerstream 저지연 스트리밍 API

Powerstream은 공개 X 데이터에 실시간으로 액세스하기 위한 가장 낮은 지연 시간의 스트리밍 API입니다. 데이터 하이드레이션과 전달에 우선순위를 두는(약 6-7초 P99 지연) 다른 스트리밍 엔드포인트와 달리, Powerstream은 속도에 최적화되어 있어 최소한의 지연으로 데이터를 전달합니다. 레거시 GNIP Powertrack API와 유사하게, 키워드, 연산자, 메타데이터를 기반으로 Post를 필터링하는 규칙을 사용합니다. Powerstream 엔드포인트에 지속적인 HTTP 연결이 이루어지면 매칭되는 Post를 실시간으로 수신할 수 있습니다. 현재 Powerstream은 최대 1,000개의 규칙을 지원하며 각 규칙은 2048자까지 가능합니다.

주요 기능

실시간 데이터 전달: Post가 게시되는 즉시 스트리밍하기 위한 가장 낮은 지연 시간 옵션.
정확한 필터링: 연산자가 포함된 Boolean 쿼리를 사용하여 원하는 데이터를 정확하게 필터링합니다.
전달: HTTP/1.1 청크 전송 인코딩을 통한 JSON 응답.
로컬 데이터센터 지원: 복제 지연을 피하여 지연 시간을 더 줄이기 위해 로컬 데이터센터에서만 Post를 가져옵니다.

Powerstream API는 선택된 Enterprise 플랜에서 사용할 수 있는 프리미엄 제공 서비스입니다.Powerstream에 액세스하거나 Enterprise 제공 서비스에 대해 자세히 알아보고 싶다면, Enterprise Request Form을 제출하여 Sales 팀에 문의하세요. Powerstream이 여러분의 필요를 어떻게 지원할 수 있는지 논의하게 되어 기쁠 것입니다.

빠른 시작

이 섹션에서는 requests 라이브러리를 사용하는 Python으로 PowerStream 엔드포인트를 빠르게 시작하는 방법을 보여줍니다. pip install requests를 통해 설치하세요. 모든 예시는 OAuth 2.0 Bearer Token 인증을 사용합니다. YOUR_BEARER_TOKEN을 실제 토큰으로 교체하세요 (예: os.getenv('BEARER_TOKEN')를 통해 안전하게 저장). 각 엔드포인트를 코드 스니펫과 함께 다룹니다. 최상단에는 다음 import 문이 있다고 가정합니다:

import requests
import json
import time
import sys
import os  # For env vars

설정

bearer_token = os.getenv('BEARER_TOKEN') or "YOUR_BEARER_TOKEN"  # Use env var for security
base_url = "https://api.x.com/2/powerstream"
rules_url = f"{base_url}/rules"  # For rule management
headers = {
   "Authorization": f"Bearer {bearer_token}",
   "Content-Type": "application/json"
}

1. 규칙 생성 (POST /rules)

스트림 필터링을 위해 규칙을 추가합니다.

예제

data = {
   "rules": [
       {
           "value": "(cat OR dog) lang:en -is:retweet",
           "tag": "pet-monitor"
       },
       # Add more rules as needed (up to 100)
   ]
}

response = requests.post(rules_url, headers=headers, json=data)
if response.status_code == 201:
   rules_added = response.json().get("data", {}).get("rules", [])
   print("Rules added:")
   for rule in rules_added:
       print(f"ID: {rule['id']}, Value: {rule['value']}, Tag: {rule.get('tag', 'N/A')}")
else:
   print(f"Error {response.status_code}: {response.text}")

2. 규칙 삭제 (POST /rules)

ID(권장) 또는 값으로 규칙을 제거합니다.

예제

data = {
   "rules": [
       {
           "value": "(cat OR dog) lang:en -is:retweet",
           "tag": "pet-monitor"
       },
       # Add more rules as needed (up to 100)
   ]
}

response = requests.delete(rules_url, headers=headers, json=data)
if response.status_code == 200:
   deleted = response.json().get("data", {})
   print(f"Deleted count: {deleted.get('deleted', 'N/A')}")
   if 'not_deleted' in deleted:
       print("Not deleted:", deleted['not_deleted'])
else:
   print(f"Error {response.status_code}: {response.text}")

팁: 모든 규칙을 삭제하려면 먼저 규칙을 GET하고 ID를 추출한 다음 일괄로 삭제합니다.

3. 규칙 가져오기 (GET /rules)

모든 활성 규칙을 가져옵니다.

response = requests.get(rules_url, headers=headers)
if response.status_code == 200:
   rules = response.json().get("data", {}).get("rules", [])
   if rules:
       print("Active rules:")
       for rule in rules:
           print(f"ID: {rule['id']}, Value: {rule['value']}, Tag: {rule.get('tag', 'N/A')}")
   else:
       print("No active rules.")
else:
   print(f"Error {response.status_code}: {response.text}")

4. PowerStream (GET /stream)

실시간 저지연 Post를 위해 스트림에 연결합니다. 줄 단위 읽기를 위해 stream=True를 사용하세요. 견고성을 위해 재연결 로직을 구현하세요.

예제

stream_url = base_url

def main():
   while True:
       response = requests.request("GET", stream_url, headers=headers, stream=True)
       print(response.status_code)
       for response_line in response.iter_lines():
           if response_line:
               json_response = json.loads(response_line)
               print(json.dumps(json_response, indent=4, sort_keys=True))
               if response.status_code != 200:
                   print(response.headers)
                   raise Exception(
                       "Request returned an error: {} {}".format(
                           response.status_code, response.text
                       )
                   )

로컬 데이터센터 지원

지연 시간 최적화를 위해 Powerstream은 연결이 설정된 로컬 데이터센터에서 발생하거나 생성된 게시물만 가져오는 옵션을 제공합니다. 이는 복제 지연을 방지하여, 다른 데이터센터의 게시물보다 더 빠른 전달을 제공합니다. 이를 활성화하려면 스트림 엔드포인트에 쿼리 매개변수 ?localDcOnly=true를 추가하세요 (예: /2/powerstream?localDcOnly=true). 연결된 데이터센터는 스트림의 초기 데이터 페이로드와 응답의 HTTP 헤더에서 표시됩니다. 코드에서 사용하려면:

# For local datacenter only:
stream_url = "https://api.x.com/2/powerstream?localDcOnly=true"

localDcOnly 매개변수가 활성화된 경우, 스트림이 처음 연결될 때 사용 중인 로컬 데이터센터를 나타내는 다음 응답 헤더가 포함됩니다:

'x-powerstream-datacenter': 'atla',
'x-powerstream-localdconly': 'true'

이 외에도 데이터센터를 지정하는 초기 페이로드도 전송됩니다:

{
    "type": "connection_metadata",
    "datacenter": "atla",
    "timestamp": 1762557264155
}

팁: 지연 시간을 최적화하려면, 서로 다른 지리적 위치(예: 미국 동부 해안 애틀랜타 근처와 미국 서부 해안 포틀랜드 근처)에서 연결을 설정하고, 각각에 대해 localDcOnly=true를 활성화하세요. 이를 통해 각 해당 데이터센터의 게시물에 더 빠르게 액세스할 수 있습니다. 데이터센터 간 데이터를 결합하려면 여러분 측에서 스트림을 집계하세요.

연산자

필터링을 위한 규칙을 설정하려면 키워드와 연산자를 사용할 수 있습니다.

Powerstream 연산자

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

응답

Powerstream API의 페이로드는 레거시 GNIP Powertrack API와 동일한 형식입니다. 샘플 JSON 응답은 다음과 같습니다:

예시 응답

[
   {
       "created_at": "Tue Mar 21 20:50:14 +0000 2006",
       "id": 20,
       "id_str": "20",
       "text": "just setting up my twttr",
       "truncated": false,
       "entities": {
           "hashtags": [],
           "symbols": [],
           "user_mentions": [],
           "urls": []
       },
       "source": "<a href=\"http://x.com\" rel=\"nofollow\">X Web Client</a>",
       "in_reply_to_status_id": null,
       "in_reply_to_status_id_str": null,
       "in_reply_to_user_id": null,
       "in_reply_to_user_id_str": null,
       "in_reply_to_screen_name": null,
       "user": {
           "id": 12,
           "id_str": "12",
           "name": "jack",
           "screen_name": "jack",
           "location": "",
           "description": "no state is the best state",
           "url": "https://t.co/ZEpOg6rn5L",
           "entities": {
               "url": {
                   "urls": [
                       {
                           "url": "https://t.co/ZEpOg6rn5L",
                           "expanded_url": "http://primal.net/jack",
                           "display_url": "primal.net/jack",
                           "indices": [
                               0,
                               23
                           ]
                       }
                   ]
               },
               "description": {
                   "urls": []
               }
           },
           "protected": false,
           "followers_count": 6427829,
           "friends_count": 3,
           "listed_count": 32968,
           "created_at": "Tue Mar 21 20:50:14 +0000 2006",
           "favourites_count": 36306,
           "utc_offset": null,
           "time_zone": null,
           "geo_enabled": true,
           "verified": false,
           "statuses_count": 30134,
           "lang": null,
           "contributors_enabled": false,
           "is_translator": false,
           "is_translation_enabled": false,
           "profile_background_color": "EBEBEB",
           "profile_background_image_url": "http://abs.twimg.com/images/themes/theme7/bg.gif",
           "profile_background_image_url_https": "https://abs.twimg.com/images/themes/theme7/bg.gif",
           "profile_background_tile": false,
           "profile_image_url": "http://pbs.twimg.com/profile_images/1661201415899951105/azNjKOSH_normal.jpg",
           "profile_image_url_https": "https://pbs.twimg.com/profile_images/1661201415899951105/azNjKOSH_normal.jpg",
           "profile_banner_url": "https://pbs.twimg.com/profile_banners/12/1742427520",
           "profile_link_color": "990000",
           "profile_sidebar_border_color": "DFDFDF",
           "profile_sidebar_fill_color": "F3F3F3",
           "profile_text_color": "333333",
           "profile_use_background_image": true,
           "has_extended_profile": true,
           "default_profile": false,
           "default_profile_image": false,
           "following": null,
           "follow_request_sent": null,
           "notifications": null,
           "translator_type": "regular",
           "withheld_in_countries": []
       },
       "geo": null,
       "coordinates": null,
       "place": null,
       "contributors": null,
       "is_quote_status": false,
       "retweet_count": 122086,
       "favorite_count": 263321,
       "favorited": false,
       "retweeted": false,
       "lang": "en"
   }
]

제한 및 모범 사례

요청 한도: 규칙 관리 24시간당 50건; 스트림에는 제한 없음 (단, 연결 제한이 적용됨).
재연결: 연결 해제 시 지수 백오프.
모니터링: Connection: keep-alive 헤더 사용.

스트리밍 기본

스트리밍 데이터 소비

스트리밍 클라이언트에 대한 모범 사례

연결 해제 처리

우아하게 재연결하기

대용량 처리

높은 처리량 처리

복구 및 이중화

복원력 있는 애플리케이션 구축

Getting Started

Products

Fundamentals

Partners & Customers

Resources

X API v2의 Powerstream 저지연 스트리밍 API

주요 기능

빠른 시작

설정

1. 규칙 생성 (POST /rules)

2. 규칙 삭제 (POST /rules)

3. 규칙 가져오기 (GET /rules)

4. PowerStream (GET /stream)

로컬 데이터센터 지원

연산자

Powerstream 연산자

응답

제한 및 모범 사례

스트리밍 기본

스트리밍 데이터 소비

연결 해제 처리

대용량 처리

복구 및 이중화

​주요 기능

​빠른 시작

​설정

​1. 규칙 생성 (POST /rules)

​2. 규칙 삭제 (POST /rules)

​3. 규칙 가져오기 (GET /rules)

​4. PowerStream (GET /stream)

​로컬 데이터센터 지원

​연산자

Powerstream 연산자

​응답

​제한 및 모범 사례

​스트리밍 기본

스트리밍 데이터 소비

연결 해제 처리

대용량 처리

복구 및 이중화

주요 기능

빠른 시작

설정

1. 규칙 생성 (POST /rules)

2. 규칙 삭제 (POST /rules)

3. 규칙 가져오기 (GET /rules)

4. PowerStream (GET /stream)

로컬 데이터센터 지원

연산자

응답

제한 및 모범 사례

스트리밍 기본