連携ガイド

​

統合ガイド

このページでは、List メンバーのendpointをシステムに統合する際に把握しておくべき各種ツールと重要な概念について説明します。内容は次のセクションに分かれています。

• 便利なツール
• 重要な概念
• 認証
• developer portal、Projects、Apps
• レートリミット
• Fields と expansions
• ページネーション

​

役立つツール

この endpoint を統合する際に役立つ主要な概念に入る前に、以下に慣れておくことをおすすめします。

​

Postman

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

​

コードサンプル

お好みのプログラミング言語でこの endpoint を使い始めたい方のために、出発点として使えるコードサンプルをいくつかGitHub ページで公開しています。

​

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

コミュニティ提供のサードパーティ製ライブラリを活用して、スムーズに開始しましょう。適切なバージョンタグを確認すれば、v2 の endpoint に対応するライブラリを見つけられます。

​

重要な概念

​

認証

すべての X API v2 endpoint では、リクエストを認証するために、キーおよびトークンとしても知られる一連の認証情報が必要です。Lists の lookup endpoint に対するリクエストの認証には、OAuth 1.0a ユーザーコンテキスト、OAuth 2.0 Authorization Code（PKCE 付き）、または App only のいずれかを使用できます。ただし、manage Lists endpoint については、OAuth 1.0a ユーザーコンテキストまたは OAuth 2.0 による認証が必須です。

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

OAuth 1.0a は扱いが難しい場合があります。この認証方式に不慣れな場合は、library を利用する、Postman のようなツールを使う、または OAuth 2.0 もしくは App only でリクエストを認証することを推奨します。

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

App で OAuth 2.0 を有効にするには、developer portal の App 設定セクションにある認証設定で有効化してください。

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

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

​

developer portal、Project、および開発者用 App

X API v2 の endpoint で使用できる認証情報一式を取得するには、デベロッパーアカウントに登録し、そのアカウント内に Project を作成し、その Project 内に 開発者用 App を作成する必要があります。作成後は、開発者用 App 内でキーおよびトークンを確認できます。  

​

レートリミット

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

Lookup（GET）endpoint は App レベルとユーザーレベルの両方でレート制限されます。一方、manage（POST/DELETE）endpoint はユーザーレベルで制限されます。App レートリミットとは、開発者であるあなたが、任意の App（API Key と API Secret Key、または App only Access Token のいずれかを使用する想定）から、一定期間内に当該 endpoint へ送信できるリクエスト数が制限されることを意味します。ユーザーレートリミットとは、あなたが代わってリクエストを行う認証済みユーザーが、どの開発者用 App であっても一定回数のみ List のルックアップを実行できることを意味します。

以下の表は、各 endpoint のレートリミットを示しています。

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 リクエスト

​

fields と expansions

X API v2 の GET endpoint では、fields と expansions という一連の機能を用いて、API から返す data を正確に選択できます。expansions パラメータは、ペイロード内で参照されているオブジェクトを展開して取得できるようにします。たとえば、List メンバーの参照では、次の expansions を取得できます:

• pinned_tweet_id

fields パラメータでは、受け取りたい各種データオブジェクト内の特定の fields を選択できます。List メンバーの参照では、主に ユーザーオブジェクト が返されます。デフォルトでは、ユーザーオブジェクトは id、name、username の fields を返します。user.created_at や user.description などの追加の fields を取得するには、user.fields パラメータで明示的にリクエストする必要があります。 

fields と expansions の使用方法に関するガイドを追加しました。

以下の表は、各参照 endpoint で利用可能な field と 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 の endpoint に備わる機能です。その場合、data は一連の「ページ」に分割されて返されます。結果のページネーション方法の詳細をご確認ください。