메인 콘텐츠로 건너뛰기

​
스트리밍 데이터를 수신하는 클라이언트 구축

스트리밍 엔드포인트를 사용할 때는 사용을 최적화하기 위해 고려해야 할 일반적인 모범 사례가 있습니다.    

​
클라이언트 설계

filter stream 엔드포인트로 솔루션을 구축할 때는 다음을 수행할 수 있는 클라이언트가 필요합니다:
  1. filter stream 엔드포인트에 HTTPS 스트리밍 연결을 설정합니다.
  2. 스트림의 규칙을 추가·삭제하기 위해 filter stream rules 엔드포인트로 비동기 POST 요청을 전송합니다.
  3. 저용량 데이터 처리 – 스트리밍 연결을 유지하고, 게시물(Post) 객체와 keep-alive 신호를 감지합니다.
  4. 대용량 데이터 처리 – 비동기 처리로 스트림 수집과 후속 처리를 분리하고, 클라이언트 측 버퍼가 정기적으로 비워지도록 합니다.
  5. 클라이언트 측에서 데이터 사용량 추적을 관리합니다.
  6. 스트림 연결 해제를 감지하고 평가하여 자동으로 재연결합니다.  

​
스트리밍 엔드포인트에 연결하기

X API v2 스트리밍 엔드포인트에 연결한다는 것은 수명이 매우 긴 HTTP 요청을 열어 두고, 응답을 순차적으로 파싱한다는 뜻입니다. 개념적으로는 HTTP를 통해 무한히 긴 파일을 다운로드하는 것과 같습니다. 연결이 수립되면, 연결이 열린 동안 X 서버는 해당 연결을 통해 게시물 이벤트를 전송합니다.  

​
데이터 소비

JSON 객체의 개별 필드는 고정된 순서가 없으며, 모든 상황에서 모든 필드가 포함되는 것은 아닙니다. 마찬가지로, 개별 활동은 정렬된 순서로 전달되지 않고, 중복 메시지를 받을 수도 있습니다. 시간이 지나면서 새로운 메시지 유형이 추가되어 스트림으로 전송될 수 있음을 명심하세요. 따라서 클라이언트는 다음을 허용해야 합니다:
  • 임의의 순서로 나타나는 필드
  • 예기치 않거나 누락된 필드
  • 정렬되지 않은 게시물
  • 중복 메시지
  • 언제든 스트림으로 전달될 수 있는 임의의 신규 메시지 유형
관련 게시물 데이터와 요청한 필드 매개변수 외에도 스트림 연결에서는 다음과 같은 유형의 메시지가 전달될 수 있습니다. 이 목록은 완전하지 않을 수 있으며, 스트림에 추가 객체가 도입될 수 있습니다. 파서는 예기치 않은 메시지 형식에도 견고하게 동작하도록 구성하십시오.  

​
버퍼링 

스트리밍 엔드포인트는 데이터가 준비되는 즉시 전송하므로, 경우에 따라 대량 트래픽이 발생할 수 있습니다. X 서버가 즉시 스트림에 새 데이터를 기록하지 못하는 상황(예: 클라이언트의 읽기 속도가 충분히 빠르지 않은 경우—자세한 내용은 연결 끊김 처리 참고)에서는, 클라이언트가 따라잡을 수 있도록 서버 측에서 콘텐츠를 버퍼링합니다. 다만 이 버퍼가 가득 차면 연결을 종료하기 위한 강제 연결 해제가 이루어지며, 버퍼에 있던 게시물은 폐기되고 재전송되지 않습니다. 자세한 내용은 아래를 참고하세요. 앱이 처리 속도에서 뒤처지는 시점을 파악하는 한 가지 방법은 수신 중인 게시물의 타임스탬프를 현재 시간과 비교하고, 이를 지속적으로 추적하는 것입니다. 공용 인터넷에서 발생할 수 있는 지연과 일시적 장애 때문에 스트림 지연을 완전히 없앨 수는 없지만, 앱을 올바르게 구성하면 상당 부분 줄일 수 있습니다. 지연 발생을 최소화하려면:
  • 클라이언트가 스트림을 충분히 빠르게 읽고 있는지 확인하세요. 일반적으로 스트림을 읽는 동안 실질적인 처리 작업을 수행하지 말고, 스트림을 읽은 뒤 작업을 다른 스레드/프로세스/데이터 저장소로 넘겨 비동기적으로 처리하세요.
  • 데이터 센터가 지속적으로 큰 데이터량과 훨씬 더 큰 급증 트래픽(예: 평시 대비 5~10배)을 수용할 수 있을 만큼 충분한 인바운드 대역폭을 보유하고 있는지 확인하세요. 필터링된 스트림의 경우, 귀측에서 필요한 처리량과 이에 따른 대역폭은 규칙이 어떤 게시물과 일치하느냐에 전적으로 좌우됩니다.  

​
사용량 추적 및 규칙 관리

개발자들이 각자의 스트림에서 어느 정도 데이터량이 “정상”인지에 대한 기준을 형성해 가는 단계이므로, 특정 기간 동안의 증감 비율에 대한 일반적인 권장치는 제공하지 않습니다. 예상치 못한 변동이 있는지 스트림 데이터량을 모니터링하십시오. 데이터량 감소는 스트림 연결 해제와는 다른 문제의 신호일 수 있습니다. 이런 경우에도 스트림은 여전히 keep-alive 신호와 일부 신규 활동 데이터를 수신할 수 있습니다. 다만 게시물 수가 눈에 띄게 줄어든다면 애플리케이션이나 네트워크로 유입되는 데이터량 감소를 야기하는 요인이 있는지 조사하고, 관련 공지가 있는지 상태 페이지를 확인해야 합니다. 이를 위해 일정 시간 동안 예상되는 신규 게시물 수를 추적하는 방식을 도입할 수 있습니다. 스트림의 데이터량이 지정한 임계값보다 충분히 낮아지고 설정된 기간 내에 회복되지 않으면 경보와 알림을 발생시키십시오. 또한 필터링 스트림에서 규칙을 수정하는 중이거나, 게시물 활동이 급증하는 이벤트가 발생하는 경우에는 데이터량이 크게 증가하는지도 함께 모니터링하는 것이 좋습니다. 필터링 스트림으로 전달되는 게시물은 월별 총 게시물량에 포함되므로, 최적화를 위해 소비량을 추적하고 조정해야 합니다. 데이터량이 많을 경우 각 규칙에 sample: 연산자를 추가해 100% 매칭에서 필요 시 sample:50 또는 sample:25로 낮추는 것을 고려하십시오. 아울러 사전에 설정한 임계값을 초과할 경우 팀에 알림이 전달되도록 앱 내에 조치를 구현하고, 과도한 데이터를 유입시키는 규칙을 자동으로 삭제하거나, 극단적인 상황에서는 스트림 연결을 완전히 해제하는 등의 추가 조치도 검토하시기 바랍니다.  

​
시스템 메시지에 응답하기

Keep-alive 신호 스트림은 최소 20초마다 열린 연결을 통해 \r\n 캐리지 리턴 형태의 keep-alive 신호(하트비트)를 보내 클라이언트의 타임아웃을 방지합니다. 클라이언트 애플리케이션은 스트림에 포함된 \r\n 문자를 허용해야 합니다. 클라이언트가 HTTP 라이브러리에서 읽기 타임아웃을 올바르게 구현했다면, 해당 기간 동안 데이터가 읽히지 않을 때 HTTP 프로토콜과 HTTP 라이브러리가 이벤트를 발생시키므로 \r\n 문자를 별도로 모니터링할 필요가 없습니다. 이 이벤트는 사용 중인 HTTP 라이브러리에 따라 일반적으로 예외가 발생하거나 기타 이벤트로 전달됩니다. 이러한 타임아웃을 감지하기 위해 HTTP 메서드에 오류/이벤트 핸들러를 감싸는 것을 강력히 권장합니다. 타임아웃이 발생하면 애플리케이션은 재연결을 시도해야 합니다. 오류 메시지 v2 스트리밍 엔드포인트는 스트림 내 오류 메시지를 전달할 수도 있습니다. 아래에는 이러한 메시지의 기본 형식과 몇 가지 예시가 제공됩니다. 전달되는 메시지는 변경될 수 있으며, 새로운 메시지가 추가될 수 있다는 점에 유의하세요. 클라이언트 애플리케이션은 변경될 수 있는 시스템 메시지 페이로드에 유연하게 대응해야 합니다. 오류 메시지에는 문제 해결 방법을 설명하는 문서로 연결되는 링크가 포함됩니다. 메시지 형식: 
	"errors": [{
		"title": "operational-disconnect",
		"disconnect_type": "UpstreamOperationalDisconnect",
		"detail": "이 스트림은 운영상의 이유로 업스트림에서 연결이 끊어졌습니다.",
		"type": "https://api.x.com/2/problems/operational-disconnect"
	}]
}
버퍼가 가득 차 강제 연결 해제가 발생했다는 오류 메시지는, 해당 강제 해제를 유발한 백업 때문에 메시지 자체가 전달되지 못해 클라이언트에 도달하지 못할 수도 있습니다. 따라서 앱은 재연결을 시작할 때 이러한 메시지에 의존해서는 안 됩니다.