跳转到主要内容

​
为过滤流构建规则

过滤流端点会根据应用于流的一组规则，向你传递匹配条件的 Post。规则由用于匹配多种 Post 属性的运算符组成。 你可以使用 POST /tweets/search/stream/rules 端点将多个规则应用到同一个流。一旦添加规则并通过 GET /tweets/search/stream 端点连接到你的流，只有符合这些规则的 Post 才会通过持久的流式连接传送。你无需断开与流的连接即可添加或移除规则。 

​
目录

​
创建规则

​
规则限制

可创建的规则数量取决于应用于你的Project的访问级别。 你可以在过滤流简介页面了解这些限制的适用方式。

​
运算符类型：独立版 与 需要使用连词

独立版运算符可以单独使用，也可以与任何其他运算符（包括那些需要使用连词的运算符）搭配使用。 例如，下面的规则可行，因为它使用了独立版的 #hashtag 运算符： #xapiv2 需要使用连词的运算符不能在规则中单独使用；只有当规则中至少包含一个独立版运算符时，才能使用它们。原因是这些运算符单独使用会过于宽泛，可能匹配到极大量的 Post。 例如，以下规则不受支持，因为它们只包含需要使用连词的运算符： has:media has:links OR is:retweet 如果我们加入一个独立版运算符，例如短语 "X data"，该规则就可以正常生效。 "X data" has:mentions (has:media OR has:links)

​
布尔运算符与分组

如果你想在单个规则中串联多个运算符，可使用以下方法：
AND 逻辑相邻运算符之间以空格分隔将产生布尔 “AND” 逻辑，即只有同时满足两个条件时才会匹配到 Posts。例如，snow day #NoSchool 将匹配包含术语 snow 和 day 以及话题标签 #NoSchool 的 Posts。
OR 逻辑相邻运算符之间使用 OR 将产生 OR 逻辑，即只要满足任一条件就会匹配到 Posts。例如，指定 grumpy OR cat OR #meme 将匹配任何至少包含术语 grumpy 或 cat，或包含话题标签 #meme 的 Posts。
NOT 逻辑（取反）在关键字（或任何运算符）前加短横线（-）可将其取反（NOT）。例如，cat #meme -grumpy 将匹配包含话题标签 #meme 和术语 cat 的 Posts，但前提是不包含术语 grumpy。一个常见的规则子句是 -is:retweet，它不会匹配 Retweets，从而仅匹配原始 Posts、Quote Tweets 和回复。所有运算符都可取反，但取反的运算符不能单独使用。
分组你可以使用括号将运算符分组。例如，(grumpy cat) OR (#meme has:images) 将返回包含术语 grumpy 和 cat 的 Posts，或包含图片且带有话题标签 #meme 的 Posts。注意先应用 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 将被评估为 (iphone ipad) OR android
为消除歧义并确保规则按预期进行评估，请在适当位置使用括号将术语分组。 例如：
  • (apple OR iphone) ipad
  • iphone (ipad OR android)

​
标点符号、变音符号和大小写敏感性

如果你在规则中指定了带有重音或变音符号的关键词或话题标签，它将只匹配包含该词且带有相应重音或变音符号的 Posts，而不会匹配仅包含相同字母但缺少重音或变音符号的内容。 例如，包含关键词 diacrítica 或话题标签 #cumpleaños 的规则会匹配包含 diacrítica 或 #cumpleaños 的 Posts，因为它们包含相应的重音或变音符号。但这些规则不会匹配包含 Diacritica 或 #cumpleanos 且缺少带重音的 í 或字母 ñ 的 Posts。 带有重音或变音符号的字符与普通字符相同对待，并不会被视为词边界。例如，包含关键词 cumpleaños 的规则只会匹配包含单词 cumpleaños 的 Posts，而不会匹配包含 cumplea、cumplean 或 os 的 Posts。 所有运算符的评估均不区分大小写。例如，规则 cat 会匹配以下所有形式：cat、CAT、Cat。
Search Posts 的匹配行为与过滤流不同。在构建 Search Posts 查询时，请注意，包含重音或变音符号的关键词和话题标签会同时匹配带有这些重音或变音符号的术语，以及使用普通字符的术语。例如，包含关键词 Diacrítica 或话题标签 #cumpleaños 的 Search Posts 查询，会匹配 Diacrítica 和 #cumpleaños，也会匹配不带重音 í 或字母 ñ 的 Diacritica 或 #cumpleanos。

​
具体性与效率

当你开始构建规则时，务必牢记以下几点。
  • 一般不建议为规则使用宽泛的、独立版的运算符，例如单个关键词或#hashtag，因为这很可能会匹配到海量的Post。创建更完善的规则将得到更具体的一组匹配的Post，并有望减少你在负载中为寻找有价值洞见而需要筛选的噪声。 
    • 例如，如果你的规则只是关键词 happy，你每天很可能会获得 200,000 - 300,000 条Post。
    • 添加更多条件运算符可以缩小搜索结果范围，例如 (happy OR happiness) place_country:GB -birthday -is:retweet
  • 编写高效的规则还有助于遵守规则长度的字符限制。字符计数包含整个规则字符串，包括空格和运算符。
    • 例如，以下规则长度为 59 个字符：(happy OR happiness) place_country:GB -birthday -is:retweet

​
引用 Tweet 的匹配行为

使用过滤流端点时，运算符会同时匹配被引用的原始 Post 的内容，以及该引用 Tweet 中包含的内容。 但请注意，Search Posts 端点不会匹配被引用的原始 Post 的内容，只会匹配引用 Tweet 本身的内容。

​
迭代式构建规则

及早且频繁地测试你的规则
第一次就让规则返回“正确”的结果并不常见。X 上的信息量巨大，许多细节起初未必显而易见，而上文所述的规则语法也可能不易精准匹配你的预期搜索。在构建规则时，务必定期通过流式端点进行测试，以查看它返回的 data。你也可以使用任一 Search Post 端点进行测试，前提是你使用的运算符也受该端点支持。  在本节中，我们将从以下规则开始，并根据测试得到的结果进行调整：  happy OR happiness
使用结果来缩小规则范围
在测试规则时，你应当查看返回的 Posts，确认它们是否包含你期望接收的 data。先从较宽泛的规则和更大的 Post 匹配集合开始，便于审查结果，再逐步收紧规则以过滤掉不需要的结果。 当我们测试示例规则时，注意到返回了多种语言的 Posts。在这种情况下，我们只想接收英文的 Posts，因此将添加 lang: 运算符： (happy OR happiness) lang:en 测试结果中有不少向他人送上生日祝福的 Posts，因此我们将添加 -birthday 作为否定关键词运算符。我们还只想接收原创的 Posts，所以添加了否定的 -is:retweet 运算符： (happy OR happiness) lang:en -birthday -is:retweet
在需要的地方扩大包含范围
如果你发现未收到预期的 data，且确认存在应当返回的 Posts，则可能需要通过移除可能过滤掉目标 data 的运算符来放宽规则。 在我们的示例中，我们注意到个人时间线中还有其他表达目标情绪的 Posts，但未被包含在测试结果中。为提升覆盖度，我们将添加关键词 excited 和 elated。 (happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet X 上的趋势变化很快。维护你的规则应是一个持续的过程。如果你打算在一段时间内使用单一规则，建议定期查看你接收到的 data，评估是否需要进行调整。 在我们的示例中，我们注意到开始收到一些祝人们“节日快乐”的 Posts。由于我们不希望这些 Posts 出现在结果中，我们将添加一个否定关键词 -holidays。 (happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet -holidays

​
添加与移除规则

在同时向流中添加或删除规则时，请使用 POST /2/tweets/search/stream/rules 端点。 要向流中添加一个或多个规则，请提交一个 add JSON 正文，其中包含一个数组；数组中的对象需包含带有规则的 value 参数，以及可选的 tag 参数。tag 可填写任意文本，便于你识别哪些返回的 Post 匹配该规则。 例如，如果你要向流中添加一组规则，你的 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"}
  ]
}'
同样地，要从你的流中删除一个或多个规则，请提交一个 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 年袭击休斯敦的飓风 Harvey 的 Post。请注意使用了匹配规则标签，以及在将规则提交到 POST /2/tweets/search/stream/rules 端点时所需的 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": "theme:info has:geo 来自气象机构与测站的原始信息"
}
审视对话的情感
下一个规则可用于更好地理解围绕话题标签“#nowplaying”展开的对话情感，但仅限于来自北美地区发布的 Post。 
{
    "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 注释相关的 Posts
此规则用于搜索原始 Posts：内容包含非猫类宠物的图片，且该 Post 的识别语言为日语。为此，我们使用 context: 运算符来利用 Post 注释 功能。我们首先使用 Post 查询 端点，并通过 tweet.fields=context_annotations fields 参数识别需要在查询中使用的 domain.entity ID：
  • 与猫相关的 Posts 返回 domain 66（兴趣与爱好类别），entity 852262932607926273（Cats）。
  • 与宠物相关的 Posts 返回 domain 65（兴趣与爱好垂直），entity 852262932607926273（Pets）。
以下是该规则的示例： 
{
    "value": "context:65.852262932607926273 -context:66.852262932607926273 -is:retweet has:images lang:ja",
    "tag": "日语宠物图片帖子 - 不含猫"
}