빠른 시작하기

​

필터링된 스트림 엔드포인트 시작하기

이 빠른 시작 가이드는 cURL 요청을 사용해 필터링된 스트림 엔드포인트 그룹에 첫 요청을 보내는 방법을 안내합니다. cURL은 최소한의 설정으로 요청을 보낼 수 있는 명령줄 도구입니다.

다른 언어의 샘플 코드를 보고 싶다면 X API v2 샘플 코드 GitHub 리포지토리를 방문하세요.

사전 준비 사항

이 가이드를 완료하려면 요청 인증에 사용할 키와 토큰 세트가 필요합니다. 다음 단계를 따라 키와 토큰을 생성할 수 있습니다:

• 개발자 계정에 가입하고 승인을 받습니다.
• 개발자 포털에서 Project와 연결된 Developer 앱을 생성합니다.
• App의 “Keys and tokens” 페이지로 이동해 필요한 자격 증명을 생성합니다. 모든 자격 증명을 안전한 위치에 저장하세요.

​

cURL을 사용해 필터링된 스트림 요청을 만드는 단계

1단계: 규칙 생성

규칙은 하나 이상의 연산자로 구성되며, 불리언 로직과 괄호로 결합하여 어떤 게시물이 스트림으로 전달될지를 정의합니다. 이 가이드에서는 키워드 “cat”과 이미지가 모두 포함된 게시물을 찾도록 스트림을 필터링합니다. 규칙은 다음과 같습니다:

has:images

2단계: 규칙에 태그 추가하기

스트림에는 동시에 여러 규칙을 추가할 수 있습니다. 스트리밍 연결을 열면 이러한 규칙 중 하나라도 일치하는 게시물은 동일한 스트리밍 연결을 통해 전달됩니다. 어떤 게시물이 어떤 규칙과 일치했는지 알 수 있도록 규칙 생성 요청에 태그를 함께 전달할 수 있습니다. 해당 규칙과 일치하는 각 게시물에는 일치한 규칙을 표시하는 태그 필드가 게시물 페이로드에 포함됩니다. 이 규칙에는 다음 태그를 지정하겠습니다:

with images

3단계: 규칙을 스트림에 추가하기

이 엔드포인트에서는 규칙과 해당 태그가 포함된 application/json 형식의 본문을 요청과 함께 전달해야 합니다. 또한 이 규칙을 스트림에 추가하려는 것이므로 add 객체 안에 규칙 값과 태그를 포함한 것을 확인할 수 있습니다. 이 JSON 본문은 다음과 같습니다:

{
  "add": [
    {
      "value": "cat has:images",
      "tag": "이미지가 있는 고양이"
    }
  ]
}

이제 이 JSON 본문 구성이 완료되었으므로 cURL 요청에 추가할 수 있으며, 형태는 다음과 같습니다. 이 요청은 아직 준비되지 않았으니, 이후 단계까지 제출을 미뤄 주세요.

curl -X POST 'https://api.x.com/2/tweets/search/stream/rules' \
-H "Content-type: application/json" \
-H "Authorization: Bearer $APP_ACCESS_TOKEN" -d \
'{
  "add": [
    {"value": "cat has:images", "tag": "이미지가 포함된 고양이"}
  ]
}'`

4단계: 요청 인증하기

필터링된 스트림 규칙 엔드포인트에는 OAuth 2.0 App-Only 인증이 필요하므로, 3단계의 cURL 명령에서 $APP_ACCESS_TOKEN을 사전 준비 단계에서 생성한 앱 액세스 토큰으로 바꿔야 합니다. 

5단계: 스트림에 규칙 추가하기

다음으로 cURL 요청을 실행하여 스트림에 규칙을 추가합니다. cURL 명령을 명령줄 인터페이스에 복사해 붙여넣고 Enter 키를 누르세요. 

cURL 요청이 성공하면 값, 태그, 그리고 id(해당 규칙의 고유 식별자)와 관련된 데이터가 포함된 응답을 받게 됩니다. 응답은 다음과 비슷합니다:

{
  "data": [
    {
      "value": "cat has:images",
      "tag": "이미지가 있는 고양이",
      "id": "1273026480692322304"
    }
  ],
  "meta": {
    "sent": "2020-06-16T22:55:39.356Z",
    "summary": {
      "created": 1,
      "not_created": 0,
      "valid": 1,
      "invalid": 0
    }
  }
}

규칙이 성공적으로 추가되었는지 확인하려면 다음 GET 요청을 규칙 엔드포인트로 보내세요. 이때 $APP_ACCESS_TOKEN을 반드시 본인의 토큰으로 다시 한 번 교체해야 합니다. 이 요청은 스트림에 추가된 모든 규칙의 전체 목록을 반환합니다.

curl -X GET 'https://api.x.com/2/tweets/search/stream/rules' \
-H "Authorization: Bearer $APP_ACCESS_TOKEN"

cURL 요청이 성공하면 다음과 같은 결과를 받습니다:

{
	"data": [{
		"id": "1273028376882589696",
		"value": "cat has:images",
		"tag": "이미지가 있는 고양이"
	}],
	"meta": {
		"sent": "2020-06-16T23:14:06.498Z"
	}
}

6단계: 가져올 필드를 식별하고 지정하기

5단계 이후 스트림에 연결하면 기본 Post object 필드가 응답에 포함됩니다: id, text, edit_history_tweet_ids. 이들 외에 추가 필드를 받고 싶다면 field 및/또는 expansion 매개변수로 요청에 해당 필드를 지정해야 합니다.

이 연습에서는 서로 다른 객체에서 세 가지 필드 세트를 요청합니다:

1. 기본 Post 객체의 추가 tweet.created_at 필드
2. 반환된 게시물의 관련 작성자 user object의 기본 필드: id, name, username
3. 관련 사용자 객체의 추가 user.created_at 필드  

이러한 필드를 요청하려면 요청에 다음 값을 전달해야 합니다:

Key	Value	Returned fields
tweet.fields	created_at	tweets.created_at
expansions	author_id	includes.users.id, includes.users.name, includes.users.username
user.fields	created_at	includes.users.created_at

이제 이를 바탕으로 스트림에 연결할 요청 URL을 구성할 수 있으며, 형태는 다음과 같습니다:

https://api.x.com/2/tweets/search/stream?tweet.fields=created_at&expansions=author_id&user.fields=created_at

7단계: 스트림에 연결하고 응답 검토하기

이제 규칙을 설정하고 반환받을 필드를 지정했으므로, 제출한 규칙과 일치하는 게시물 객체를 전달하는 스트림에 연결할 준비가 되었습니다. 6단계의 URL을 요청에 추가하면 cURL 명령은 다음과 같은 형태가 됩니다:

curl -X GET -H "Authorization: Bearer $APP_ACCESS_TOKEN" "https://api.x.com/2/tweets/search/stream?tweet.fields=created_at&expansions=author_id&user.fields=created_at"

다시 한 번, 이 요청은 OAuth 2.0 App-Only로 인증해야 하므로 명령줄 도구에 복사해 붙여넣기 전에 $APP_ACCESS_TOKEN을(를) 앱 자격 증명으로 바꿔 주세요.

필터링된 스트림에 연결되면 아래 JSON 형식으로 규칙과 일치하는 게시물을 받기 시작합니다:

{
  "data": [
    {
      "author_id": "2244994945",
      "created_at": "2022-09-14T19:00:55.000Z",
      "id": "1228393702244134912",
      "edit_history_tweet_ids": ["1228393702244134912"],
      "text": "개발자가 발렌타인 카드에 뭐라고 썼을까요?\n  \nwhile(true) {\n    I = Love(You);  \n}"
    },
    {
      "author_id": "2244994945",
      "created_at": "2022-09-12T17:09:56.000Z",
      "id": "1227640996038684673",
       "edit_history_tweet_ids": ["1227640996038684673"],
      "text": "의사: 온라인 검색한다고 의사 되는 거 아닙니다\n\n개발자: https://t.co/mrju5ypPkb"
    },
    {
      "author_id": "2244994945",
      "created_at": "2022-09-27T20:26:41.000Z",
      "id": "1199786642791452673",
      "edit_history_tweet_ids": ["1199786642791452673"],
      "text": "C#"
    }
  ],
  "includes": {
    "users": [
      {
        "created_at": "2013-12-14T04:35:55.000Z",
        "id": "2244994945",
        "name": "X Dev",
        "username": "TwitterDev"
      }
    ]
  }
}

연결을 종료하려면 Mac 또는 Windows의 명령줄 도구에서 Control-C를 눌러 연결을 끊거나 창을 닫으면 됩니다.