このエンドポイントは、ポストの編集メタデータを含むように更新されました。これらのメタデータの詳細については、「ポストを編集する」の基本事項ページを参照してください。
Decahose ストリーム
Enterprise これは、マネージドアクセスレベルでのみ利用可能な Enterprise API です。この API を利用するには、まず Enterprise セールスチームを通じてアカウントを開設する必要があります。 詳細はこちら Decahose は、ストリーミング接続を通じて、リアルタイムの X Firehose の全体の 10% にあたるランダムサンプルを提供します。これは、リアルタイムサンプリングアルゴリズムによってデータをランダムに選択しつつ、X から Firehose 経由で送信されるデータを期待どおりの低レイテンシで配信できるようにすることで実現されています。 以下は、Decahose で利用可能な主な機能です。- 拡張・強化された URL: - 短縮 URL を完全に展開し、追加のメタデータ (ページタイトルと説明文) を提供
- ストリームのパーティショニング - 2 つのパーティションで構成され、それぞれが Decahose ストリーム全体ボリュームの 50% を保持
- 信頼性の向上 - バックエンドシステムの地理的分散
ENTERPRISE
いいねのストリーミング
- いいねは独立した専用ストリームとして配信されます
- いいねは、これまで「Favorites」と呼ばれてきました。拡張済みネイティブ形式のペイロードでもこの名称が保持されています
- ストリームにはパブリックいいねのみが含まれます
- パブリックとは、いいねしたユーザー、投稿作成者、および投稿がすべてプラットフォーム上で公開状態であることを意味します
- いいねはリツイートと非常によく似ており、公開されたエンゲージメントシグナルを表します
- ペイロード要素には次が含まれます:
- 元の投稿オブジェクト
- 元の投稿を作成したアクターオブジェクト
- いいねアクションを実行したアクターオブジェクト
- オリジナルコンテンツのみがいいねの対象になります
- リツイートにはいいねできません。リツイートに対するいいねは元の投稿に適用されます
- 引用ツイートには いいねできます
- いいねのアクティビティには、該当する Gnip Enrichments (購入・適用されている場合) が含まれます
- サポートされるプロダクト / 機能
- いいねストリームは Backfill をサポートします (購入・適用されている場合)
- いいねストリームには Replay のサポートはありません
- いいねに対する Search または Historical のサポートはありません
- PowerTrack にいいねのサポートを追加する即時の計画はありません
- Decahose で配信される 10% サンプルの投稿に対して、ストリームには該当するパブリックいいねが 100% 含まれます
- パーティション: 2
- URL 構造
ガイド
リカバリと冗長性
- 複数の環境をサポートするために、アカウントに対して追加ストリームをデプロイできます。これらのストリームは互いに独立しており、それぞれを区別するための異なる stream_label を持ちます。
- 接続維持を支援するため、各 Decahose ストリームは冗長接続をサポートしています。最も一般的なアーキテクチャは、1 つのストリームに 2 つの接続があり、クライアント側には 2 つの独立したコンシューマーが存在する構成で、理想的には異なるネットワーク上に配置します。この設計により、クライアント側のネットワーク、サーバー、およびデータストア経路にまたがって冗長性を持たせることができます。各接続ではデータの完全なコピーが配信されるため、クライアント側は重複データを許容し、管理できる必要がある点に注意してください。
- 「ハートビート」が 10 秒ごとに送信されます。ただし、Decahose ストリームではデータ量が十分に多いため、短い期間 (数秒程度) でも投稿がない場合は、接続に問題が発生している可能性があります。したがって、データの「無送信状態」とハートビートの欠如の両方を、切断検知に利用できます。
追加ストリーム
stream_label が割り当てられ、このラベルとアカウント名がそのストリームの URL の一部になります。以下の例を参照してください。
https://gnip-stream.x.com/stream/sample10/accounts/:account_name/publishers/twitter/:stream_label.json
最も一般的な慣例は、本番システム専用のリアルタイムストリームを 1 つ用意し、開発およびテスト用に追加ストリームを 1 つ用意することです。テスト/開発用ストリームを持つことで、Decahose のお客様はクライアントコンシューマの更新をテストするためのストリームを確保できます。任意の (一意な) ラベルをストリームに割り当てることができますが、1 つの慣例として、本番ストリームには「prod」、追加の開発用ストリームには「dev」または「sandbox」を使用します。
ストリームの数とそれぞれの一意なラベルは、アカウント担当者によって設定できます。
冗長接続
冗長接続とは、データストリームに対して複数の同時接続を確立できるようにすることを指します。これにより、2 つの別々のコンシューマから同じストリームに接続し、両方の接続を通じて同じデータを受信することで冗長性が提供されます。したがって、例えば一方のストリームが切断された場合や、アプリケーションのプライマリサーバーが障害を起こした場合など、さまざまな状況に対してホットフェイルオーバーを実現できます。
特定のストリームに対して許可される接続数は、アカウント担当者によって設定できます。冗長ストリームを利用するには、プライマリ接続で使用しているものと同じ URL に接続するだけです。ストリームのデータは両方の接続を通じて送信され、両方のストリーム接続はストリームダッシュボード上に表示されます。
課金の観点からは、複数接続を通じて受信したアクティビティ数について重複排除を行い、それぞれの一意なアクティビティについてのみ 1 回分の料金が請求される点に注意してください。Decahose には 2 つのパーティションがあるため、接続数がどのようにカウントされるかを以下に例示します。
Connect to decahose partition=1
Connect to decahose partition=1
Connect to decahose partition=2
上記の状況では合計 3 つの接続が存在します。partition=1 への接続が 2 つ、partition=2 への接続が 1 つです。通常は各パーティションに対して同じ数の接続を確保することが望ましいため、この例は partition=2 への冗長接続が切断され、さらなる調査が必要な状況を示しています。
リカバリー
概要
Recovery の使用
データ可用性
start_time と end_time のリクエストパラメータを使用して接続リクエストを行うと、リカバリストリームが開始されます。接続が確立されると、Recovery は指定された時間範囲のデータを再ストリーミングし、その後切断します。
Recovery には同時に 2 件のリクエストを行うことができ、つまり「2 つのリカバリジョブ」を同時に実行できます。Recovery は、開始時刻と終了時刻が定義される点を除き、技術的にはバックフィルと同じように動作します。1 回のリカバリ期間は、単一の時間範囲に対して行われます。
バックフィル
- 接続のたびに常に「backfillMinutes=5」を使用し、提供される重複データを処理する、という運用も可能です。
- 5 分を超えて切断された場合は、Recovery を使用してデータを復旧できます。
- 切断期間の長さを判断する。
- 5 分以下か?
- ストリームで Backfill を有効にしている場合は、適切な「backfillMinutes」パラメータを指定した接続リクエストを準備します。
- 5 分より長いか?
- Recovery ストリームがある場合は、切断されていた期間について Recovery リクエストを行います (必要であれば Rules API を使用して、可能な限り現在のリアルタイムルールセットで行うのが理想的です) 。
- 5 分以下か?
- 新しい接続をリクエストする。
-
バックフィルを実装する
バックフィルを使用すると、ストリーム接続から切断される前の時点から再接続でき、最大 5 分間の切断をカバーできます。これは接続リクエストにパラメータを含めることで実装されます。 -
別の場所から冗長ストリームを取り込む
冗長ストリームを同じ本番環境にストリーミングし、データの重複排除ができるのであれば、通常のストリームと冗長ストリームの両方で同時にダウンタイムや切断が発生しない限り、Recovery を行う必要はなくなります。冗長ストリームを本番環境にライブでストリーミングできない場合は、別の「緊急用」データストアに書き込むことができます。そのうえで、プライマリストリーム接続で切断やダウンタイムが発生した際には、その期間に欠損しているデータをプライマリデータベースに補完するためのデータを、システム側で確保しておくことができます。 -
Recovery を実装する
切断やダウンタイムがプライマリストリームと冗長ストリームの両方に影響する場合は、Decahose Recovery を使用して欠損データを復旧します。API にはアーカイブ 5 日分を対象とするローリングウィンドウが用意されており、そのウィンドウのうち 1 回あたり 1 時間分以下をリクエストしてストリーミングする形で利用するのが最適です。これはリアルタイムストリームと並行して実行します。Recovery が提供する 5 日間のウィンドウより前の Decahose データを復旧する手段はないため、重大なダウンタイムが発生した場合でも自社側で完全なデータコピーを保持できるよう、冗長ストリームを活用することが重要です。
切断やダウンタイムが発生していないのに欠損データを検知する可能性のある方法としては、次のようなものがあります。
-
受信した投稿数をカウントする
システムは、取り込みアプリの最初の段階で受信した生の投稿数をカウントし、その数と最終的なデータストアに到達した投稿数を比較できるようにすべきです。差分を監視することで、受信後にデータがドロップされる原因となっている問題をチームに通知できます。 -
異常な保存ボリュームを分析する
最終データベースに保存されているデータ量を分析し、異常な落ち込みがないかを確認することも有用です。これも問題の兆候になり得ますが、ボリュームが減少しても問題ない状況 (たとえば、X プラットフォームが利用できず、一定期間ユーザーが投稿を作成できない場合) も存在する点には留意してください。
APIリファレンス
Decahose stream
メソッド
| メソッド | 説明 |
|---|---|
| GET /{stream-type}/:stream | データストリームへ接続 |
GET :stream
リアルタイムのデータが配信される Firehose ストリームへの永続的な接続を確立します。リクエスト仕様
| リクエストメソッド | HTTP GET |
| 接続タイプ | Keep-Alive リクエストのヘッダーで指定してください。 |
| URL | ダッシュボードのストリームAPI Helpページに記載されており、以下の構造になっています: Decahose: https://gnip-stream.x.com/stream/sample10/accounts/:account_name/publishers/twitter/:stream_label.json?partition=1 |
| パーティション(必須) | partition=\{#} - フルストリームを利用するには、パーティショニングが必須です。パーティションパラメータを指定してストリームに接続してください。各ストリームのパーティション数は以下の通りです:* Decahose: 2パーティション |
| 圧縮 | Gzip。Gzip圧縮を使用してストリームに接続するには、接続リクエストにAccept-Encodingヘッダーを送信してください。ヘッダーは以下のようになります: Accept-Encoding: gzip |
| 文字エンコーディング | UTF-8 |
| レスポンス形式 | JSON。リクエストのヘッダーでレスポンスのJSON形式を指定してください。 |
| レート制限 | 60秒あたり10リクエスト |
| バックフィルパラメータ | バックフィルが有効なストリームを購入した場合、GETリクエストに「backfillMinutes」パラメータを追加して有効化してください。 |
| 読み取りタイムアウト | クライアントに読み取りタイムアウトを設定し、30秒を超える値に設定してください。 |
| ツイート編集のサポート | すべてのツイートオブジェクトには、ツイートの編集履歴を示すツイート編集メタデータが含まれます。詳細については、「ツイートの編集」基礎ページを参照してください。 |
レスポンス
| ステータス | テキスト | 説明 |
|---|---|---|
| 200 | Success | 接続が正常に確立され、以後は新しいアクティビティが到着し次第送信されます。 |
| 401 | Unauthorized | 無効な認証情報が原因で HTTP 認証に失敗しました。console.gnip.com に自身の認証情報でログインし、リクエストで正しく使用できていることを確認してください。 |
| 406 | Not Acceptable | 一般的には、クライアントがストリームからの gzip エンコーディングを受け入れるためのヘッダーを正しく含めていない場合に発生しますが、その他の状況でも発生する可能性があります。 「この接続には圧縮が必要です。圧縮を有効にするには、リクエストに ‘Accept-Encoding: gzip’ ヘッダーを送信し、クライアント側でストリームを読み取る際に解凍できるよう準備してください。」という内容に類似した JSON メッセージが含まれます。 |
| 429 | Rate Limited | App が接続リクエストの上限を超過しました。 |
| 503 | Service Unavailable | Twitter サーバー側の問題です。指数バックオフパターンを用いて再接続してください。この問題について X API Status Page に通知が投稿されていない状態で、10 分経過しても接続できない場合は、サポートまたは緊急連絡先にお問い合わせください。 |