メインコンテンツへスキップ
このendpointは、Postの編集metadataを含むように更新されました。これらのmetadataの詳細は、“Edit Posts” の基礎をご覧ください。

​
Decahose stream

Enterprise これはマネージドアクセスレベルでのみ利用可能な Enterprise API です。この API を使用するには、まず当社の Enterprise 営業チームとアカウント契約を設定する必要があります。 詳細はこちら Decahose は、ストリーミング接続を通じて、リアルタイムの X Firehose からランダムに抽出した 10% のサンプルを提供します。これは、ランダムに data を選択しつつ、X が Firehose で送信する際に期待される低レイテンシーの配信を維持するリアルタイムサンプリングアルゴリズムによって実現されます。 以下は、Decahose で利用可能な機能の一部です:
  • 拡張・強化された URL: - 短縮 URL を完全に展開し、追加の metadata（ページタイトルと説明）を提供
  • Stream partitioning - 2 つのパーティション（各パーティションが Decahose stream のボリュームの 50% を保持）
  • 信頼性の向上 - バックエンドシステムの地理的冗長化
注: この data は一括配信であり、追加のフィルタリング（例: キーワード）には対応していません。 ENTERPRISE

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

これは当社のマネージドアクセスレベルでのみ利用可能な Enterprise API です。この API を使用するには、まず当社の Enterprise セールスチームとアカウントの設定を行う必要があります。 詳しくはこちら いいねは、誰が Posts を like しているかに関するインサイトと、正確ないいね数を提供します。Gnip の Firehose および Decahose は、Gnip を通じて配信される Posts に関連する公開いいねを配信できます。これにより、Post に紐づくリアルタイムの公開エンゲージメントやオーディエンス metrics を把握できます。   Likes の始め方 likes data を利用するにあたり、次の点をご確認ください:
  • Likes は独立した専用の stream で配信されます
  • Likes は歴史的に「Favorites」と呼ばれてきました。拡張されたネイティブ形式のペイロードではこの命名が維持されています
  • Streams には公開いいねのみが含まれます
    • 公開とは、いいねしたユーザー、Post の作成者、Post のすべてがプラットフォーム上で公開であることを意味します
  • Likes はリツイートに非常に似ており、公開のエンゲージメントシグナルを表します
  • ペイロード要素には以下が含まれます:
    • 元の Post オブジェクト
    • 元の Post を作成した Actor オブジェクト
    • いいねアクションを実行した Actor オブジェクト
  • オリジナルコンテンツのみにいいねできます
    • リツイートにはいいねできません。リツイートへのいいねは元の Post に適用されます
    • 引用した Tweet はいいねが_可能_です
  • いいねアクティビティには、該当する Gnip Enrichments（購入/適用済みの場合）が含まれます
  • 対応製品 / 機能
    • Likes stream は Backfill をサポートします（購入/適用済みの場合）
    • likes stream に Replay のサポートはありません
    • likes に対する Search および Historical のサポートはありません
    • 現時点で PowerTrack に likes のサポートを追加する予定はありません
Decahose ネイティブ拡張形式のペイロード 
{
   "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
   }
}
Like の削除 / 「いいね」解除ペイロード 
{
   "delete":{
      "favorite":{
         "tweet_id":696615514970279937,
         "tweet_id_str":"696615514970279937",
         "user_id":2510287578,
         "user_id_str":"2510287578"
      },
      "timestamp_ms":"1480437031205"
   }
}

​
ガイド

​
復旧と冗長性

はじめに  大量のリアルタイムな Posts をストリーミングする際には、data の信頼性と完全性（フルフィデリティ）を確保するためのベストプラクティスが存在します。リアルタイム data を取り込むにあたっては、接続をできるだけ長く維持することが基本目標です。切断が発生した場合は自動的に検知して再接続することが重要です。再接続後は、バックフィルが必要な期間がないかを確認する必要があります。これらの詳細を管理し、リアルタイムの Posts を消費するコンポーネントは、ネットワーク、データストア、サーバー、ストレージといった要素を含むシステムの一部にすぎません。これらのシステムは複雑であるため、もう一つのベストプラクティスとして、開発/テスト用と本番用で少なくとも別々の stream を用意するなど、環境を分離することが挙げられます。 Decahose には、これらの取り組みを支援するための機能が備わっています。
  1. 複数環境をサポートするため、アカウントに対して Additional Streams をデプロイできます。これらの stream は相互に独立しており、識別のために異なる stream_label が付与されます。
  2. 接続維持を支援するため、各 Decahose stream は 冗長接続 をサポートしています。最も一般的な構成は、1 つの stream に 2 つの接続を持たせ、クライアント側にも 2 つの独立したコンシューマ（理想的には異なるネットワーク上）を用意する形です。この設計により、クライアント側のネットワーク、サーバー、データストア経路にわたって冗長性を確保できます。各接続では data の完全なコピーが配信されるため、クライアント側は重複データを許容し、重複を適切に処理する必要があります。
  3. 「ハートビート」は 10 秒ごとに送信されます。ただし、Decahose stream は data のボリュームが十分に大きいため、短時間（例：数秒）でも Posts が流れない場合は接続問題を示す可能性があります。したがって、「data の沈黙」とハートビートの欠如の両方で切断を検知できます。
切断は避けられないため、Decahose stream には、切断やその他の運用上の問題により取り逃した data の復旧を支援する専用の Recovery および Backfill 機能が用意されています。

​
追加のストリーム

追加の Decahose stream を用意することは、ソリューションの信頼性を高めるもう一つの手段です。追加の stream は完全に独立しており、それぞれに固有の endpoint があります。各 stream には独自の stream_label が割り当てられ、このラベルはアカウント名とともに、その stream の URL の一部になります。以下の例をご覧ください: https://gnip-stream.x.com/stream/sample10/accounts/:account_name/publishers/twitter/:stream_label.json 一般的な慣例としては、本番システム専用のリアルタイム stream と、開発・テスト用の追加の stream を用意します。テスト／開発用の stream によって、Decahose 利用者はクライアントのコンシューマ更新を検証できます。どのような（重複しない）ラベルでも stream に割り当てられますが、慣例として本番用の stream には「prod」、開発用の追加 stream には「dev」または「sandbox」を使用します。 stream の数とその固有ラベルは、担当アカウント代表者によって設定可能です。 冗長接続 冗長接続とは、data stream への同時複数接続を確立できるようにする仕組みです。これにより、同じ stream に別々の二つのコンシューマで接続し、両方の接続から同一の data を受信できるため、冗長性が確保されます。したがって、一方の stream が切断された場合や App のプライマリサーバーが障害を起こした場合などに、ホットフェイルオーバーが可能になります。 特定の stream に許可される接続数は、担当アカウント代表者によって設定可能です。冗長 stream を利用するには、プライマリ接続と同じ URL に接続するだけです。あなたの stream の data は両方の接続を通じて送信され、両方の stream 接続が stream ダッシュボードに表示されます。 課金上は、複数接続で受信したアクティビティ数は重複排除され、各ユニークなアクティビティにつき一度だけ課金される点に留意してください。Decahose には二つのパーティションがあるため、以下は接続数のカウント例です: Connect to decahose partition=1 Connect to decahose partition=1 Connect to decahose partition=2 上記の状況では合計三つの接続となります――partition=1 に二つ、partition=2 に一つの接続です。通常は各パーティションに同数の接続を持つことが望ましいため、この例は partition=2 への冗長接続が切れており、さらなる調査が必要な状況を示しています。 復旧

​
概要 

Recovery はデータ復旧ツールです（一次的なデータ収集には使用しないでください）。直近の X の履歴データについて、ローリングの5日間ウィンドウに対するストリーミングアクセスを提供します。これは、リアルタイムの stream において消費側アプリケーションがデータを取り逃した場合、短時間の切断によるものか、あるいは一定期間リアルタイムデータの取り込みに失敗したその他のあらゆるケースであっても、データを復旧するために利用してください。

​
Recovery の使用

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

​
データの可用性

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

​
バックフィル

バックフィルをリクエストするには、接続リクエストに backfillMinutes=N パラメータを追加します。ここで N は接続時にバックフィルする分数（1～5、整数のみ）です。たとえば 90 秒間切断された場合は、接続リクエストに backfillMinutes=2 を追加します。このリクエストでは切断前の 30 秒を含む 2 分間のバックフィルが提供されるため、コンシューマー App は重複した data を許容できる必要があります。 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’ を使用し、提供される重複した data を処理する方法を取ることもできます。
  • 5 分以上切断された場合は、Recovery を使用して data を回復できます。
切断からの復旧 切断からの再起動および復旧には、いくつかの手順が含まれます:
  • 切断時間の長さを判断する。
    • 5 分以内か？
      • stream で Backfill が有効な場合は、適切な ‘backfillMinutes’ パラメータを含む接続リクエストを準備する。
    • 5 分より長いか？
      • Recovery stream がある場合は、切断期間について Recovery リクエストを行う（必要に応じて Rules API を使用し、可能であれば現在のリアルタイムのルールセットで実施）。
  • 新しい接続をリクエストする。
切断やダウンタイムが発生した場合、この状況を緩和・復旧するための戦略は次のとおりです:
  1. バックフィルの実装 バックフィルにより、stream 接続から切断される前の時点にさかのぼって再接続でき、最大 5 分の切断に対応します。これは接続リクエストにパラメータを含めることで実装されます。
  2. 別拠点から冗長 stream を取り込む 冗長 stream を同じ本番環境にライブで取り込み、data の重複排除ができる場合、通常の stream と冗長 stream の両方で同時にダウンタイムや切断が発生しない限り、Recovery は不要です。冗長 stream を本番環境にライブ取り込みできない場合は、別の「緊急」データストアに書き込むことができます。そうしておけば、プライマリの stream 接続で切断やダウンタイムが発生した際に、欠落期間のプライマリデータベースを補完するための data を手元に確保できます。
  3. Recovery の実装 切断やダウンタイムがプライマリ stream と冗長 stream の両方に影響する場合は、Decahose Recovery を使用して欠落した data を回収します。API はアーカイブの 5 日間のローリングウィンドウを提供しており、そのウィンドウから一度に 1 時間以下の範囲でリクエストし、stream で取り込むのが最適です。これはリアルタイム stream と並行して行います。Recovery が提供する 5 日間のウィンドウを超える Decahose データの復旧手段はないため、重大なダウンタイムに備えて冗長 stream を活用し、あなた側で data の完全なコピーを確保しておくことが重要です。
異常な保存データ量を検知した場合 — 切断やダウンタイムが発生していないのに欠落データを検知する方法の例:
  1. 受信した Posts をカウントする 取り込み App の最初の段階で受信した生の Posts の件数をカウントし、その数値を最終データストアに到達した Posts の件数と比較できるようにします。差分を監視し、受信後に data がドロップされる原因となる問題をチームに通知できます。
  2. 異常な保存量を分析する 最終データベースに保存された data の量を分析し、異常な減少がないか確認することも検討してください。これも問題を示す可能性がありますが、状況によってはボリュームの低下が正常である場合もあります（例: X プラットフォームが利用できず、人々が一定期間 Posts を作成できない場合）。

​
API リファレンス

​
Decahose stream

このページの項目へジャンプ Methods Authentication GET /{stream-type}/:stream Replay API

​
メソッド

メソッド説明
GET /{stream-type}/:streamデータstreamに接続

​
認証

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

​
GET :stream

Firehose stream への永続接続を確立し、この接続を介してリアルタイムの data が配信されます。

​
リクエスト仕様

リクエストメソッドHTTP GET
接続タイプKeep-Alive

これはリクエストのヘッダーで指定する必要があります。
URLダッシュボードのstreamのAPIヘルプページで確認できます。以下の構造を使用します：

Decahose:

https://gnip-stream.x.com/stream/sample10/accounts/:account_name/publishers/twitter/:stream_label.json?partition=1
パーティション（必須）partition=\{#} - 完全なstreamを利用するためにパーティショニングが必須となりました。パーティションパラメータを指定してstreamに接続する必要があります。以下は各streamのパーティション数です：

* Decahose: 2パーティション
圧縮Gzip。Gzip圧縮を使用してstreamに接続するには、接続リクエストでAccept-Encodingヘッダーを送信するだけです。ヘッダーは以下のようになります：

Accept-Encoding: gzip
文字エンコーディングUTF-8
レスポンス形式JSON。リクエストのヘッダーでレスポンスのJSON形式を指定する必要があります。
レートリミット60秒間に10リクエスト。
バックフィルパラメータバックフィルが有効なstreamを購入している場合、GETリクエストに「backfillMinutes」パラメータを追加して有効にする必要があります。
読み取りタイムアウトクライアントで読み取りタイムアウトを設定し、30秒を超える値に設定してください。
Tweet編集のサポートすべてのTweetオブジェクトには、Tweetの編集履歴を記述するTweet編集metadataが含まれます。詳細については、「Edit Tweets」基礎ページを参照してください。

​
レスポンス

これらのリクエストに対して、API は次のレスポンスを返す場合があります。ほとんどのエラーコードには、本文に追加の詳細を含む文字列が含まれます。200 以外のレスポンスの場合、クライアントは再接続を試行してください。
StatusTextDescription
200Success接続は正常に確立され、到着し次第、新しいアクティビティが送信されます。
401Unauthorized無効な認証情報により HTTP 認証に失敗しました。リクエストで認証情報を正しく使用していることを確認するため、console.gnip.com に認証情報でログインしてください。
406Not Acceptable一般的には、クライアントが stream からの gzip エンコーディングを受け入れるためのヘッダーを適切に含めていない場合に発生しますが、他の状況でも発生する可能性があります。

次のような JSON メッセージが含まれます: “This connection requires compression. To enable compression, send an ‘Accept-Encoding: gzip’ header in your request and be ready to uncompress the stream as it is read on the client end.”
429Rate LimitedApp が接続リクエストの上限を超過しました。
503Service UnavailableX サーバー側の問題です。指数バックオフ方式で再接続してください。この問題に関する通知が 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 stream を補完する重要な機能です。Replay はデータ復旧ツールであり、直近の X の履歴データに対するローリングウィンドウへストリーミングでアクセスできます。
⌘I