基本概念
監視対象とキーワードは別物です
監視対象は監視するアカウントで、そのアカウントのあらゆる動き、または選んだイベント種類だけが届きます。キーワードは X 全体を対象に監視するクエリで、誰の投稿であれマッチしたものが search.match イベントとして届きます。監視対象はハンドルで、キーワードはクエリのテキストで識別され、1 つのキーはプランの上限までそれぞれをいくつでも持てます。
アカウントはハンドルではなく ID で決まる
監視するのはアカウントで、数値の X ID (Target の id) で識別されます。アカウントはいつでもハンドル (screen_name) や表示名を変更できます。その後もイベントは届き続け、以降のイベントは target.screen_name に新しいハンドルを持ち、profile.screen_name または profile.name イベントで変更内容が通知されます。記録のキーは id にしてください。API でアカウントを指定する箇所では、user_id、現在のハンドル、以前のハンドルのいずれでも指定できます。
2 段階配信: create の後に update
一部の投稿イベントは 2 つのフレームで配信されます。最初の op: "create" は要点 (投稿 ID、投稿者、テキスト) だけを持ち、直ちに処理を始められます。少し後に同じイベント ID が op: "update" として再度届き、この時点でメディア、引用元や返信先の元投稿、各種カウント、その他すべてが含まれます。最初から完全な形のイベントには 2 つ目のフレームはありません。どの種類にそれがあり得るかは GET /v1/meta/event-types が示します。
create の時点で処理してください。投稿全体が必要なら、同じ id の update を待ってください。いずれの場合も、ストレージのキーは id にして、後から届く update で上書きされるようにしてください。2 つのフレームの間で種類が変わるのは 1 通りだけです。kind_final: false を持つ最初の tweet.create が tweet.quote になることがあります。オリジナル投稿と引用を別々に扱うなら、そのようなフレームは update が届いてから振り分けてください。At-least-once であり、exactly-once ではありません
監視対象の各アカウントは、複数の独立した経路で同時に監視しているため、経路が 1 つ落ちても失うものはありません。ある変更を最初に報告した経路がイベントになり、他は再配信されずに裏付けとして記録されます。ただし再接続をまたぐと、すでに受け取ったイベントが再び届くことがあります。id で重複排除してください。
位置とリプレイ
各イベントには当社のログ内での位置を示す sid があります。最後に処理したものを永続化しておき、再接続時に ?last_id= として渡すと、その後のすべてを送ってからライブ配信に戻ります。ログは 24 時間分保持され、1 回の再接続でリプレイされるのは最大 5,000 イベントです。ソケットを開いたまま追加した監視対象やキーワードは 30 秒以内にそのソケットに流れ始めるので、再接続は不要です。