クイックスタート

​

Filtered stream endpointの使い方を始める

このクイックスタート ガイドでは、cURL リクエストを使って Filtered stream の endpoint グループに最初のリクエストを送る方法を説明します。cURL は、最小限の設定でリクエストを実行できるコマンドラインツールです。

さまざまな言語のサンプルコードを見たい場合は、X API v2 sample code の GitHub リポジトリをご覧ください。

前提条件

このガイドを完了するには、リクエストの認証に使用するキーおよびトークンが必要です。これらのキーおよびトークンは、次の手順で生成できます。

• デベロッパーアカウントに登録し、承認を受ける。
• developer portal で Project を作成し、関連付けられた 開発者用 App を作成する。
• App の「Keys and tokens」ページに移動して、必要な認証情報を生成する。すべての認証情報は安全な場所に保管してください。

​

cURL を使用して Filtered stream リクエストを作成する手順

ステップ 1: ルールを作成する

ルールは、複数のoperatorsをブール論理と括弧で組み合わせて構成され、どの Posts を自分の stream に配信するかを定義します。本ガイドでは、キーワード「cat」と画像の両方を含む Posts を見つけるために stream をフィルタリングします。ルールは次のとおりです。

has:images

ステップ2：ルールにタグを追加する

stream には同時に複数のルールを追加できます。ストリーミング接続を開始すると、これらのいずれかのルールに一致する Posts は同じストリーミング接続経由で配信されます。どの Post がどのルールに一致したかを判別できるよう、ルール作成リクエストにタグを付与して送信できます。そのルールに一致した各 Post には、どのルールに一致したかを示す tag フィールドが Post のペイロード内に含まれます。このルールでは、次のタグを割り当てます。

with images

ステップ3: ルールを stream に追加する

この endpoint では、ルールとそのタグを含む application/json のリクエストボディを渡す必要があります。また、このルールを stream に追加するため、ルールの value と tag は 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：リクエストを認証する

Filtered stream のルール用 endpoint では OAuth 2.0 App-Only authentication が必要なため、事前準備で生成した App Access Token を使用して、ステップ3の cURL コマンド内の $APP_ACCESS_TOKEN を置き換えてください。

ステップ5：ルールを stream に追加する

続いて、cURL リクエストを実行して stream にルールを追加します。cURL コマンドをコマンドラインインターフェースにコピー＆ペーストし、return キーを押してください。

cURL リクエストが成功すると、value、tag、id（ルールの一意の識別子）の data を含むレスポンスが返されます。レスポンスは次のようになります：

{
  "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 リクエストを rules endpoint に送信してください。$APP_ACCESS_TOKEN は必ずご自身のトークンに置き換えてください。このリクエストは、あなたの stream に追加されたすべてのルールの一覧を返します。

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": "cats with images"
	}],
	"meta": {
		"sent": "2020-06-16T23:14:06.498Z"
	}
}

ステップ6：取得する fields を特定して指定する

ステップ5の後にstreamに接続すると、レスポンスにはデフォルトのPost オブジェクトのfieldsが含まれます: id、text、edit_history_tweet_ids。これら以外の追加のfieldsを受け取りたい場合は、リクエストでfields および/または expansions パラメータを指定する必要があります。

この演習では、異なるオブジェクトから3種類のfieldsセットをリクエストします:

1. プライマリの Post オブジェクトに追加する tweet.created_at field
2. 返された Posts の関連する著者のユーザーオブジェクトのデフォルトfields: id、name、username
3. 関連するユーザーオブジェクトに追加する user.created_at field  

これらのfieldsをリクエストするには、リクエストで次の内容を渡す必要があります:

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

以上を踏まえて、streamに接続するためのリクエストURLを組み立てると、次のようになります:

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

ステップ7：stream に接続し、レスポンスを確認する

ルールを設定し、返す fields を指定したので、送信したルールに一致する Post オブジェクトを配信する stream に接続する準備が整いました。ステップ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 をご自身の認証情報に置き換えてください。

Filtered stream に接続すると、設定したルールに一致する Posts が、次の 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": "Twitter Dev",
        "username": "TwitterDev"
      }
    ]
  }
}

接続を終了するには、Mac/Windows いずれの環境でもコマンドラインツールで Control+C を押して接続を切断するか、ウィンドウを閉じてください。