メインコンテンツへスキップ

​
フィルタリングされたストリームのルール構築

フィルタリングされたストリームのエンドポイントは、ストリームに適用される一連のルールに一致する投稿をあなたに配信します。ルールは、さまざまな投稿の属性に一致させるために使用される演算子で構成されています。 複数のルールをストリームに適用するには、POST /tweets/search/stream/rules エンドポイントを使用します。ルールを追加した後、GET /tweets/search/stream エンドポイントを使用してストリームに接続すると、ルールに一致する投稿のみが永続的なストリーミング接続を通じて配信されます。ルールの追加や削除のためにストリームから切断する必要はありません。 

​
目次

​
ルールの作成

​
ルールの制限

ルールの数の制限は、お使いの プロジェクト に適用される アクセス レベル によって異なります。 これらの制限の適用方法は、フィルタリング ストリーム入門 ページで確認できます。

​
オペレーターの種類: 単体および接続詞が必要

単体オペレーター は、単独で使用するか、他の任意のオペレーター（接続詞を必要とするものを含む）と組み合わせて使用できます。 たとえば、以下のルールは、#hashtag オペレーターを使用しており、これは単体であるため機能します： #xapiv2 接続詞が必要なオペレーター は、ルール内で単独で使用できません。少なくとも1つの単体オペレーターがルールに含まれている場合にのみ使用できます。これは、これらのオペレーターを単独で使用すると、あまりにも一般的になり、投稿の極めて大量に一致してしまうためです。 たとえば、以下のルールは、接続詞が必要なオペレーターのみを含んでいるためサポートされていません： has:media has:links OR is:retweet たとえば、フレーズ "X data" のような単体オペレーターを追加すると、ルールは適切に機能します。 "X data" has:mentions (has:media OR has:links)

​
ブール演算子とグループ化

複数の演算子を1つのルール内で組み合わせたい場合、以下の方法を利用できます：
AND 論理連続する演算子 間にスペースを置く と、ブール「AND」論理が適用され、両方の条件が満たされた場合にのみ投稿が一致します。たとえば、snow day #NoSchool は snow と day のキーワード、および #NoSchool ハッシュタグを含む投稿に一致します。
OR 論理連続する演算子に OR を挟むと、OR 論理が適用され、いずれかの条件が満たされた場合に投稿が一致します。たとえば、grumpy OR cat OR #meme を指定すると、grumpy または cat のキーワード、または #meme ハッシュタグの少なくとも1つを含む投稿に一致します。
NOT 論理、否定キーワード（または任意の演算子）にダッシュ (-) を前に付けて否定（NOT）します。たとえば、cat #meme -grumpy は #meme ハッシュタグと cat のキーワードを含む投稿に一致しますが、grumpy のキーワードを含まない場合に限ります。一般的なルール句の1つは -is:retweet で、リツイートには一致せず、元の投稿、引用ツイート、および返信にのみ一致します。すべての演算子を否定できますが、否定された演算子は単独では使用できません。
グループ化演算子をグループ化するために括弧を使用できます。たとえば、(grumpy cat) OR (#meme has:images) は grumpy と cat のキーワードを含む投稿、または #meme ハッシュタグを含む画像付き投稿のいずれかを返します。AND が最初に適用され、次に OR が適用されることに注意してください。
否定に関する注意すべての演算子を否定できますが、sample: を除きます。また、-is:nullcast は常に否定形として使用する必要があります。否定された演算子は単独では使用できません。括弧でグループ化された演算子のセットを否定しないでください。代わりに、各個別の演算子を否定してください。たとえば、skiing -(snow OR day OR noschool) を使用する代わりに、skiing -snow -day -noschool を使用することをお勧めします。 

​
演算の順序

AND と OR を組み合わせる場合、ルールの評価は以下の演算順序に従います。
  1. AND 論理で接続された演算子が最初に結合されます
  2. その後、OR 論理で接続された演算子が適用されます
例:
  • apple OR iphone ipad は apple OR (iphone ipad) として評価されます
  • ipad iphone OR android は (ipad iphone) OR android として評価されます
曖昧さを避け、ルールが意図した通りに評価されるよう、必要に応じて括弧で項をグループ化してください。 例:
  • (apple OR iphone) ipad
  • iphone (ipad OR android)

​
句読点、ダイアクリティカルマーク、大小文字の区別

アクセントやダイアクリティカルマークを含む文字でキーワードまたはハッシュタグのルールを指定した場合、そのアクセントやダイアクリティカルマークが正しく付いた完全一致の語を含むPostにはマッチしますが、同じ語でもアクセントやダイアクリティカルマークがないものにはマッチしません。 たとえば、キーワード diacrítica やハッシュタグ #cumpleaños を含むルールは、アクセントやダイアクリティカルマークが含まれているため、diacrítica や #cumpleaños を含むPostにマッチします。ただし、チルデ付きの í やエニェがない Diacritica や #cumpleanos を含むPostにはマッチしません。 アクセントやダイアクリティカルマークを含む文字は通常の文字と同様に扱われ、単語境界とは見なされません。たとえば、キーワード cumpleaños を含むルールは、cumpleaños という語を含むPostにのみマッチし、cumplea、cumplean、または os を含むPostにはマッチしません。 すべての演算子は大文字・小文字を区別せずに評価されます。たとえば、ルール cat は、cat、CAT、Cat のいずれにもマッチします。
Search Posts のマッチング挙動は filtered stream とは異なります。Search Posts のクエリを構築する際は、アクセントやダイアクリティカルマークを含むキーワードやハッシュタグが、アクセントやダイアクリティカルマークを含む表記と通常の文字の表記の両方にマッチすることに留意してください。たとえば、キーワード Diacrítica やハッシュタグ #cumpleaños を含む Search Posts のクエリは、Diacrítica や #cumpleaños に加えて、チルデ付きの í やエニェがない Diacritica や #cumpleanos にもマッチします。

​
具体性と効率

ルールを作成し始めるときは、いくつかの点に留意することが重要です。
  • ルールで単一のキーワードや #ハッシュタグのような広範な単体演算子を使用するのは、通常推奨されません。なぜなら、それらは大量の投稿に一致する可能性が高いからです。より堅牢なルールを作成すれば、より具体的な一致投稿のセットが得られ、価値ある洞察を探すためにペイロードを精査する際のノイズを減らすことができるでしょう。
    • たとえば、ルールが単にキーワード happy の場合、1 日あたり 200,000 〜 300,000 の投稿が得られる可能性があります。
    • 条件演算子を追加することで検索結果を絞り込めます。たとえば (happy OR happiness) place_country:GB -birthday -is:retweet
  • 効率的なルールを書くことは、ルールの文字数制限内に収まるのにも有益です。文字数は、スペースや演算子を含むルール文字列全体を含みます。
    • たとえば、次のルールは 59 文字です：(happy OR happiness) place_country:GB -birthday -is:retweet

​
引用Tweetのマッチング動作

filtered streamエンドポイントを使用する場合、オペレーターは引用された元のPostの内容と、引用Tweetに含まれる内容の両方にマッチします。 ただし、Search Posts エンドポイントは、引用された元のPostの内容にはマッチせず、引用Tweetの内容にのみマッチします。

​
ルールの反復的な構築

ルールを早期に、かつ頻繁にテストする
ルールが最初から「正しい」結果を返すことは稀です。X 上には膨大な量のものが存在し、最初は明らかでないかもしれないものが多く、上記のルール構文を目的の検索に合わせるのが難しい場合があります。ルールを作成する際には、ストリームエンドポイントを使用して定期的にテストし、どのようなデータを返すかを確認することが重要です。また、使用しているオペレーターがそのエンドポイントでも利用可能であることを前提に、投稿の検索 エンドポイントのいずれかを使用してテストすることもできます。 このセクションでは、以下のルールから始め、テスト中に受け取る結果に基づいて調整します： happy OR happiness
結果を活用してルールを絞り込む
ルールをテストするときは、返ってきた Post を確認し、期待する data が含まれているかを確認してください。まずは対象を広めに設定し、Post の一致を網羅的に取得しておくと、結果を見直して不要なものを除外するようにルールを絞り込めます。   例のルールをテストしたところ、さまざまな言語の Post が返ってきました。この場合は英語の Post のみを受け取りたいので、lang: 演算子を追加します: (happy OR happiness) lang:en テストでは、誕生日を祝う内容の Post が多数含まれていたため、否定キーワード演算子として -birthday を追加します。さらに、オリジナルの Post のみに絞るため、否定の -is:retweet 演算子も追加しました: (happy OR happiness) lang:en -birthday -is:retweet
必要に応じて包含を調整する
期待するデータを受け取っていないことに気づき、返されるはずの既存の投稿があることを知っている場合、目的のデータをフィルタリングして除外している可能性のある演算子を削除してルールを広げる必要があるかもしれません。 例として、個人タイムラインに探している感情を表現した他の投稿があり、テスト結果に含まれていなかったことに気づきました。より広いカバレッジを確保するため、excited と elated のキーワードを追加します。 (happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet Xではトレンドが素早く現れては消えていきます。ルールの維持は積極的なプロセスであるべきです。1つのルールをしばらく使用する予定の場合、受信しているデータを定期的に確認し、調整が必要かどうかをチェックすることをおすすめします。 例では、人々に「happy holidays」を願う投稿を受け取り始めたことに気づきました。これらの投稿を結果に含めたくないため、否定の -holidays キーワードを追加します。 (happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet -holidays

​
ルールの追加と削除

ストリームにルールを追加および削除する際は、POST /2/tweets/search/stream/rules エンドポイントを使用します。 ストリームに 1 つ以上のルールを追加するには、add JSON ボディを送信します。このボディは、ルールを含む value パラメータ、および返された投稿がこのルールに一致するかどうかを識別するために使用できる自由形式のテキストを含むオプションの tag パラメータからなるオブジェクトの配列を含みます。 例として、ストリームにルールのセットを追加しようとしている場合、cURL コマンドは次のようになります： 
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": "メディア付きの猫"},
    {"value": "cat has:media -grumpy", "tag": "メディア付きの幸せな猫"},
    {"value": "meme", "tag": "面白いもの"},
    {"value": "meme has:images"}
  ]
}'
同様に、ストリームから1つまたは複数のルールを削除するには、delete JSON ボディを送信します。このボディには、削除したいルールの ID を含む id パラメータの配列を指定します。 たとえば、ストリームから一連のルールを削除する場合、cURL コマンドは次のようになります： 
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"
      ]
    }
  }'
さまざまな言語のサンプルコードを Github で提供しています。

​
ルールの例

自然災害の追跡
次のルールは、2017年にヒューストンを襲ったハリケーン・ハービーについて言及する気象当局や観測所からのPostにマッチしました。 matching rules タグの使い方と、ルールを POST /2/tweets/search/stream/rules endpoint に送信する際に用いる必要があるJSON形式に注目してください。 
{
    "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": "テーマ:情報 位置情報あり 気象機関・観測所からのオリジナル"
}
会話のセンチメントのレビュー
次のルールは、ハッシュタグ #nowplaying を中心に展開する会話のセンチメントをより深く理解するために使用できますが、北米で公開された投稿からのみです。 
{
    "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 ポジティブ"
},
{
    "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 ネガティブ"
}
特定の Post アノテーションに関連する Post を検索する
このルールは、猫ではないペットの画像を含むオリジナル Post を検索するよう構築されており、Post で識別された言語が日本語のものを対象としています。これを行うために、context: 演算子を活用して Post annotation 機能を利用しました。まず、Post lookup エンドポイントと tweet.fields=context_annotations fields パラメータを使用して、クエリで使用する必要がある domain.entity ID を特定しました：
  • 猫に関連する Post は、domain 66 (Interests and Hobbies category) に entity 852262932607926273 (Cats) を返します。
  • ペットに関連する Post は、domain 65 (Interests and Hobbies Vertical) に entity 852262932607926273 (Pets) を返します。  
このルールは次のようになります： 
{
    "value": "context:65.852262932607926273 -context:66.852262932607926273 -is:retweet has:images lang:ja",
    "tag": "画像付きの日本語ペット - 猫以外"
}