メインコンテンツへスキップ
このページでは、最近の検索または全アーカイブ検索のエンドポイントをシステムに統合する際に把握しておくべきツールや主要概念について説明します。ページは次のセクションに分かれています。
主要な概念を見ていく前に、これらのエンドポイントの機能をテストするため、次のいずれかのツールまたはコードサンプルの利用を推奨します。
お使いのプログラミング言語でこれらのエンドポイントをすぐに使い始めたい方へ。GitHub ページに、導入の出発点として利用できる各種コードサンプルをご用意しています。Python クライアントや Ruby クライアントも含まれています。
作業を始める際は、数多くあるコミュニティ提供のサードパーティライブラリのいずれかをご活用ください。適切なバージョンタグを確認すれば、v2 エンドポイントに対応するライブラリを見つけられます。
Postman は、これらのエンドポイントの動作を検証するのに適したツールです。各 Postman リクエストには、そのエンドポイントで指定可能なすべてのパラメータが含まれており、利用できる項目を素早く把握するのに役立ちます。Postman コレクションの詳細は、Postman の使い方 をご覧ください。
すべての X API v2 エンドポイントでは、リクエストを認証するために、キーとトークンとしても知られる一連の認証情報が必要です。recent search エンドポイントへのリクエストの認証には、OAuth 1.0a User Context、OAuth 2.0 App-Only、または OAuth 2.0 認可コード（PKCE）のいずれかを使用できます。full archive search エンドポイントを使用する場合は、OAuth 2.0 App-Only を使用する必要があります。
OAuth 2.0 App-Only は、リクエストに OAuth 2.0 App Access Token を付与するだけで利用できます。App Access Token は、Developer App から直接生成するか、POST oauth2/token エンドポイントで生成できます。
OAuth 1.0a User Context では、API キー、ユーザーのアクセストークン、その他のパラメータを用いて認可ヘッダーを作成し、それをリクエストに付与する必要があります。アクセストークンは、あなたが代理してリクエストを行うユーザーに紐づいている必要があります。別のユーザーのアクセストークン一式を生成したい場合は、そのユーザーが 3-legged OAuth フロー を使用してあなたの App を承認する必要があります。
OAuth 1.0a は扱いが難しい場合があります。この認証方法に不慣れな場合は、ライブラリ を使う、Postman のようなツールを使う、あるいは OAuth 2.0 でリクエストを認証することをお勧めします。これらのエンドポイントからポストや非公開メトリクスをリクエストする場合は、コンテンツの所有者であるユーザーから適切な許可を得るために、OAuth 1.0a User Context または OAuth 2.0 認可コード（PKCE）のいずれかを使用する必要があります。
OAuth 2.0 認可コード（PKCE） は、アプリケーションのスコープや複数デバイス間にまたがる認可フローをより細かく制御できます。OAuth 2.0 では、ユーザーに代わって特定の権限を付与する、きめ細かなスコープを選択できます。
App で OAuth 2.0 を有効にするには、開発者ポータルの App 設定セクションにある認証設定で有効化してください。
ご注意ください以下のフィールドをリクエストする場合は、OAuth 1.0a User Context または OAuth 2.0 Authorization Code が必要です。
- 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
- 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
これらのフィールドには非公開のメトリクス データが含まれるため、recent search エンドポイントを使用する際には、ポストの投稿者から代理取得の許可を得ている必要があり、そのためにはOAuth 1.0a User Contextを使用する必要があります。recent search でのみこの認証方式を使用できるため、full archive search エンドポイント経由ではこれらのメトリクスを取得できません。
たとえば、ユーザー ID 1234 のポストに対する non_public_metrics を取得するには、そのユーザーに紐づくアクセストークンをリクエストに含める必要があります。3-legged OAuth フローを使用すると、ユーザーにアプリを認可してもらい、そのユーザーに紐づくアクセストークン一式を受け取れます。
non_public_metrics、organic_metrics、および promoted_metrics は、直近 30 日以内に作成されたポストに対してのみ利用可能です。つまり、これらのフィールドをリクエストすると、結果は自動的に直近 30 日のポストのみに絞り込まれます。
これらのフィールドがリクエストされた場合、認証済みユーザーが作成したポストのみが返され、それ以外のポストにはエラーメッセージが返されます。
これらのエンドポイントの中核となる機能は、単一の検索クエリで配信対象の投稿を絞り込むことです。クエリは、メッセージのキーワード、ハッシュタグ、URL など、ポストやユーザーの属性に一致するオペレーターの組み合わせで構成されます。オペレーターはブール論理や括弧と組み合わせてクエリを構築でき、マッチングの挙動をより精緻に制御できます。
詳しくは、クエリの構築方法のガイドをご覧ください。
これらのエンドポイントは、レスポンスを迅速に返すためページネーションを利用します。単一のレスポンスで送信できる件数を超える場合（最近の検索は最大100件のポスト、全アーカイブ検索は最大500件）には、ページネーションが必要です。1ページあたりの件数を指定するには max_results パラメータを、次ページの結果を取得するには pagination_token パラメータを使用してください。詳しくは当社のpagination guideをご覧ください。
Search Posts エンドポイントは、ページネーションに関係なく、各月に返せる投稿数に上限があります。
どの検索エンドポイントを使用しても、返される投稿はプロジェクト単位のポスト上限にカウントされます。利用状況は開発者ポータルに表示され、「月」は開発者ポータルのダッシュボードに表示されるサブスクリプションの更新日を起点とします。
ポストの編集
編集可能な投稿は、元のポストの公開後30分間に最大5回まで編集できます。検索エンドポイントは常にポストの最新バージョンを返します。公開から30分以上経過した投稿のみをリクエストする場合は、常にポストの最終バージョンを受け取ります。ただし、ほぼリアルタイムのユースケースで、直近30分以内に公開された投稿をクエリしている場合、受信後に編集されている可能性があります。これらの投稿は、最終状態を確認するために検索または Post Lookup エンドポイントでリハイドレート（再取得）できます。ポストの編集の仕組みについては、ポスト編集の基礎をご覧ください。
次のステップ
Search Posts エンドポイントへの最初のリクエストを行う
API リファレンスでパラメータ、フィールドなどの全一覧を見る
サポートの取得またはエラーのトラブルシューティング 
