核心概念

监控目标和关键词是两回事

监控目标是你监视的账号;它做的一切你都会收到,也可以只收你选定的事件类型。关键词是你在整个 X 上监视的查询;任何人发的匹配帖子都会以 search.match 事件发给你。监控目标由用户名标识,关键词由查询文本标识;一个密钥可以持有任意数量的两者,上限由其套餐决定。

账号以 id 为准,而不是用户名

你监控的是一个账号,以它的 X 数字 id 标识(Target 上的 id)。账号随时可能修改用户名(screen_name)或显示名:你会继续收到它的事件,之后的事件在 target.screen_name 中带新用户名,并会有一条 profile.screen_name 或 profile.name 事件告诉你改了什么。请以 id 作为记录的主键。API 中凡是需要指定账号的地方,都可以用它的 user_id、当前用户名或以前用过的用户名。

两阶段投递:先 create,再 update

有些帖子事件分两帧投递。第一帧 op: "create" 携带要点——帖子 id、作者和文本——让你可以立即采取行动。片刻之后,同一个事件 id 会以 op: "update" 再次到达,这次带上媒体、被引用或被回复的原帖、计数以及其余内容。首次出现时就已完整的事件没有第二帧;GET /v1/meta/event-types 说明哪些类型可能有第二帧。

该怎么做。 要速度,就对 create 采取行动。要完整帖子,就等同一个 id 的 update。无论哪种,都以 id 为键存储,并让后到的 update 覆盖已保存的内容。两帧之间类型只有一种可能的变化:带 kind_final: false 的第一帧 tweet.create 可能变成 tweet.quote。如果你对原创和引用分别处理,请等这种帧的 update 到达后再归类。

至少一次,绝非恰好一次

每个被监控的账号都同时由多条独立路径监视,因此一条路径失效不会让你有任何损失。最先报告某个变化的路径胜出并成为事件;其他路径只记录为佐证,不会再次投递。但跨越一次重连时,你可能会看到已经收到过的事件。请按 id 去重。

位置与回放

每个事件都带一个 sid——它在我们日志中的位置。持久化你处理过的最后一个;重连时以 ?last_id= 传入,我们会先发送它之后的所有事件,再恢复实时。日志保留 24 小时,单次重连最多回放 5,000 个事件。连接打开期间新增的监控目标或关键词会在 30 秒内开始在该连接上流动;不需要重连。