統合ガイド

このページでは、リストメンバーエンドポイントとの連携に役立つツールと主要な概念について説明します。

---

​

便利なツール

このエンドポイントを統合するうえで役立つ、いくつかの重要な概念に入る前に、まず次のツールに慣れておくことをおすすめします。

​

Postman

Postman は、エンドポイントをテストするのに便利なツールです。各 Postman リクエストには、何が利用できるかをすばやく把握できるよう、すべてのパスおよびボディパラメータが含まれています。Postman コレクションの詳細については、“Using Postman” ページをご覧ください。

​

コードサンプル

お好みのプログラミング言語でこのエンドポイントを使い始める際の参考コードをお探しですか？GitHub ページで、出発点として利用できるコードサンプルをいくつかご用意しています。

​

サードパーティライブラリ

コミュニティが提供する サードパーティライブラリ を活用して、スムーズに始めましょう。v2 エンドポイントに対応したライブラリは、対応するバージョンタグを確認することで見つけることができます。

---

​

基本概念

​

認証

すべての X API v2 エンドポイントでは、リクエストを認証するための一連の認証情報 (キーおよびトークンとも呼ばれます) が必要です。リストの lookup エンドポイントに対してリクエストを認証するには、OAuth 1.0a User Context、OAuth 2.0 Authorization Code with PKCE、または App only のいずれかを使用できます。ただし、リストの manage エンドポイントでは、OAuth 1.0a User Context または OAuth 2.0 で認証する必要があります。

OAuth 1.0a User Context では、API Key とユーザー Access Token のセットを使用して、リクエストを成功させる必要があります。Access Token は、代理でリクエストを行う対象のユーザーに関連付けられていなければなりません。別のユーザーの Access Token セットを生成したい場合は、そのユーザーが 3-legged OAuth フロー を用いて App を承認する必要があります。

OAuth 1.0a は扱いが難しい場合があることに注意してください。この認証方式に慣れていない場合は、ライブラリ を利用するか、Postman のようなツールを使うか、あるいは OAuth 2.0 または App only のいずれかを使用してリクエストを認証することをお勧めします。

OAuth 2.0 Authorization Code with PKCE は、アプリケーションのスコープや複数デバイス間の認可フローをより細かく制御できるようにします。OAuth 2.0 では、ユーザーに代わって特定の権限を付与するきめ細かいスコープを個別に選択できます。

App で OAuth 2.0 を有効にするには、開発者コンソールの App 設定セクションにあるその App の認証設定で OAuth 2.0 を有効にする必要があります。

App only では、リクエストに App only Access Token を渡すだけで済みます。App only Access Token は、開発者 App 内で直接生成するか、POST oauth2/token エンドポイントを使用して生成できます。

​

開発者コンソール、Project、および開発者 App

X API v2 エンドポイントで使用できる認証情報セットを取得するには、まず開発者アカウントに登録し、そのアカウント内にProjectを作成し、その Project 内に開発者 Appを作成する必要があります。これらを作成した後、開発者 App 内でキーとトークンを確認できます。

​

レート制限

毎日、何万もの開発者が X API にリクエストを送信しています。これらの膨大なリクエスト量を管理するために、各エンドポイントには レート制限 が設定されており、あなたのアプリや認証済みユーザーの代理として実行できるリクエスト数が制限されています。

Lookup (GET) エンドポイントには App レベルとユーザーレベルの両方でレート制限があり、manage (POST/DELETE) エンドポイントにはユーザーレベルでのみレート制限があります。App のレート制限とは、開発者であるあなたが、いずれかの App (API Key と API Secret Key、または App only Access Token を使用していると見なされます) から、一定期間内にそのエンドポイントへ送信できるリクエスト数が決まっていることを意味します。ユーザーのレート制限とは、あなたが代理でリクエストを送信している認証済みユーザーが、どの開発者の App からリクエストした場合でも、List の Lookup を行える回数が一定数に制限されることを意味します。

以下の表は、各エンドポイントのレート制限を示しています。

Endpoint	HTTP method	Rate limit
/2/lists/:id/members	GET	15 分あたり 900 件のリクエスト
/2/users/:id/list_memberships	GET	15 分あたり 75 件のリクエスト
/2/lists/:id/members	POST	15 分あたり 300 件のリクエスト
/2/lists/:id/members/:user_id	DELETE	15 分あたり 300 件のリクエスト

​

フィールドと Expansions

X API v2 の GET エンドポイントでは、fields と expansions と呼ばれる一連のツールを使って、API から返したいデータを正確に指定できます。expansions パラメータを使用すると、ペイロード内で参照されているオブジェクトを展開できます。たとえば、リストメンバーのルックアップでは、次のような expansions を取得できます。

• pinned_tweet_id

fields パラメータを使用すると、受け取りたい各種データオブジェクト内のどの fields を取得するかを正確に指定できます。リストメンバーのルックアップでは、主にユーザーオブジェクトが返されます。デフォルトでは、ユーザーオブジェクトは id、name、username フィールドを返します。user.created_at や user.description などの追加のフィールドを受け取るには、user.fields パラメータを使って明示的にリクエストする必要があります。

fields と expansions の使い方に関するガイドも用意しています。

以下の表は、各ルックアップエンドポイントで利用可能な fields と expansions を示しています。

Endpoint	Fields	Expansions
/2/lists/:id/members	user.fields, tweet.fields	pinned_tweet_id
/2/users/:id/list_memberships	list.fields, user.fields	owner_id

​

ページネーション

membership/members の取得では、多くのデータが返される場合があります。常に一貫性があり高パフォーマンスな結果を返せるようにするために、ページネーションを使用します。ページネーションは、単一のレスポンスで返せる件数を超える結果を返す X API v2 エンドポイントの機能です。このような場合、データは一連の「ページ」に分割されて返されます。結果をページネーションする方法について詳しくご覧ください。