メインコンテンツへスキップ

​
Timelines エンドポイントを統合する方法

このページでは、Timelines エンドポイントをシステムに統合する際に把握しておくべき各種ツールと主要な概念について説明します。ページは次のセクションで構成されています:

​
便利なツール

いくつかの主要な概念を見ていく前に、これらのエンドポイントの機能をテストし始めるにあたり、以下のツールまたはコードサンプルのいずれかを使用することをおすすめします。 コードサンプル お好みのプログラミング言語で、これらのエンドポイントをコードでセットアップしたい方へ。出発点として使える各種コードサンプルをGitHub ページで提供しています。 ライブラリ 導入の助けとなるコミュニティ製のサードパーティライブラリを活用してください。適切なバージョンタグを確認することで、v2 エンドポイントに対応したライブラリを見つけられます。 Postman Postman は、これらのエンドポイントのテストに最適なツールです。各 Postman リクエストには、利用可能な項目をすばやく把握できるよう、すべてのパスおよびボディパラメータが含まれています。Postman コレクションの詳細は、Using Postmanページをご覧ください。

​
重要な概念

認証 すべての X API v2 エンドポイントでは、キーやトークンとも呼ばれる一連の認証情報を用いた認証済みリクエストが必要です。これらのエンドポイントへのリクエストの認証には、OAuth 1.0a ユーザーコンテキストまたは OAuth 2.0 認可コード（PKCE 対応）のいずれかを使用できます。ユーザーの Post タイムラインおよびユーザーのメンションタイムラインには、OAuth 2.0 App-Only を使用できます。 OAuth 1.0a ユーザーコンテキスト は、API Keys、ユーザーの Access Tokens、その他いくつかのパラメータを使用して認可ヘッダーを作成し、それをリクエストに付与する必要があります。Access Tokens は、あなたが代行してリクエストするユーザーに紐づいている必要があります。別のユーザーの Access Tokens セットを生成したい場合は、そのユーザーが3-legged OAuth フローを用いてあなたのアプリを認可する必要があります。 OAuth 1.0a は扱いが難しい場合がある点にご注意ください。この認証方法に不慣れな場合は、ライブラリの利用、Postman のようなツールの使用、または OAuth 2.0 によるリクエストの認証を推奨します。これらのエンドポイントから Post や非公開メトリクスを取得する場合は、OAuth 1.0a ユーザーコンテキストまたは OAuth 2.0 認可コード（PKCE 対応）のいずれかを使用する必要があり、コンテンツの所有者であるユーザーから適切な権限を得ていることを担保します。 OAuth 2.0 App-Only は、リクエストにOAuth 2.0 App Access Tokenを付与するだけで済みます。開発者アプリ内から直接 App Access Token を生成するか、POST oauth2/token エンドポイントで生成できます。これはユーザーの Post タイムラインやユーザーのメンションタイムラインに使用できます。 OAuth 2.0 認可コード（PKCE 対応） は、アプリケーションのスコープに対するより細かな制御や、複数デバイス間での認可フローを可能にします。OAuth 2.0 では、ユーザーに代わって特定の権限を付与する細分化されたスコープを選択できます。 アプリで OAuth 2.0 を有効にするには、開発者ポータルの App 設定セクションにあるアプリの認証設定で有効化する必要があります。
ご注意次のfieldsをリクエストする場合は、OAuth 1.0a ユーザーコンテキストまたは OAuth 2.0 認可コードが必要です: 
  • tweet.fields.non_public_metrics
  • tweet.fields.promoted_metrics
  • tweet.fields.organic_metrics
  • media.fields.non_public_metrics
  • media.fields.promoted_metrics
  • media.fields.organic_metrics
開発者ポータル、プロジェクト、開発者アプリ X API v2 のエンドポイントを利用するには、開発者アカウントに登録し、そのアカウント内でプロジェクトを設定し、そのプロジェクト内に開発者アプリを作成する必要があります。その開発者アプリ内のキーとトークンは、これらのタイムラインエンドポイントで使用できます。 レート制限 毎日、何千人もの開発者が X API にリクエストを送信しています。トラフィックを管理するために、各エンドポイントにはレート制限が設けられており、アプリまたは認証済みユーザーに代わって各開発者が行えるリクエスト数を制限しています。 これらのエンドポイントには、使用する認証方法に応じて異なるレート制限が適用されます。アプリレベルのレート制限は OAuth 2.0 App-Only でリクエストを行うアプリに適用され、ユーザーレベルのレート制限は OAuth 1.0a ユーザーコンテキストで特定の認可ユーザーに代わって行われるリクエストに適用されます。これら 2 種類のレート制限は、15 分間のウィンドウ内でのリクエスト頻度に基づきます。 例えば、これら両方のタイムラインエンドポイントで OAuth 2.0 App-Only 認証を使用するアプリは、15 分間の枠内でユーザーの Post タイムラインに 1,500 件（ページネーションを含む）、ユーザーメンションタイムラインに 450 件（ページネーションを含む）のリクエストを行えます。 同じアプリでも、同一の 15 分間に、2 人の異なる認可済みユーザー（OAuth 1.0a ユーザーコンテキストを使用）ごとに、ユーザーの Post タイムラインに 900 件（ページネーションを含む）、ユーザーメンションタイムラインに 180 件（ページネーションを含む）のリクエストを行えます。 逆時系列のホームタイムラインには、ユーザーごとに 15 分あたり 180 リクエストのレート制限があります。このエンドポイントでは、直近 7 日間にタイムラインで作成されたすべての Post に加え、作成日時に関わらず最新の 800 件を返せます。 Fields と expansions X API v2 では、fields と expansions を使用して、API から返す data を正確に指定できます。expansions パラメータを使用すると、ペイロード内で参照されているオブジェクトを展開できます。例えば、このエンドポイントでは、expansions パラメータを使用して poll、place、media などのオブジェクトをリクエストできます。 fields パラメータを使用すると、各種 data オブジェクト内のどの fields を受け取るかを正確に指定できます。デフォルトでは、これらのエンドポイントから返される主要な Post オブジェクトには、id と text の fields が含まれます。author_id や public_metrics などの追加の fields を受け取るには、fields パラメータで明示的にリクエストする必要があります。インテグレーションでの利用を検討すべき重要な fields として、poll の data、metrics、Post annotations、conversation ID などがあります。 fields と expansions の使い方を解説したガイドを、X API v2 data dictionaryに追加しました。 Post メトリクス X API v2 の各エンドポイントでは、リクエストで適切な fields を指定していれば、返される Post オブジェクトから直接 Post メトリクスを取得できます。 ユーザープライバシーに関連して、以下のレスポンス fields にはいくつかの制限があります。
  • tweet.fields.non_public_metrics
  • tweet.fields.promoted_metrics
  • tweet.fields.organic_metrics
  • media.fields.non_public_metrics
  • media.fields.promoted_metrics
  • media.fields.organic_metrics
これらの fields には非公開のメトリクス data が含まれるため、ユーザーの Post タイムラインエンドポイントを使用して当該 data を代理取得するには、Post の投稿者からの認可が必要であり、OAuth 1.0a User Context または OAuth 2.0 Authorization Code Flow with PKCE を使用する必要があります。 例えば、ユーザー ID 1234 のユーザー Post タイムラインで non_public_metrics を取得するには、そのユーザーに紐づくアクセストークンをリクエストに含める必要があります。3-legged OAuth フローを使用すれば、ユーザーにアプリを認可してもらい、そのユーザーに紐づく一連のアクセストークンを取得できます。 ユーザーメンションタイムラインを使用している場合、メンションした投稿者がアプリに対して自分の非公開メトリクス data へのアクセスを認可し、かつ OAuth 1.0a ユーザーコンテキストで当該ユーザーのアクセストークンを用いてリクエストする場合を除き、これらの fields は利用できません。 non_public_metrics、organic_metrics、promoted_metrics は、過去 30 日以内に作成された Posts に対してのみ提供されます。つまり、これらの fields をリクエストする場合、結果は自動的に過去 30 日以内の Posts のみに調整されます。 これらの fields がリクエストされた場合は、認証済みユーザーが作成した Posts のみが返され、それ以外の Posts についてはエラーが返されます。 ページネーション これらのエンドポイントはページネーションを使用して、レスポンスを迅速に返します。単一のレスポンスで送信できる結果数（タイムラインエンドポイントでは最大 100 件の Posts）を超える場合は、ページネーションが必要です。max_results パラメータで 1 ページあたりの件数を指定し、pagination_token パラメータで次ページの結果を取得します。詳細は ページネーションガイドをご覧ください。 結果のフィルタリング これらのエンドポイントには、結果をフィルタリングするために使用できる複数のパラメータがあります。start_date と end_date を使うと、結果を特定の期間に絞り込めます。特定の Post の集合を選択するために Post の ID を使いたい場合は、since_id と until_id を使用できます。ユーザーの Post タイムラインには exclude パラメータもあり、結果から Retweet と Reply を除外できます。  Post の上限と返される Post の件数 ユーザーの Post タイムラインおよびユーザーのメンションタイムラインの各エンドポイントには、月ごとに返せる Post の件数に制限があります。逆時系列のホームタイムライン・エンドポイントにはこの制限は適用されません。 どのタイムライン・エンドポイントを使用しても、返された Post はプロジェクトレベルのPost 上限にカウントされます。使用状況は開発者ポータルに表示され、「月」はdeveloper portal dashboardに表示されるサブスクリプションの更新日から始まります。  ユーザーの Post タイムライン・エンドポイントは、ユーザーのタイムラインに投稿された直近の 3200 件の Post のみを返します。start_time と end_time を直近 3200 件を超える期間に設定した場合、レスポンス自体は成功しますが、Post は返されません。 また、ユーザーの Post タイムラインのリクエストで excludes=replies を指定した場合、直近 800 件の Post のみが返される点にも注意してください。 ユーザーのメンションタイムライン・エンドポイントは、直近の 800 件の Post メンションのみを返します。 逆時系列のホームタイムライン・エンドポイントは、直近の 3200 件の Post を返します。 Post の編集 編集可能な Post は、元の Post が公開されてから 30 分間に最大 5 回まで編集できます。検索エンドポイントは常に Post の最新バージョンを返します。公開から 30 分以上経過した Post のみをリクエストする場合は、常に最終版の Post を受け取ります。ただし、ほぼリアルタイムのユースケースで公開後 30 分以内の Post を照会する場合、それらの Post は受信後に編集されている可能性があります。これらの Post は検索、または Post Lookup エンドポイントで再取得して最終状態を確認できます。Post の編集の仕組みについては、Edit Posts fundamentals ページをご覧ください。   イレギュラーケース
  • ユーザーの Post タイムライン・エンドポイントで、30 日より前の Post に対して非公開メトリクスをリクエストする場合、結果数が 0 の next_token がレスポンスに含まれることがあります。この問題を回避するには、non_public_metrics パラメータで指定する期間を直近 30 日以内にしてください。加えて、max_results の最小値は 10 としてください。これらは回避に役立つ可能性がありますが、それでも発生することがあります。
  • プロモーションされていない Post に対してプロモート済みメトリクスをリクエストすると、Post の data ではなく空のレスポンスが返されます。現在この問題の修正に取り組んでいます。
  • 本文テキストが 140 文字を超える Post を含む Retweet では、Post の全文を返す代わりに text フィールドが切り詰められます。短期的な回避策としては、参照された Post を展開し、その拡張から全文を取得してください。これは将来的に修正予定のバグです。
次のステップ [タイムライン・エンドポイントへの最初のリクエストを行う]/x-api/posts/timelines#getting-started-with-reverse-chronological-home-timeline “タイムライン・エンドポイントへの最初のリクエストを行う”) API Reference ページでパラメータ、fields などの完全な一覧を見る サポートを受ける、またはエラーをトラブルシュートする