Decahose API

このエンドポイントは、Post の編集メタデータを含むように更新されました。これらのメタデータの詳細は、“Edit Posts” の基本をご覧ください。

Decahose ストリーム

エンタープライズこれは当社のマネージドアクセスレベルでのみ利用可能なエンタープライズ API です。この API を利用するには、まず当社のエンタープライズ営業チームとアカウントを設定する必要があります。詳細 Decahose はストリーミング接続を通じて、リアルタイムの X Firehose の 10% のランダムサンプルを提供します。これは、X が firehose 経由で送信する際の想定どおりの低レイテンシー配信を維持しつつ、data をランダムに抽出するリアルタイムサンプリングアルゴリズムによって実現されています。以下は Decahose で利用可能な機能の一部です:

拡張・強化された URL: - 短縮 URL を完全に展開し、追加のメタデータ（ページタイトルと説明）を提供
ストリームのパーティショニング - 2 つのパーティション（各パーティションが Decahose ストリームのボリュームの 50% を保持）
信頼性の向上 - バックエンドシステムの地理的多様性

注: この data はバルク配信であり、追加のフィルタリング（例: キーワード）には対応していません。 ENTERPRISE

いいねのストリーミング

これは当社のマネージドアクセスレベルでのみ利用可能なエンタープライズ API です。この API を使用するには、まず当社のエンタープライズセールスチームとアカウントの設定を行う必要があります。詳細はこちら「いいね」は、誰が Post に「いいね」したかの把握と、正確な「いいね」数の提供を可能にします。Gnip の Firehose と Decahose は、Gnip を通じて配信される Post に関連する公開の「いいね」を配信できます。これにより、Post に紐づくリアルタイムの公開エンゲージメントとオーディエンス指標が得られます。 「いいね」を始めるにあたって 「いいね」データを取得するにあたり、次の点をご理解ください。

「いいね」は独立した個別のストリームで配信されます
「いいね」は以前は「Favorites」と呼ばれていました。拡張済みのネイティブ形式ペイロードはこの呼称を保持しています
ストリームには公開の「いいね」のみが含まれます
- 「公開」とは、「いいね」したユーザー、Post 作成者、および当該 Post がプラットフォーム上で公開であることを意味します
「いいね」は Retweet に非常によく似ており、公開のエンゲージメントシグナルを表します
ペイロード要素には以下が含まれます:
- 元の Post オブジェクト
- 元の Post を作成したアクターオブジェクト
- 「いいね」アクションを行ったアクターオブジェクト
元のコンテンツのみが「いいね」可能です
- Retweet は「いいね」できません。Retweet への「いいね」は元の Post に適用されます
- 引用した Tweet は「いいね」できます
「いいね」アクティビティには、該当する Gnip Enrichments（購入/適用済みの場合）が含まれます
対応製品 / 機能
- 「いいね」ストリームは Backfill をサポートします（購入/適用済みの場合）
- 「いいね」ストリームに Replay のサポートはありません
- 「いいね」には Search および Historical のサポートはありません
- 現時点で PowerTrack に「いいね」サポートを追加する予定はありません

Decahose

Decahose で配信される 10% サンプルの Post については、ストリームに該当する公開の「いいね」を 100% 含みます
パーティション: 2
URL 構造
- https://gnip-stream.x.com/stream/sample10-likes/accounts/<accountName>/publishers/twitter/<streamLabel>.json?partition=1

ネイティブ拡張形式ペイロード

{
   "id":"43560406e0ad9f68374445f5f30c33fc",
   "created_at":"Thu Dec 01 22:27:39 +0000 2016",
   "timestamp_ms":1480631259353,
   "favorited_status":{
      "created_at":"Thu Dec 01 22:27:16 +0000 2016",
      "id":804451830033948672,
      "id_str":"804451830033948672",
      "text":"@kafammheppduman",
      "source":"\u003ca href=\"http:\/\/x.com\/download\/android\" rel=\"nofollow\"\u003eX for Android\u003c\/a\u003e",
      "truncated":false,
      "in_reply_to_status_id":803694205163814912,
      "in_reply_to_status_id_str":"803694205163814912",
      "in_reply_to_user_id":2855759795,
      "in_reply_to_user_id_str":"2855759795",
      "in_reply_to_screen_name":"kafammheppduman",
      "user":{
         "id":2855759795,
         "id_str":"2855759795",
         "name":"delirdim kanka",
         "screen_name":"kafammheppduman",
         "location":"sanane",
         "url":"http:\/\/instagram.com\/kafammheppduman",
         "description":"Manit @GalatasaraySk \ud83d\udc9e",
         "translator_type":"none",
         "protected":false,
         "verified":false,
         "followers_count":3702,
         "friends_count":607,
         "listed_count":1,
         "favourites_count":113338,
         "statuses_count":389,
         "created_at":"Sat Nov 01 22:38:25 +0000 2014",
         "utc_offset":null,
         "time_zone":null,
         "geo_enabled":true,
         "lang":"tr",
         "contributors_enabled":false,
         "is_translator":false,
         "profile_background_color":"C0DEED",
         "profile_background_image_url":"",
         "profile_background_image_url_https":"",
         "profile_background_tile":false,
         "profile_link_color":"1DA1F2",
         "profile_sidebar_border_color":"C0DEED",
         "profile_sidebar_fill_color":"DDEEF6",
         "profile_text_color":"333333",
         "profile_use_background_image":true,
       "Profile_image_url": "http:\/\/pbs.twimg.com\/profile_images\/804421763945861121\/v3bp9pnq_normal.jpg",
         "Profile_image_url_https": "https:\/\/pbs.twimg.com\/profile_images\/804421763945861121\/v3bp9pnq_normal.jpg",
         "profile_banner_url":"https:\/\/pbs.twimg.com\/profile_banners\/2855759795\/1480630085",
         "default_profile":true,
         "default_profile_image":false,
         "following":null,
         "follow_request_sent":null,
         "notifications":null
      },
      "geo":null,
      "coordinates":null,
      "place":null,
      "contributors":null,
      "is_quote_status":false,
      "retweet_count":0,
      "favorite_count":0,
      "entities":{
         "hashtags":[],
         "urls":[],
         "user_mentions":[
            {
               "screen_name":"kafammheppduman",
               "name":"delirdim kanka",
               "id":2855759795,
               "id_str":"2855759795",
               "indices":[
                  0,
                  16
               ]
            }
         ],
         "symbols":[]
      },
      "favorited":false,
      "retweeted":false,
      "filter_level":"low",
      "lang":"und"
   },
   "user":{
      "id":774146932365070336,
      "id_str":"774146932365070336",
      "name":"Uyuyan Adam",
      "screen_name":"saykoMenn",
      "location":"Tarsus, T\u00fcrkiye",
      "url":"http:\/\/connected2.me\/pmc1i",
      "description":null,
      "translator_type":"none",
      "protected":false,
      "verified":false,
      "followers_count":414,
      "friends_count":393,
      "listed_count":0,
      "favourites_count":9868,
      "statuses_count":370,
      "created_at":"Fri Sep 09 07:26:26 +0000 2016",
      "utc_offset":null,
      "time_zone":null,
      "geo_enabled":false,
      "lang":"tr",
      "contributors_enabled":false,
      "is_translator":false,
      "profile_background_color":"F5F8FA",
      "profile_background_image_url":"",
      "profile_background_image_url_https":"",
      "profile_background_tile":false,
      "profile_link_color":"1DA1F2",
      "profile_sidebar_border_color":"C0DEED",
      "profile_sidebar_fill_color":"DDEEF6",
      "profile_text_color":"333333",
      "profile_use_background_image":true,
      "Profile_image_url": "http:\/\/pbs.twimg.com\/profile_images\/802992813424201728\/VMzcTL3x_normal.jpg",
      "Profile_image_url_https": "https:\/\/pbs.twimg.com\/profile_images\/802992813424201728\/VMzcTL3x_normal.jpg",
      "profile_banner_url":"https:\/\/pbs.twimg.com\/profile_banners\/774146932365070336\/1480283382",
      "default_profile":true,
      "default_profile_image":false,
      "following":null,
      "follow_request_sent":null,
      "notifications":null
   }
}

「いいね」削除 / 「いいね」解除のペイロード

{
   "delete":{
      "favorite":{
         "tweet_id":696615514970279937,
         "tweet_id_str":"696615514970279937",
         "user_id":2510287578,
         "user_id_str":"2510287578"
      },
      "timestamp_ms":"1480437031205"
   }
}

ガイド

リカバリーと冗長性

はじめに リアルタイムのPostを大量にストリーミングする場合、dataの信頼性と完全再現性を両立させるためのベストプラクティスがあります。リアルタイムdataを取り込む際は、接続時間を最大化することが基本目標です。切断が発生した場合は、自動的に検知して再接続することが重要です。再接続後は、バックフィルが必要な期間がないか評価する必要があります。これらの詳細を管理し、リアルタイムのPostを取り込むコンポーネントは、ネットワーク、データストア、サーバー、ストレージといった懸念を抱えるシステムの一部にすぎません。こうしたシステムの複雑さを踏まえた別のベストプラクティスとして、ストリーミング環境を分離し、少なくとも開発/テスト用と本番用にストリームを分けることが挙げられます。 Decahoseには、これらの取り組みを支援する一連の機能が用意されています。

複数の環境をサポートするため、アカウントに追加ストリームをデプロイできます。これらのストリームは互いに独立しており、区別のための異なるstream_labelを持ちます。
接続維持を支援するため、各Decahoseストリームは冗長接続をサポートしています。最も一般的なアーキテクチャは、1つのストリームに2つの接続を設け、クライアント側に独立した2つのコンシューマー（理想的には異なるネットワーク上）を配置する構成です。この設計により、クライアント側のネットワーク、サーバー、データストア経路にわたって冗長性を確保できます。各接続ではdataの完全コピーが配信されるため、クライアント側は重複dataを許容し、適切に管理する必要がある点に注意してください。
「heartbeat」は10秒ごとに送信されます。ただし、Decahoseストリームではdata量が十分に多いため、わずかな時間（例：数秒）でもPostがない場合は接続の問題を示す可能性があります。したがって、「dataの沈黙」とheartbeatの欠如の両方で切断を検知できます。

切断は発生し得るため、Decahoseストリームには、切断やその他の運用上の問題により取り逃したdataを回復するための専用のリカバリー機能とバックフィル機能があります。

追加ストリーム

Decahose のストリームを追加で用意することは、ソリューションの信頼性を高めるもう一つの方法です。追加ストリームは完全に独立しており、それぞれ固有のエンドポイントを持ちます。各ストリームには独自の stream_label が割り当てられ、このラベルとアカウント名がそのストリームの URL の一部になります。以下の例をご覧ください: https://gnip-stream.x.com/stream/sample10/accounts/:account_name/publishers/twitter/:stream_label.json 一般的な慣例として、本番システム専用のリアルタイムストリームとは別に、開発・テスト用の追加ストリームを用意します。テスト／開発ストリームがあることで、Decahose のお客様はクライアントコンシューマの更新を検証できます。ストリームには任意の（ユニークな）ラベルを割り当てられますが、慣例として本番ストリームには「prod」、開発用の追加ストリームには「dev」や「sandbox」を使用します。ストリーム数およびそれぞれの固有ラベルは、アカウント担当者によって設定可能です。 冗長接続 冗長接続とは、データストリームに対して同時に複数の接続を確立できるようにするものです。これにより、同じストリームに 2 つの別個のコンシューマで接続し、両方の接続で同一データを受信できるため、冗長性が確保されます。したがって、アプリは、片方のストリームが切断された場合やアプリのプライマリサーバーが障害を起こした場合などに備えたホットフェイルオーバーを持てます。特定のストリームに許可される接続数は、アカウント担当者によって設定可能です。冗長ストリームを利用するには、プライマリ接続と同じ URL に接続するだけです。ストリームの data は両方の接続を通じて送信され、両方のストリーム接続はストリームのダッシュボードに表示されます。課金上は、複数接続を通じて受け取るアクティビティ数を重複排除し、各ユニークなアクティビティにつき 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 は、直近の X の履歴データに対して、過去5日分のローリングウィンドウでストリーミングアクセスを提供するデータ復旧ツールです（一次データ収集には使用しないでください）。リアルタイムストリームでデータを取り逃した場合—短時間の切断によるものでも、その他の理由で一定期間リアルタイムデータの取り込みに失敗した場合でも—データの復旧にご利用ください。

Recovery の使用

Recovery ストリームを使うと、アプリはリアルタイムストリームと同様の方法でリクエストを送信できます。ただし、要求する時間範囲を示すパラメータを URL に指定する必要があります。言い換えると、Recovery リクエストは API に「時間Aから時間Bまでの Post」を要求します。これらの Post は、その後ストリーミング接続を通じて、リアルタイムストリームを模した形式で配信されますが、リアルタイムよりわずかに遅い速度になります。以下の例を参照してください: “https://stream-data-api.x.com/stream/powertrack/accounts/someAccountName/publishers/twitter/powertrack.json?startTime=2023-07-05T17:09:12.070Z” Post は、指定した期間の最初の（最も古い）1分から配信が始まり、最後の1分が配信されるまで時系列に配信されます。その時点で、Recovery Request Completed メッセージが接続経由で送信され、サーバーによって接続が閉じられます。リクエストが、一致する結果がほとんどない、または全くない時間帯から始まる場合、最初の結果が配信されるまでに時間がかかる可能性があります。これは、その時点で処理中のアーカイブ部分で Recovery が一致を検出した時に data が配信されるためです。配信できる結果がない場合でも、ストリームはタイムアウトを防ぐために、キャリッジリターン、いわゆる「ハートビート」を接続を通じて送り続けます。 Recovery は、短時間の切断によって取り逃がした data を容易に回収するためのツールであり、1日全体のような非常に長い期間を対象としたものではありません。長期間の data を回収する必要が生じた場合は、インターネットの不安定さなどによりリクエスト途中で切断される可能性を減らし、長時間リクエストの進行状況を把握しやすくするために、長いリクエストをより短い時間枠（例: 2時間）に分割することを推奨します。

データ可用性

5分間のバックフィル・ウィンドウ内に再接続できない場合でも、Recovery 機能を使って直近24時間の取り逃したデータを回復できます。ストリーミングの Recovery 機能により、バックフィルのウィンドウを24時間まで拡張できます。Recovery は、取り逃したデータの期間を「回復」するための機能です。‘start_time’ と ‘end_time’ のリクエストパラメータを指定して接続リクエストを行うと、リカバリー・ストリームが開始されます。接続されると、Recovery は指定された期間を再ストリームし、その後切断します。同時に2件の Recovery リクエスト、つまり「2つのリカバリー・ジョブ」を実行できます。Recovery は、開始時刻と終了時刻を指定する点を除き、技術的にはバックフィルと同様に動作します。リカバリーの期間は単一の時間範囲です。

バックフィル

バックフィルをリクエストするには、接続リクエストに backfillMinutes=N パラメータを追加します。N は接続時に遡って取得する分数（1～5、整数のみ）です。例えば、90秒間切断された場合は、接続リクエストに backfillMinutes=2 を指定してください。このリクエストでは切断前の30秒を含む2分間のバックフィルが提供されるため、コンシューマーアプリは重複するデータを許容できる必要があります。 Decahose の接続リクエスト URL の例（パーティション 1 に 5 分のバックフィルを要求）は次のとおりです: https://gnip-stream.x.com/stream/sample10/accounts/:account_name/publishers/twitter/:stream_label.json?partition=1&backfillMinutes=5 注:

接続時に常に ‘backfillMinutes=5’ を使用し、提供される重複データを後段で重複排除するという運用も可能です。
5分以上切断された場合は、Recovery を使用してデータを復旧できます。

切断からの復旧 切断からの再起動と復旧には、以下の手順が含まれます:

切断期間の特定
- 5分以下か？
  - ストリームで Backfill が有効な場合は、適切な ‘backfillMinutes’ パラメータを指定して接続リクエストを準備します。
- 5分を超えるか？
  - Recovery ストリームがある場合は、切断期間に対して Recovery リクエストを行います（必要に応じて Rules API を使用し、可能であれば現在のリアルタイムのルールセットで実行します）。
新しい接続をリクエストします。

切断やダウンタイムが発生した場合、以下の戦略で影響を軽減し、復旧してください:

バックフィルを実装する バックフィルにより、ストリーム接続から切断される前の時点に遡って再接続でき、最大5分の切断をカバーします。接続リクエストにパラメータを含めて実装します。
別拠点から冗長ストリームを取り込む 冗長ストリームを同一の本番環境に取り込み、データの重複排除が可能であれば、通常ストリームと冗長ストリームの両方で同時にダウンタイムや切断が発生しない限り、Recovery は不要です。冗長ストリームを本番環境へライブで取り込めない場合は、別の「緊急」データストアに書き込みます。そうしておけば、プライマリのストリーム接続に切断やダウンタイムが発生した際、欠落期間を補うデータを手元で確保できます。
Recovery を実装する 切断やダウンタイムがプライマリと冗長の両ストリームに影響する場合は、Decahose Recovery を使用して取り逃したデータを復旧します。API はアーカイブの5日分をカバーするローリングウィンドウを提供しており、そのウィンドウから1時間以内の範囲でリクエストし、ストリーミングするのが最適です。これはリアルタイムストリームと並行して行います。Recovery で提供される5日のウィンドウを超える Decahose のデータを復旧する手段はないため、重大なダウンタイムに備えて冗長ストリームを活用し、手元に完全なデータのコピーを確保しておくことが重要です。

異常な保存データ量を検知した場合 — 切断やダウンタイムが発生していないのにデータ欠落を検出する方法の例:

受信した Post をカウントする取り込みアプリの入り口で受信した生の Post 数をカウントし、その数を最終的なデータストアに到達した Post 数と比較できるようにします。差分を監視し、受信後にデータがドロップされる原因となる問題をチームにアラートできます。
異常な保存量を分析する最終データベースに保存されたデータ量を分析し、異常な減少がないか確認します。これも問題の兆候になり得ますが、状況によっては量の減少が正常な場合もあります（例: X プラットフォームが利用不可で、一定期間ユーザーが Post を作成できない場合）。

API リファレンス

Decahose ストリーム

このページの項目へ移動メソッド認証 GET /{stream-type}/:stream Replay API

メソッド

メソッド	説明
GET /{stream-type}/:stream	data ストリームに接続する

認証

Volume Stream API へのすべてのリクエストは、console.gnip.com のアカウントにログインする際に使用する有効なメールアドレスとパスワードの組み合わせで構成される HTTP ベーシック認証を使用する必要があります。各リクエストでは、認証情報を Authorization ヘッダーで送信する必要があります。したがって、すべての API リクエストに対し、クライアントが「Authorization: Basic」HTTP ヘッダー（HTTPS 上でエンコードした認証情報付き）を付与していることを確認してください。

GET :stream

Firehose ストリームへの永続接続を確立し、リアルタイムのdataがこの接続経由で配信されます。

リクエスト仕様


リクエストメソッド	HTTP GET
接続タイプ	Keep-Alive リクエストヘッダーで指定してください。
URL	ダッシュボードのストリーム用 API ヘルプページに記載されています。構成は次のとおりです。 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 リクエスト。
バックフィルパラメーター	Backfill が有効なストリームを購入している場合、GET リクエストに “backfillMinutes” パラメーターを追加して有効化してください。
読み取りタイムアウト	クライアントで読み取りタイムアウトを設定し、30 秒を超える値にしてください。
Tweet 編集のサポート	すべての Tweet オブジェクトには、その Tweet の編集履歴を示す Tweet 編集メタデータが含まれます。詳細は「“Edit Tweets” の基本」を参照してください。

レスポンス

これらのリクエストに対して、API は次のレスポンスを返す場合があります。ほとんどのエラーコードは、本文に追加の詳細を含む文字列とともに返されます。200 以外のレスポンスの場合、クライアントは再接続を試みてください。

ステータス	テキスト	説明
200	成功	接続は正常に確立され、以降は新しいアクティビティが到着次第送信されます。
401	認証失敗	無効な認証情報により HTTP 認証に失敗しました。リクエストで正しく使用していることを確認するため、認証情報で console.gnip.com にログインしてください。
406	受理不可	一般的には、クライアントがストリームの gzip エンコードを受け入れるためのヘッダーを正しく含めていない場合に発生しますが、他の状況でも発生することがあります。次のような JSON メッセージが含まれます: “この接続には圧縮が必要です。圧縮を有効にするには、リクエストに ‘Accept-Encoding: gzip’ ヘッダーを送信し、クライアント側で読み取り時にストリームを解凍できるようにしてください。“
429	レート制限	アプリが接続リクエストの上限を超えました。
503	サービス利用不可	X サーバー側の問題です。指数バックオフで再接続してください。この問題に関する通知が X API Status Page に掲載されていない場合、10 分経っても接続できないときはサポートまたは緊急窓口に連絡してください。

curl リクエストの例

次の例では、コマンドラインで cURL を使用してリクエストを行います。なお、これらのリクエストは任意のプログラミング言語から送信することもできます。

curl --compressed -v -uexample@customer.com "https://gnip-stream.x.com/stream/firehose/accounts/:account\_name/publishers/twitter/:stream\_label.json?partition={#}"

Replay API

Replay API は、リアルタイムの Volume ストリームを補完する重要な機能です。Replay は、直近の X の履歴データに対して、スライディングウィンドウ方式でストリーミングアクセスを提供するデータ復旧ツールです。

概要

ポスト

ユーザー

ダイレクトメッセージ

いいね

リスト

スペース

コミュニティ

コミュニティノート

トレンド

メディア

Xのアクティビティ

利用方法

ストリーム接続

法令遵守

エンタープライズ v2

いいねストリーム

GNIP 2.0

Decahose API

Decahose ストリーム

いいねのストリーミング

ガイド

リカバリーと冗長性

追加ストリーム

概要

Recovery の使用

データ可用性

バックフィル

API リファレンス

Decahose ストリーム

メソッド

認証

GET :stream

リクエスト仕様

レスポンス

curl リクエストの例

Replay API

概要

ポスト

ユーザー

ダイレクトメッセージ

いいね

リスト

スペース

コミュニティ

コミュニティノート

トレンド

メディア

Xのアクティビティ

利用方法

ストリーム接続

法令遵守

エンタープライズ v2

いいねストリーム

GNIP 2.0

​Decahose ストリーム

​いいねのストリーミング

​ガイド

​リカバリーと冗長性

​追加ストリーム

​概要

​Recovery の使用

​データ可用性

​バックフィル

​API リファレンス

​Decahose ストリーム

​メソッド

​認証

​GET :stream

​リクエスト仕様

​レスポンス

​curl リクエストの例

​Replay API

Decahose ストリーム

いいねのストリーミング

ガイド

リカバリーと冗長性

追加ストリーム

概要

Recovery の使用

データ可用性

バックフィル

API リファレンス

Decahose ストリーム

メソッド

認証

GET :stream

リクエスト仕様

レスポンス

curl リクエストの例

Replay API